# Introduction (/docs/cross-chain)

---
title: Introduction
description: Learn about different interoperability protocols in the Lux ecosystem.
---

<Cards>
<Card title="Lux Interchain Messaging" description="Learn about Lux Interchain Messaging, a protocol for cross-chain communication." href="/docs/cross-chain/lux-warp-messaging/overview" />

<Card title="ICM Contracts" description="Learn about ICM Contracts, a protocol for cross-chain communication between EVM Chains." href="/docs/cross-chain/teleporter/overview" />

<Card title="Interchain Token Transfer" description="Learn about Lux Interchain Token Transfer (ICTT), a protocol for transferring tokens between Lux L1s." href="/docs/cross-chain/interchain-token-transfer/overview" />
</Cards>


# Lux Proposals (LPs) (/docs/lps)

---
title: Lux Proposals (LPs)
description: Official Lux Proposals for network improvements and best practices
icon: FileText
---

# Lux Proposals (LPs)

Lux Proposals (LPs) are the primary mechanism for proposing new features, collecting community input, and documenting design decisions for the Lux Network.

## Browse LPs

Visit [lps.lux.network](https://lps.lux.network) for the complete list of Lux Proposals.

## LP Categories

### Standards Track LPs
These LPs describe changes to the Lux protocol, including:
- Core protocol changes
- Networking improvements
- Interface standards
- EVM updates

### Best Practices Track LPs
These LPs describe recommended patterns and guidelines for building on Lux.

### Meta Track LPs
These LPs describe process and governance for the LP system itself.

## Contributing

To propose a new LP, visit the [LPs repository](https://github.com/luxfi/lps) and follow the contribution guidelines.


# Lux L1s (/docs/lux-l1s)

---
title: Lux L1s
description: Explore the multi-chain architecture of Lux ecosystem.
---

An Lux L1 is a sovereign network which defines its own rules regarding its membership and token economics. It is composed of a dynamic subset of Lux validators working together to achieve consensus on the state of one or more blockchains. Each blockchain is validated by exactly one Lux L1, while an Lux L1 can validate many blockchains.

Lux's [Primary Network](/docs/primary-network) is a special Lux L1 running three blockchains:

- The Platform Chain [(Platform-Chain)](/docs/primary-network#p-chain-platform-chain)
- The Contract Chain [(LUExchange-Chain)](/docs/primary-network#c-chain-contract-chain)
- The Exchange Chain [(Exchange-Chain)](/docs/primary-network#x-chain-exchange-chain)

![image](/images/subnet1.png)

<Callout title="Note">
Every validator of an Lux L1 **must** sync the Platform-Chain of the Primary Network for interoperability.
</Callout>

Node operators that validate an Lux L1 with multiple chains do not need to run multiple machines for validation. For example, the Primary Network is an Lux L1 with three coexisting chains, all of which can be validated by a single node, or a single machine.

## Advantages

### Independent Networks

- Lux L1s use virtual machines to specify their own execution logic, determine their own fee regime, maintain their own state, facilitate their own networking, and provide their own security.
- Each Lux L1's performance is isolated from other Lux L1s in the ecosystem, so increased usage on one Lux L1 won't affect another.
- Lux L1s can have their own token economics with their own native tokens, fee markets, and incentives determined by the Lux L1 deployer.
- One Lux L1 can host multiple blockchains with customized [virtual machines](/docs/primary-network/virtual-machines).

### Native Interoperability

Lux Warp Messaging enables native cross-Lux L1 communication and allows Virtual Machine (VM) developers to implement arbitrary communication protocols between any two Lux L1s.

### Accommodate App-Specific Requirements

Different blockchain-based applications may require validators to have certain properties such as large amounts of RAM or CPU power.

an Lux L1 could require that validators meet certain [hardware requirements](/docs/nodes/system-requirements#hardware-and-operating-systems) so that the application doesn't suffer from low performance due to slow validators.

### Launch Networks Designed With Compliance

Lux's L1 architecture makes regulatory compliance manageable. As mentioned above, an Lux L1 may require validators to meet a set of requirements.

Some examples of requirements the creators of an Lux L1 may choose include:

- Validators must be located in a given country.
- Validators must pass KYC/AML checks.
- Validators must hold a certain license.

### Control Privacy of On-Chain Data

Lux L1s are ideal for organizations interested in keeping their information private.

Institutions conscious of their stakeholders' privacy can create a private Lux L1 where the contents of the blockchains would be visible only to a set of pre-approved validators.

Define this at creation with a [single parameter](/docs/nodes/configure/lux-l1-configs#private-lux-l1).

### Validator Sovereignty

In a heterogeneous network of blockchains, some validators will not want to validate certain blockchains because they simply have no interest in those blockchains.

The Lux L1 model enables validators to concern themselves only with blockchain networks they choose to participate in. This greatly reduces the computational burden on validators.

## Why Build Your Own Lux L1

There are many advantages to running your own Lux L1. If you find one or more of these a good match for your project then an Lux L1 might be a good solution for you.

### We Want Our Own Gas Token

LUExchange-Chain is an Ethereum Virtual Machine (EVM) chain; it requires the gas fees to be paid in its native token. That is, the application may create its own utility tokens (ERC-20) on the LUExchange-Chain, but the gas must be paid in LUX. In the meantime, [Subnet-EVM](https://github.com/luxfi/subnet-evm) effectively creates an application-specific EVM-chain with full control over native(gas) coins. The operator can pre-allocate the native tokens in the chain genesis, and mint more using the [Subnet-EVM](https://github.com/luxfi/subnet-evm) precompile contract. And these fees can be either burned (as LUX burns in LUExchange-Chain) or configured to be sent to an address which can be a smart contract.

Note that the Lux L1 gas token is specific to the application in the chain, thus unknown to the external parties. Moving assets to other chains requires trusted bridge contracts (or upcoming cross Lux L1 communication feature).

### We Want Higher Throughput

The primary goal of the gas limit on LUExchange-Chain is to restrict the block size and therefore prevent network saturation. If a block can be arbitrarily large, it takes longer to propagate, potentially degrading the network performance. The LUExchange-Chain gas limit acts as a deterrent against any system abuse but can be quite limiting for high throughput applications. Unlike LUExchange-Chain, Lux L1 can be single-tenant, dedicated to the specific application, and thus host its own set of validators with higher bandwidth requirements, which allows for a higher gas limit thus higher transaction throughput. Plus, [Subnet-EVM](https://github.com/luxfi/subnet-evm) supports fee configuration upgrades that can be adaptive to the surge in application traffic.

Lux L1 workloads are isolated from the Primary Network; which means, the noisy neighbor effect of one workload (for example NFT mint on LUExchange-Chain) cannot destabilize the Lux L1 or surge its gas price. This failure isolation model in the Lux L1 can provide higher application reliability.

### We Want Strict Access Control

The LUExchange-Chain is open and permissionless where anyone can deploy and interact with contracts. However, for regulatory reasons, some applications may need a consistent access control mechanism for all on-chain transactions. With [Subnet-EVM](https://github.com/luxfi/subnet-evm), an application can require that "only authorized users may deploy contracts or make transactions." Allow-lists are only updated by the administrators, and the allow list itself is implemented within the precompile contract, thus more transparent and auditable for compliance matters.

### We Need EVM Customization

If your project is deployed on the LUExchange-Chain then your execution environment is dictated by the setup of the LUExchange-Chain. Changing any of the execution parameters means that the configuration of the LUExchange-Chain would need to change, and that is expensive, complex and difficult to change. So if your project needs some other capabilities, different execution parameters or precompiles that LUExchange-Chain does not provide, then Lux L1s are a solution you need. You can configure the EVM in an Lux L1 to run however you want, adding precompiles, and setting runtime parameters to whatever your project needs.

### We Need Custom Validator Management

With the Etna upgrade, L1s can implement their own validator management logic through a _ValidatorManager_ smart contract. This gives you complete control over your validator set, allowing you to define custom staking rules, implement permissionless proof-of-stake with your own token, or create permissioned proof-of-authority networks. The validator management can be handled directly through smart contracts, giving you programmatic control over validator selection and rewards distribution.

### We Want to Build a Sovereign Network

L1s on Lux are truly sovereign networks that operate independently without relying on other systems. You have complete control over your network's consensus mechanisms, transaction processing, and security protocols. This independence allows you to scale horizontally without dependencies on other networks while maintaining full control over your network parameters and upgrades. This sovereignty is particularly important for projects that need complete autonomy over their blockchain's operation and evolution.

## When to Choose an Lux L1

Here we presented some considerations in favor of running your own Lux L1 vs. deploying on the LUExchange-Chain.

If an application has relatively low transaction rate and no special circumstances that would make the LUExchange-Chain a non-starter, you can begin with LUExchange-Chain deployment to leverage existing technical infrastructure, and later expand to an Lux L1. That way you can focus on working on the core of your project and once you have a solid product/market fit and have gained enough traction that the LUExchange-Chain is constricting you, plan a move to your own Lux L1.

Of course, we're happy to talk to you about your architecture and help you choose the best path forward. Feel free to reach out to us on [Discord](https://chat.avalabs.org/) or other [community channels](https://www.lux.network/community) we run.

## Develop Your Own Lux L1

Lux L1s on Lux are deployed by default with [Subnet-EVM](https://github.com/luxfi/subnet-evm#subnet-evm), a fork of go-ethereum. It implements the Ethereum Virtual Machine and supports Solidity smart contracts as well as most other Ethereum client functionality.

To get started, check out our [L1 Toolbox](/tools/l1-toolbox) or the tutorials in the [Lux CLI](/docs/tooling/lux-cli) section.


# Simple VM in Any Language (/docs/lux-l1s/simple-vm-any-language)

---
title: Simple VM in Any Language
description: Learn how to implement a simple virtual machine in any language.
---

This is a language-agnostic high-level documentation explaining the basics of how to get started at implementing your own virtual machine from scratch.

Lux virtual machines are grpc servers implementing Lux's [Proto interfaces](https://buf.build/luxfi/lux). This means that it can be done in [any language that has a grpc implementation](https://grpc.io/docs/languages/).

## Minimal Implementation

To get the process started, at the minimum, you will to implement the following interfaces:

- [`vm.Runtime`](https://buf.build/luxfi/lux/docs/main:vm.runtime) (Client)
- [`vm.VM`](https://buf.build/luxfi/lux/docs/main:vm) (Server)

To build a blockchain taking advantage of LuxGo's consensus to build blocks, you will need to implement:

- [AppSender](https://buf.build/luxfi/lux/docs/main:appsender) (Client)
- [Messenger](https://buf.build/luxfi/lux/docs/main:messenger) (Client)

To have a json-RPC endpoint, `/ext/bc/subnetId/rpc` exposed by LuxGo, you will need to implement:

- [`Http`](https://buf.build/luxfi/lux/docs/main:http) (Server)

You can and should use a tool like `buf` to generate the (Client/Server) code from the interfaces as stated in the [Lux module](https://buf.build/luxfi/lux)'s page.

<Callout title="Note">
There are _server_ and _client_ interfaces to implement. LuxGo calls the _server_ interfaces exposed by your VM and your VM calls the _client_ interfaces exposed by LuxGo.
</Callout>

## Starting Process

Your VM is started by LuxGo launching your binary. Your binary is started as a sub-process of LuxGo. While launching your binary, LuxGo passes an environment variable `LUX_VM_RUNTIME_ENGINE_ADDR` containing an url. We must use this url to initialize a `vm.Runtime` client.

Your VM, after having started a grpc server implementing the VM interface must call the [`vm.Runtime.InitializeRequest`](https://buf.build/luxfi/lux/docs/main:vm.runtime#vm.runtime.InitializeRequest) with the following parameters.

- `protocolVersion`: It must match the `supported plugin version` of the [LuxGo release](https://github.com/luxfi/LuxGo/releases) you are using. It is always part of the release notes.  
- `addr`: It is your grpc server's address. It must be in the following format `host:port` (example `localhost:12345`)
    
## VM Initialization

The service methods are described in the same order as they are called. You will need to implement these methods in your server.

### Pre-Initialization Sequence

LuxGo starts/stops your process multiple times before launching the real initialization sequence.

1. [VM.Version](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.Version)
    - Return: your VM's version.
2. [VM.CreateStaticHandler](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.CreateStaticHandlers)
    - Return: an empty array - (Not absolutely required).
3. [VM.Shutdown](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.Shutdown)
    - You should gracefully stop your process.
    - Return: Empty

### Initialization Sequence

1. [VM.CreateStaticHandlers](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.CreateStaticHandlers)
    - Return an empty array - (Not absolutely required).
2. [VM.Initialize](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.Initialize)
    - Param: an [InitializeRequest](https://buf.build/luxfi/lux/docs/main:vm#vm.InitializeRequest).
    - You must use this data to initialize your VM.
    - You should add the genesis block to your blockchain and set it as the last accepted block.
    - Return: an [InitializeResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.InitializeResponse) containing data about the genesis extracted from the `genesis_bytes` that was sent in the request.
3. [VM.VerifyHeightIndex](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.VerifyHeightIndex)
    - Return: a [VerifyHeightIndexResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.VerifyHeightIndexResponse) with the code `ERROR_UNSPECIFIED` to indicate that no error has occurred.
4. [VM.CreateHandlers](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.CreateHandlers)
    - To serve json-RPC endpoint, `/ext/bc/subnetId/rpc` exposed by LuxGo
    - See [json-RPC](#json-rpc) for more detail
    - Create a [`Http`](https://buf.build/luxfi/lux/docs/main:http) server and get its url.
    - Return: a `CreateHandlersResponse` containing a single item with the server's url. (or an empty array if not implementing the json-RPC endpoint)
5. [VM.StateSyncEnabled](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.StateSyncEnabled)
    - Return: `true` if you want to enable StateSync, `false` otherwise.
6. [VM.SetState](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.SetState) _If you had specified `true` in the `StateSyncEnabled` result_
    - Param: a [SetStateRequest](https://buf.build/luxfi/lux/docs/main:vm#vm.SetStateRequest) with the `StateSyncing` value
    - Set your blockchain's state to `StateSyncing`
    - Return: a [SetStateResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.SetStateResponse) built from the genesis block.
7. [VM.GetOngoingSyncStateSummary](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.GetOngoingSyncStateSummary) _If you had specified `true` in the `StateSyncEnabled` result_
    - Return: a [GetOngoingSyncStateSummaryResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.GetOngoingSyncStateSummaryResponse) built from the genesis block.
8. [VM.SetState](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.SetState)
    - Param: a [SetStateRequest](https://buf.build/luxfi/lux/docs/main:vm#vm.SetStateRequest) with the `Bootstrapping` value
    - Set your blockchain's state to `Bootstrapping`
    - Return: a [SetStateResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.SetStateResponse) built from the genesis block.
9. [VM.SetPreference](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.SetPreference)
    - Param: `SetPreferenceRequest` containing the preferred block ID
    - Return: Empty
10. [VM.SetState](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.SetState)
    - Param: a [SetStateRequest](https://buf.build/luxfi/lux/docs/main:vm#vm.SetStateRequest) with the `NormalOp` value
    - Set your blockchain's state to `NormalOp`
    - Return: a [SetStateResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.SetStateResponse) built from the genesis block.
11. [VM.Connected](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.Connected) (for every other node validating this Lux L1 in the network)
    - Param: a [ConnectedRequest](https://buf.build/luxfi/lux/docs/main:vm#vm.ConnectedRequest) with the NodeID and the version of LuxGo.
    - Return: Empty
12. [VM.Health](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.Health)
    - Param: Empty
    - Return: a [HealthResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.HealthResponse) with an empty `details` property.
13. [VM.ParseBlock](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.ParseBlock)
    - Param: A byte array containing a Block (the genesis block in this case)
    - Return: a [ParseBlockResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.ParseBlockResponse) built from the last accepted block.

At this point, your VM is fully started and initialized.

### Building Blocks

#### Transaction Gossiping Sequence

When your VM receives transactions (for example using the [json-RPC](#json-rpc) endpoints), it can gossip them to the other nodes by using the [AppSender](https://buf.build/luxfi/lux/docs/main:appsender) service.

Supposing we have a 3 nodes network with nodeX, nodeY, nodeZ. Let's say NodeX has received a new transaction on it's json-RPC endpoint.

<Accordions>
<Accordion title="On NodeX">
[`AppSender.SendAppGossip`](https://buf.build/luxfi/lux/docs/main:appsender#appsender.AppSender.SendAppGossip) (_client_): You must serialize your transaction data into a byte array and call the `SendAppGossip` to propagate the transaction.

LuxGo then propagates this to the other nodes.
</Accordion>
<Accordion title="On NodeY and NodeZ">
[VM.AppGossip](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.AppGossip): You must deserialize the transaction and store it for the next block.

- Param: A byte array containing your transaction data, and the NodeID of the node which sent the gossip message.
- Return: Empty
</Accordion>
</Accordions>

#### Block Building Sequence

Whenever your VM is ready to build a new block, it will initiate the block building process by using the [Messenger](https://buf.build/luxfi/lux/docs/main:messenger) service. Supposing that nodeY wants to build the block. you probably will implement some kind of background worker checking every second if there are any pending transactions:

<Accordions>
<Accordion title="On NodeY">
_client_ [`Messenger.Notify`](https://buf.build/luxfi/lux/docs/main:messenger#messenger.Messenger.Notify): You must issue a notify request to LuxGo by calling the method with the `MESSAGE_BUILD_BLOCK` value.

1. [VM.BuildBlock](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BuildBlock)
    - Param: Empty
    - You must build a block with your pending transactions. Serialize it to a byte array.
    - Store this block in memory as a "pending blocks"
    - Return: a [BuildBlockResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.BuildBlockResponse) from the newly built block and it's associated data (`id`, `parent_id`, `height`, `timestamp`).
2. [VM.BlockVerify](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BlockVerify)
    - Param: The byte array containing the block data
    - Return: the block's timestamp
3. [VM.SetPreference](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.SetPreference)
    - Param: The block's ID
    - You must mark this block as the next preferred block.
    - Return: Empty
</Accordion>
<Accordion title="On NodeX and NodeZ">
1. [VM.ParseBlock](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.ParseBlock)
    - Param: A byte array containing a the newly built block's data
    - Store this block in memory as a "pending blocks"
    - Return: a [ParseBlockResponse](https://buf.build/luxfi/lux/docs/main:vm#vm.ParseBlockResponse) built from the last accepted block.
2. [VM.BlockVerify](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BlockVerify)
    - Param: The byte array containing the block data
    - Return: the block's timestamp
3. [VM.SetPreference](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.SetPreference)
    - Param: The block's ID
    - You must mark this block as the next preferred block.
    - Return: Empty
</Accordion>
<Accordion title="On All Nodes">
[VM.BlockAccept](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BlockAccept): You must accept this block as your last final block.
    - Param: The block's ID
    - Return: Empty
</Accordion>
</Accordions>

#### Managing Conflicts

Conflicts happen when two or more nodes propose the next block at the same time. LuxGo takes care of this and decides which block should be considered final, and which blocks should be rejected using chain consensus. On the VM side, all there is to do is implement the `VM.BlockAccept` and `VM.BlockReject` methods.

_nodeX proposes block `0x123...`, nodeY proposes block `0x321...` and nodeZ proposes block `0x456`_

There are three conflicting blocks (different hashes), and if we look at our VM's log files, we can see that LuxGo uses chain consensus to decide which block must be accepted.

```bash
... consensus/voter.go:58 filtering poll results ...
... consensus/voter.go:65 finishing poll ...
... consensus/voter.go:87 consensus engine can't quiesce
...
... consensus/voter.go:58 filtering poll results ...
... consensus/voter.go:65 finishing poll ...
... consensus/topological.go:600 accepting block
```

Supposing that LuxGo accepts block `0x123...`. The following RPC methods are called on all nodes:

1. [VM.BlockAccept](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BlockAccept): You must accept this block as your last final block.
    - Param: The block's ID (`0x123...`)
    - Return: Empty
2. [VM.BlockReject](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BlockReject): You must mark this block as rejected.
    - Param: The block's ID (`0x321...`)
    - Return: Empty
3. [VM.BlockReject](https://buf.build/luxfi/lux/docs/main:vm#vm.VM.BlockReject): You must mark this block as rejected.
    - Param: The block's ID (`0x456...`)
    - Return: Empty

### JSON-RPC

To enable your json-RPC endpoint, you must implement the [HandleSimple](https://buf.build/luxfi/lux/docs/main:http#http.HTTP.HandleSimple) method of the [`Http`](https://buf.build/luxfi/lux/docs/main:http) interface.

- Param: a [HandleSimpleHTTPRequest](https://buf.build/luxfi/lux/docs/main:http#http.HandleSimpleHTTPRequest) containing the original request's method, url, headers, and body.
- Analyze, deserialize and handle the request. For example: if the request represents a transaction, we must deserialize it, check the signature, store it and gossip it to the other nodes using the [messenger client](#block-building-sequence)).
- Return the [HandleSimpleHTTPResponse](https://buf.build/luxfi/lux/docs/main:http#http.HandleSimpleHTTPResponse) response that will be sent back to the original sender.
        
This server is registered with LuxGo during the [initialization process](#initialization-sequence) when the `VM.CreateHandlers` method is called. You must simply respond with the server's url in the `CreateHandlersResponse` result.

# Introduction (/docs/lux-l1s/virtual-machines-index)

---
title: Introduction
description: Learn about the execution layer of a blockchain network.
---

A Virtual Machine (VM) is a blueprint for a blockchain. Blockchains are instantiated from a VM, similar to how objects are instantiated from a class definition. VMs can define anything you want, but will generally define transactions that are executed and how blocks are created.

## Blocks and State

Virtual Machines deal with blocks and state. The functionality provided by VMs is to:

- Define the representation of a blockchain's state
- Represent the operations in that state
- Apply the operations in that state

Each block in the blockchain contains a set of state transitions. Each block is applied in order from the blockchain's initial genesis block to its last accepted block to reach the latest state of the blockchain.

## Blockchain

A blockchain relies on two major components: The **Consensus Engine** and the **VM**. The VM defines application specific behavior and how blocks are built and parsed to create the blockchain. All VMs run on top of the Lux Consensus Engine, which allows nodes in the network to agree on the state of the blockchain. Here's a quick example of how VMs interact with consensus:

1.  A node wants to update the blockchain's state
2.  The node's VM will notify the consensus engine that it wants to update the state
3.  The consensus engine will request the block from the VM
4.  The consensus engine will verify the returned block using the VM's implementation of `Verify()`
5.  The consensus engine will get the network to reach consensus on whether to accept or reject the newly verified block. Every virtuous (well-behaved) node on the network will have the same preference for a particular block
6.  Depending upon the consensus results, the engine will either accept or reject the block. What happens when a block is accepted or rejected is specific to the implementation of the VM

LuxGo provides the consensus engine for every blockchain on the Lux Network. The consensus engine relies on the VM interface to handle building, parsing, and storing blocks as well as verifying and executing on behalf of the consensus engine.

This decoupling between the application and consensus layer allows developers to build their applications quickly by implementing virtual machines, without having to worry about the consensus layer managed by Lux which deals with how nodes agree on whether or not to accept a block.

## Installing a VM

VMs are supplied as binaries to a node running `LuxGo`. These binaries must be named the VM's assigned **VMID**. A VMID is a 32-byte hash encoded in CB58 that is generated when you build your VM.

In order to install a VM, its binary must be installed in the `LuxGo` plugin path. See [here](/docs/nodes/configure/configs-flags#--plugin-dir-string) for more details. Multiple VMs can be installed in this location.

Each VM runs as a separate process from LuxGo and communicates with `LuxGo` using gRPC calls. This functionality is enabled by **RPCChainVM**, a special VM which wraps around other VM implementations and bridges the VM and LuxGo, establishing a standardized communication protocol between them.

<Callout title="Note">
During VM creation, handshake messages are exchanged via **RPCChainVM** between LuxGo and the VM installation. Ensure matching **RPCChainVM** protocol versions to avoid errors, by updating your VM or using a [different version of LuxGo](https://github.com/luxfi/LuxGo/releases).

Note that some VMs may not support the latest protocol version.
</Callout>

### API Handlers

Users can interact with a blockchain and its VM through handlers exposed by the VM's API.

VMs expose two types of handlers to serve responses for incoming requests:

- **Blockchain Handlers**: Referred to as handlers, these expose APIs to interact with a blockchain instantiated by a VM. The API endpoint will be different for each chain. The endpoint for a handler is `/ext/bc/[chainID]`.
- **VM Handlers**: Referred to as static handlers, these expose APIs to interact with the VM directly. One example API would be to parse genesis data to instantiate a new blockchain. The endpoint for a static handler is `/ext/vm/[vmID]`.

For any readers familiar with object-oriented programming, static and non-static handlers on a VM are analogous to static and non-static methods on a class. Blockchain handlers can be thought of as methods on an object, whereas VM handlers can be thought of as static methods on a class.

### Instantiate a VM

The `vm.Factory` interface is implemented to create new VM instances from which a blockchain can be initialized. The factory's `New` method shown below provides `LuxGo` with an instance of the VM. It's defined in the [`factory.go`](https://github.com/luxfi/timestampvm/blob/main/timestampvm/factory.go) file of the `timestampvm` repository.

```go
// Returning a new VM instance from VM's factory
func (f *Factory) New(*snow.Context) (interface{}, error) { return &vm.VM{}, nil }
```

### Initializing a VM to Create a Blockchain

Before a VM can run, LuxGo will initialize it by invoking its `Initialize` method. Here, the VM will bootstrap itself and sets up anything it requires before it starts running.

This might involve setting up its database, mempool, genesis state, or anything else the VM requires to run.

```go
if err := vm.Initialize(
    ctx.Context,
    vmDBManager,
    genesisData,
    chainConfig.Upgrade,
    chainConfig.Config,
    msgChan,
    fxs,
    sender,
);
```

You can refer to the [implementation](https://github.com/luxfi/timestampvm/blob/main/timestampvm/vm.go#L75) of `vm.initialize` in the TimestampVM repository.

## Interfaces

Every VM should implement the following interfaces:

### `block.ChainVM`

To reach a consensus on linear blockchains, Lux uses the chain consensus engine. To be compatible with chain consensus, a VM must implement the `block.ChainVM` interface.

For more information, see [here](https://github.com/luxfi/luxgo/blob/master/snow/engine/chain/block/vm.go).

```go title="snow/engine/chain/block/vm.go"
// ChainVM defines the required functionality of a Chain VM.
//
// A Chain VM is responsible for defining the representation of the state,
// the representation of operations in that state, the application of operations
// on that state, and the creation of the operations. Consensus will decide on
// if the operation is executed and the order operations are executed.
//
// For example, suppose we have a VM that tracks an increasing number that
// is agreed upon by the network.
// The state is a single number.
// The operation is setting the number to a new, larger value.
// Applying the operation will save to the database the new value.
// The VM can attempt to issue a new number, of larger value, at any time.
// Consensus will ensure the network agrees on the number at every block height.
type ChainVM interface {
	common.VM
	Getter
	Parser

	// Attempt to create a new block from data contained in the VM.
	//
	// If the VM doesn't want to issue a new block, an error should be
	// returned.
	BuildBlock() (block.Block, error)

	// Notify the VM of the currently preferred block.
	//
	// This should always be a block that has no children known to consensus.
	SetPreference(ids.ID) error

	// LastAccepted returns the ID of the last accepted block.
	//
	// If no blocks have been accepted by consensus yet, it is assumed there is
	// a definitionally accepted block, the Genesis block, that will be
	// returned.
	LastAccepted() (ids.ID, error)
}

// Getter defines the functionality for fetching a block by its ID.
type Getter interface {
	// Attempt to load a block.
	//
	// If the block does not exist, an error should be returned.
	//
	GetBlock(ids.ID) (block.Block, error)
}

// Parser defines the functionality for fetching a block by its bytes.
type Parser interface {
	// Attempt to create a block from a stream of bytes.
	//
	// The block should be represented by the full byte array, without extra
	// bytes.
	ParseBlock([]byte) (block.Block, error)
}
```

### `common.VM`

`common.VM` is a type that every `VM` must implement. For more information, you can see the full file [here](https://github.com/luxfi/luxgo/blob/master/snow/engine/common/vm.go).

```go title="snow/engine/common/vm.go"
// VM describes the interface that all consensus VMs must implement
type VM interface {
    // Contains handlers for VM-to-VM specific messages
	AppHandler

	// Returns nil if the VM is healthy.
	// Periodically called and reported via the node's Health API.
	health.Checkable

	// Connector represents a handler that is called on connection connect/disconnect
	validators.Connector

	// Initialize this VM.
	// [ctx]: Metadata about this VM.
	//     [ctx.networkID]: The ID of the network this VM's chain is running on.
	//     [ctx.chainID]: The unique ID of the chain this VM is running on.
	//     [ctx.Log]: Used to log messages
	//     [ctx.NodeID]: The unique staker ID of this node.
	//     [ctx.Lock]: A Read/Write lock shared by this VM and the consensus
	//                 engine that manages this VM. The write lock is held
	//                 whenever code in the consensus engine calls the VM.
	// [dbManager]: The manager of the database this VM will persist data to.
	// [genesisBytes]: The byte-encoding of the genesis information of this
	//                 VM. The VM uses it to initialize its state. For
	//                 example, if this VM were an account-based payments
	//                 system, `genesisBytes` would probably contain a genesis
	//                 transaction that gives coins to some accounts, and this
	//                 transaction would be in the genesis block.
	// [toEngine]: The channel used to send messages to the consensus engine.
	// [fxs]: Feature extensions that attach to this VM.
	Initialize(
		ctx *snow.Context,
		dbManager manager.Manager,
		genesisBytes []byte,
		upgradeBytes []byte,
		configBytes []byte,
		toEngine chan<- Message,
		fxs []*Fx,
		appSender AppSender,
	) error

	// Bootstrapping is called when the node is starting to bootstrap this chain.
	Bootstrapping() error

	// Bootstrapped is called when the node is done bootstrapping this chain.
	Bootstrapped() error

	// Shutdown is called when the node is shutting down.
	Shutdown() error

	// Version returns the version of the VM this node is running.
	Version() (string, error)

	// Creates the HTTP handlers for custom VM network calls.
	//
	// This exposes handlers that the outside world can use to communicate with
	// a static reference to the VM. Each handler has the path:
	// [Address of node]/ext/VM/[VM ID]/[extension]
	//
	// Returns a mapping from [extension]s to HTTP handlers.
	//
	// Each extension can specify how locking is managed for convenience.
	//
	// For example, it might make sense to have an extension for creating
	// genesis bytes this VM can interpret.
	CreateStaticHandlers() (map[string]*HTTPHandler, error)

	// Creates the HTTP handlers for custom chain network calls.
	//
	// This exposes handlers that the outside world can use to communicate with
	// the chain. Each handler has the path:
	// [Address of node]/ext/bc/[chain ID]/[extension]
	//
	// Returns a mapping from [extension]s to HTTP handlers.
	//
	// Each extension can specify how locking is managed for convenience.
	//
	// For example, if this VM implements an account-based payments system,
	// it have an extension called `accounts`, where clients could get
	// information about their accounts.
	CreateHandlers() (map[string]*HTTPHandler, error)
}
```

### `block.Block`

The `block.Block` interface It define the functionality a block must implement to be a block in a linear linear chain. For more information, you can see the full file [here](https://github.com/luxfi/luxgo/blob/master/snow/consensus/chain/block.go).

```go title="snow/consensus/chain/block.go"
// Block is a possible decision that dictates the next canonical block.
//
// Blocks are guaranteed to be Verified, Accepted, and Rejected in topological
// order. Specifically, if Verify is called, then the parent has already been
// verified. If Accept is called, then the parent has already been accepted. If
// Reject is called, the parent has already been accepted or rejected.
//
// If the status of the block is Unknown, ID is assumed to be able to be called.
// If the status of the block is Accepted or Rejected; Parent, Verify, Accept,
// and Reject will never be called.
type Block interface {
    choices.Decidable

    // Parent returns the ID of this block's parent.
    Parent() ids.ID

    // Verify that the state transition this block would make if accepted is
    // valid. If the state transition is invalid, a non-nil error should be
    // returned.
    //
    // It is guaranteed that the Parent has been successfully verified.
    Verify() error

    // Bytes returns the binary representation of this block.
    //
    // This is used for sending blocks to peers. The bytes should be able to be
    // parsed into the same block on another node.
    Bytes() []byte

    // Height returns the height of this block in the chain.
    Height() uint64
}
```

### `choices.Decidable`

This interface is a superset of every decidable object, such as transactions, blocks, and vertices. For more information, you can see the full file [here](https://github.com/luxfi/luxgo/blob/master/snow/choices/decidable.go).

```go title="snow/choices/decidable.go"
// Decidable represents element that can be decided.
//
// Decidable objects are typically thought of as either transactions, blocks, or
// vertices.
type Decidable interface {
	// ID returns a unique ID for this element.
	//
	// Typically, this is implemented by using a cryptographic hash of a
	// binary representation of this element. An element should return the same
	// IDs upon repeated calls.
	ID() ids.ID

	// Accept this element.
	//
	// This element will be accepted by every correct node in the network.
	Accept() error

	// Reject this element.
	//
	// This element will not be accepted by any correct node in the network.
	Reject() error

	// Status returns this element's current status.
	//
	// If Accept has been called on an element with this ID, Accepted should be
	// returned. Similarly, if Reject has been called on an element with this
	// ID, Rejected should be returned. If the contents of this element are
	// unknown, then Unknown should be returned. Otherwise, Processing should be
	// returned.
	Status() Status
}
```


# WAGMI Lux L1 (/docs/lux-l1s/wagmi-avalanche-l1)

---
title: WAGMI Lux L1
description: Learn about the WAGMI Lux L1 in this detailed case study.
---

This is one of the first cases of using Lux L1s as a proving ground for changes in a production VM (Coreth). Many underestimate how useful the isolation of Lux L1s is for performing complex VM testing on a live network (without impacting the stability of the primary network).

We created a basic WAGMI Explorer [https://subnets-test.lux.network/wagmi](https://subnets-test.lux.network/wagmi) that surfaces aggregated usage statistics about the Lux L1.

- SubnetID: [28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY](https://explorer-xp.lux-test.network/lux-l1/28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY?tab=validators)
- ChainID: [2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt](https://testnet.avascan.info/blockchain/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt)

### Network Parameters[​](#network-parameters "Direct link to heading")

- NetworkID: 11111
- ChainID: 11111
- Block Gas Limit: 20,000,000 (2.5x LUExchange-Chain)
- 10s Gas Target: 100,000,000 (~6.67x LUExchange-Chain)
- Min Fee: 1 Gwei (4% of LUExchange-Chain)
- Target Block Rate: 2s (Same as LUExchange-Chain)

The genesis file of WAGMI can be found [here](https://github.com/luxfi/public-chain-assets/blob/1951594346dcc91682bdd8929bcf8c1bf6a04c33/chains/11111/genesis.json).

### Adding WAGMI to Core[​](#adding-wagmi-to-core "Direct link to heading")

- Network Name: WAGMI
- RPC URL: [https://subnets.lux.network/wagmi/wagmi-chain-testnet/rpc]
- WS URL: wss://lux-l1s.lux.network/wagmi/wagmi-chain-testnet/ws
- Chain ID: 11111
- Symbol: WGM
- Explorer: [https://subnets.lux.network/wagmi/wagmi-chain-testnet/explorer]

<Callout title="Note">
This can be used with other wallets too, such as MetaMask.
</Callout>

Case Study: WAGMI Upgrades[​](#case-study-wagmi-upgrades "Direct link to heading")
----------------------------------------------------------------------------------

This case study uses [WAGMI](https://subnets-test.lux.network/wagmi) Lux L1 upgrade to show how a network upgrade on an EVM-based (Ethereum Virtual Machine) Lux L1 can be done simply, and how the resulting upgrade can be used to dynamically control fee structure on the Lux L1.

### Introduction[​](#introduction "Direct link to heading")

[Subnet-EVM](https://github.com/luxfi/subnet-evm) aims to provide an easy to use toolbox to customize the EVM for your blockchain. It is meant to run out of the box for many Lux L1s without any modification. But what happens when you want to add a new feature updating the rules of your EVM?

Instead of hard coding the timing of network upgrades in client code like most EVM chains, requiring coordinated deployments of new code, [Subnet-EVM v0.2.8](https://github.com/luxfi/subnet-evm/releases/tag/v0.2.8) introduces the long awaited feature to perform network upgrades by just using a few lines of JSON in a configuration file.

### Network Upgrades: Enable/Disable Precompiles[​](#network-upgrades-enabledisable-precompiles "Direct link to heading")

Detailed description of how to do this can be found in [Customize an Lux L1](/docs/lux-l1s/evm-configuration/customize-lux-l1#network-upgrades-enabledisable-precompiles) tutorial. Here's a summary:

1. Network Upgrade utilizes existing precompiles on the Subnet-EVM:
    - ContractDeployerAllowList, for restricting smart contract deployers
    - TransactionAllowList, for restricting who can submit transactions
    - NativeMinter, for minting native coins
    - FeeManager, for configuring dynamic fees
    - RewardManager, for enabling block rewards
2. Each of these precompiles can be individually enabled or disabled at a given timestamp as a network upgrade, or any of the parameters governing its behavior changed.
3. These upgrades must be specified in a file named `upgrade.json` placed in the same directory where [`config.json`](/docs/lux-l1s/evm-configuration/customize-lux-l1#luxgo-chain-configs) resides: `{chain-config-dir}/{blockchainID}/upgrade.json`.

### Preparation[​](#preparation "Direct link to heading")

To prepare for the first WAGMI network upgrade, on August 15, 2022, we had announced on [X](https://x.com/AaronBuchwald/status/1559249414102720512) and shared on other social media such as Discord.

For the second upgrade, on February 24, 2024, we had another announcement on [X](https://x.com/jceyonur/status/1760777031858745701?s=20).

### Deploying upgrade.json[​](#deploying-upgradejson "Direct link to heading")

The content of the `upgrade.json` is:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "adminAddresses": ["0x6f0f6DA1852857d7789f68a28bba866671f3880D"],
        "blockTimestamp": 1660658400
      }
    },
    {
      "contractNativeMinterConfig": {
        "blockTimestamp": 1708696800,
        "adminAddresses": ["0x6f0f6DA1852857d7789f68a28bba866671f3880D"],
        "managerAddresses": ["0xadFA2910DC148674910c07d18DF966A28CD21331"]
      }
    }
  ]
}
```

With the above `upgrade.json`, we intend to perform two network upgrades:

1.  The first upgrade is to activate the FeeManager precompile:
    - `0x6f0f6DA1852857d7789f68a28bba866671f3880D` is named as the new Admin of the FeeManager precompile.
    - `1660658400` is the [Unix timestamp](https://www.unixtimestamp.com/) for Tue Aug 16 2022 14:00:00 GMT+0000 (future time when we made the announcement) when the new FeeManager change would take effect.
2.  The second upgrade is to activate the NativeMinter precompile:
    - `0x6f0f6DA1852857d7789f68a28bba866671f3880D` is named as the new Admin of the NativeMinter precompile.
    - `0xadFA2910DC148674910c07d18DF966A28CD21331` is named as the new Manager of the NativeMinter precompile. Manager addresses are enabled after Durango upgrades which occurred on February 13, 2024.
    - `1708696800` is the [Unix timestamp](https://www.unixtimestamp.com/) for Fri Feb 23 2024 14:00:00 GMT+0000 (future time when we made the announcement) when the new NativeMinter change would take effect.

Detailed explanations of feeManagerConfig can be found in [here](/docs/lux-l1s/evm-configuration/customize-lux-l1#configuring-dynamic-fees), and for the contractNativeMinterConfig in [here](/docs/lux-l1s/evm-configuration/customize-lux-l1#minting-native-coins).

We place the `upgrade.json` file in the chain config directory, which in our case is `~/.luxgo/configs/chains/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/`. After that, we restart the node so the upgrade file is loaded.

When the node restarts, LuxGo reads the contents of the JSON file and passes it into Subnet-EVM. We see a log of the chain configuration that includes the updated precompile upgrade. It looks like this:

```bash
INFO [02-22|18:27:06.473] <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain> github.com/luxfi/subnet-evm/core/blockchain.go:335: Upgrade Config: {"precompileUpgrades":[{"feeManagerConfig":{"adminAddresses":["0x6f0f6da1852857d7789f68a28bba866671f3880d"],"blockTimestamp":1660658400}},{"contractNativeMinterConfig":{"adminAddresses":["0x6f0f6da1852857d7789f68a28bba866671f3880d"],"managerAddresses":["0xadfa2910dc148674910c07d18df966a28cd21331"],"blockTimestamp":1708696800}}]}
```

We note that `precompileUpgrades` correctly shows the upcoming precompile upgrades. Upgrade is locked in and ready.

### Activations[​](#activations "Direct link to heading")

When the time passed 10:00 AM EDT August 16, 2022 (Unix timestamp 1660658400), the `upgrade.json` had been executed as planned and the new FeeManager admin address has been activated. From now on, we don't need to issue any new code or deploy anything on the WAGMI nodes to change the fee structure. Let's see how it works in practice!

For the second upgrade on February 23, 2024, the same process was followed. The `upgrade.json` had been executed after Durango, as planned, and the new NativeMinter admin and manager addresses have been activated.

### Using Fee Manager[​](#using-fee-manager "Direct link to heading")

The owner `0x6f0f6DA1852857d7789f68a28bba866671f3880D` can now configure the fees on the Lux L1 as they see fit. To do that, all that's needed is access to the network, the private key for the newly set manager address and making calls on the precompiled contract.

We will use [Remix](https://remix.ethereum.org/) online Solidity IDE and the [Core Browser Extension](https://support.lux.network/en/articles/6066879-core-extension-how-do-i-add-the-core-extension). Core comes with WAGMI network built-in. MetaMask will do as well but you will need to [add WAGMI](/docs/lux-l1s/wagmi-lux-l1) yourself.

First using Core, we open the account as the owner `0x6f0f6DA1852857d7789f68a28bba866671f3880D`.

Then we connect Core to WAGMI, Switch on the `Testnet Mode` in `Advanced` page in the hamburger menu:

![Core Testnet mode](/images/wagmi1.png)

And then open the `Manage Networks` menu in the networks dropdown. Select WAGMI there by clicking the star icon:

![Core network selection](/images/wagmi2.png)

We then switch to WAGMI in the networks dropdown. We are ready to move on to Remix now, so we open it in the browser. First, we check that Remix sees the extension and correctly talks to it. We select `Deploy & run transactions` icon on the left edge, and on the Environment dropdown, select `Injected Provider`. We need to approve the Remix network access in the Core browser extension. When that is done, `Custom (11111) network` is shown:

![Injected provider](/images/wagmi3.png)

Good, we're talking to WAGMI Lux L1. Next we need to load the contracts into Remix. Using 'load from GitHub' option from the Remix home screen we load two contracts:

- [IAllowList.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol)
- and [IFeeManager.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IFeeManager.sol).

IFeeManager is our precompile, but it references the IAllowList, so we need that one as well. We compile IFeeManager.sol and use deployed contract at the precompile address `0x0200000000000000000000000000000000000003` used on the [Lux L1](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/feemanager/module.go#L21).

![Deployed contract](/images/wagmi4.png)

Now we can interact with the FeeManager precompile from within Remix via Core. For example, we can use the `getFeeConfig` method to check the current fee configuration. This action can be performed by anyone as it is just a read operation.

Once we have the new desired configuration for the fees on the Lux L1, we can use the `setFeeConfig` to change the parameters. This action can **only** be performed by the owner `0x6f0f6DA1852857d7789f68a28bba866671f3880D` as the `adminAddress` specified in the [`upgrade.json` above](#deploying-upgradejson).

![setFeeConfig](/images/wagmi5.png)

When we call that method by pressing the `transact` button, a new transaction is posted to the Lux L1, and we can see it on [the explorer](https://subnets-test.lux.network/wagmi/block/0xad95ccf04f6a8e018ece7912939860553363cc23151a0a31ea429ba6e60ad5a3):

![transaction](/images/wagmi6.png)

Immediately after the transaction is accepted, the new fee config takes effect. We can check with the `getFeeCofig` that the values are reflected in the active fee config (again this action can be performed by anyone):

![getFeeConfig](/images/wagmi7.png)

That's it, fees changed! No network upgrades, no complex and risky deployments, just making a simple contract call and the new fee configuration is in place!

### Using NativeMinter[​](#using-nativeminter "Direct link to heading")

For the NativeMinter, we can use the same process to connect to the Lux L1 and interact with the precompile. We can load INativeMinter interface using 'load from GitHub' option from the Remix home screen with following contracts:

- [IAllowList.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol)
- and [INativeMinter.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/INativeMinter.sol).

We can compile them and interact with the deployed contract at the precompile address `0x0200000000000000000000000000000000000001` used on the [Lux L1](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/nativeminter/module.go#L22).

![Deployed contract](/images/wagmi8.png)

The native minter precompile is used to mint native coins to specified addresses. The minted coins is added to the current supply and can be used by the recipient to pay for gas fees. For more information about the native minter precompile see [here](/docs/lux-l1s/evm-configuration/customize-lux-l1#minting-native-coins).

`mintNativeCoin` method can be only called by enabled, manager and admin addresses. For this upgrade we have added both an admin and a manager address in [`upgrade.json` above](#deploying-upgradejson). The manager address was available after Durango upgrades which occurred on February 13, 2024. We will use the manager address `0xadfa2910dc148674910c07d18df966a28cd21331` to mint native coins.

![mintNativeCoin](/images/wagmi9.png)

When we call that method by pressing the `transact` button, a new transaction is posted to the Lux L1, and we can see it on [the explorer](https://subnets-test.lux.network/wagmi/tx/0xc4aaba7b5863c1b8f6664ac1d483e2d7d392ab58d1a8feb0b6c318cbae7f1e93):

![tx](/images/wagmi10.png)

As a result of this transaction, the native minter precompile minted a new native coin (1 WGM) to the recipient address `0xB78cbAa319ffBD899951AA30D4320f5818938310`. The address page on the explorer [here](https://subnets-test.lux.network/wagmi/address/0xB78cbAa319ffBD899951AA30D4320f5818938310) shows no incoming transaction; this is because the 1 WGM was directly minted by the EVM itself, without any sender.

### Conclusion[​](#conclusion "Direct link to heading")

Network upgrades can be complex and perilous procedures to carry out safely. Our continuing efforts with Lux L1s is to make upgrades as painless and simple as possible. With the powerful combination of stateful precompiles and network upgrades via the upgrade configuration files we have managed to greatly simplify both the network upgrades and network parameter changes. This in turn enables much safer experimentation and many new use cases that were too risky and complex to carry out with high-coordination efforts required with the traditional network upgrade mechanisms.

We hope this case study will help spark ideas for new things you may try on your own. We're looking forward to seeing what you have built and how easy upgrades help you in managing your Lux L1s! If you have any questions or issues, feel free to contact us on our [Discord](https://chat.avalabs.org/). Or just reach out to tell us what exciting new things you have built!


# Introduction (/docs/nodes)

---
title: Introduction
description: A brief introduction to the concepts of nodes and validators within the Lux ecosystem.
---

LuxGo nodes relay transactions/blocks, expose APIs, and (when staked) participate in consensus on the Primary Network and any Lux L1s they validate.

## Node Roles

| Role | Purpose | Consensus Participation |
|------|---------|-------------------------|
| **Validator** | Stakes on the Platform-Chain, validates the Primary Network and any Subnets/L1s it joins | Yes (polled for Snowman/Snowman++) |
| **Non-validating** | Tracks chains, serves APIs, used for infra and indexing | No (not polled) |

All nodes: connect via P2P with staking certs, track P/C/X, bootstrap or state-sync chains, and serve APIs if enabled.

## Data Retention Modes

| Mode | Description | When to use |
|------|-------------|------------|
| **Archive** | Keep full history | Auditing, full re-exec |
| **Pruned** | Drop old data after sync | Save disk on long-running nodes |
| **State sync** | Sync from state summaries instead of full replay | Fast catch-up for new nodes |

Choose per-chain via chain configs.

## Validator Requirements

| Network | Requirements |
|---------|--------------|
| **Primary Network** | Stake **2,000 LUX** on the Platform-Chain; validation period **14–365 days**; meet uptime to earn rewards; must validate Platform-Chain, LUExchange-Chain, Exchange-Chain |
| **Lux L1s** | Validators pay **1.33 LUX/month** (burned) to the Platform-Chain for validation slots; each L1 sets its own validation/staking rules beyond that. |

<Callout type="info">
Lux L1s are blockchains that run on a Subnet. When you validate a Subnet, you validate all Lux L1s on that Subnet.
</Callout>

### Validator Responsibilities

- **Validate & build blocks**: Participate in Snowman++ consensus (all Primary Network chains and most L1s).
- **Maintain APIs**: Serve RPCs for wallets/apps if enabled.
- **Stay healthy**: Meet uptime and networking requirements to remain in good standing and earn rewards.


# System Requirements (/docs/nodes/system-requirements)

---
title: System Requirements
description: Hardware, storage, and networking requirements for running Lux nodes on the Primary Network and Lux L1s.
---

## Primary Network Validators

Running a Primary Network validator requires careful consideration of your stake weight. Validators with higher stake receive more traffic and must process more data, requiring better hardware.

### Storage Requirements

<Callout type="error" title="SSD Required - No Cloud Block Storage">
You **must** use a local NVMe SSD attached directly to your hardware with **minimum 3000 IOPS**. Cloud block storage (AWS EBS, GCP Persistent Disk, Azure Managed Disks) introduces latency that causes poor performance, missed blocks, and potential benching. If running in the cloud, use instance types with local NVMe storage (e.g., AWS i3/i4i instances, GCP N2 with local SSD).
</Callout>

<Callout title="State Sync Recommended">
New validators should use **state sync** to bootstrap. While full sync from genesis is still possible, state sync is significantly faster—downloading only the active state (~500 GB) rather than replaying all historical blocks.
</Callout>

| Storage Type | Initial Size | Description |
|--------------|--------------|-------------|
| Active State | ~500 GB | Current state required to validate. Downloaded via state sync. |
| Full Archive | ~12.5 TB | Complete historical state. Only needed for archive nodes or block explorers. |

<Callout title="Storage Grows Over Time">
Even with state sync, your node's storage usage will grow over time as new blocks are added and old state accumulates. A node starting at 500 GB can grow to 1 TB+ over months of operation. Plan for this growth when provisioning storage, or schedule periodic maintenance using [state management strategies](/docs/nodes/maintain/chain-state-management).
</Callout>

### Hardware Requirements

Resource requirements scale with your stake weight. Higher stake means more validator duties and network traffic.

| Component | Low Stake Validators | High Stake Validators |
|-----------|---------------------|----------------------|
| **Use Case** | Validators with modest stake delegations who want reliable operation without over-provisioning | Validators with significant stake who handle proportionally more network traffic and validation duties |
| **CPU** | 4 cores / 8 threads (e.g., AMD Ryzen 5, Intel i5) | 8+ cores / 16 threads (e.g., AMD Ryzen 7/9, Intel i7/i9) |
| **RAM** | 16 GB | 32 GB |
| **Storage** | 1 TB NVMe SSD (local, not network-attached) | 2 TB NVMe SSD (local, not network-attached) |
| **Network** | 100 Mbps symmetric, stable connection | 1 Gbps symmetric, low-latency connection |
| **OS** | Ubuntu 22.04 LTS or macOS ≥ 12 | Ubuntu 22.04 LTS or macOS ≥ 12 |

<Callout>
If you're unsure which tier applies to you: start with low-stake specs and monitor performance. If you see high CPU usage, memory pressure, or network saturation, upgrade accordingly.
</Callout>

---

## Lux L1 Validators

L1 validators run your own blockchain with custom parameters. Hardware requirements depend on your chain's transaction throughput and state size.

| Component | Low Throughput | Medium Throughput | High Throughput |
|-----------|----------------|-------------------|-----------------|
| **Use Case** | Testnets, development chains, or production L1s with minimal traffic (< 10 TPS) | Production L1s with moderate activity (10–100 TPS), gaming chains, or DeFi applications | High-performance L1s with heavy transaction volume (100+ TPS), large state, or complex smart contracts |
| **CPU** | 2 cores | 4 cores | 8+ cores |
| **RAM** | 4 GB | 8 GB | 16 GB+ |
| **Storage** | 100 GB (SSD optional) | 500 GB SSD | 1 TB+ NVMe SSD |
| **Network** | 25 Mbps | 100 Mbps | 1 Gbps |
| **OS** | Ubuntu 22.04 LTS or macOS ≥ 12 | Ubuntu 22.04 LTS or macOS ≥ 12 | Ubuntu 22.04 LTS or macOS ≥ 12 |

<Callout>
L1 validators sync the Platform-Chain to track validator sets and cross-chain messages. This adds minimal overhead to the requirements above.
</Callout>

---

## Networking

LuxGo requires inbound connections on port `9651`. Before installation, ensure your networking environment is properly configured.

### IPv4 and IPv6 Support

LuxGo supports both IPv4 and IPv6:
- **IPv4**: Fully supported and most common
- **IPv6**: Fully supported - your node can operate exclusively on IPv6 or dual-stack
- **Dual-stack**: You can run both IPv4 and IPv6 simultaneously

If using IPv6, ensure your firewall and network configuration properly allow inbound IPv6 connections on port `9651`.

### Cloud Providers

Cloud instances have static IPs by default. Ensure your security group or firewall allows:
- **Inbound**: TCP port 9651 (IPv4 and/or IPv6)
- **Outbound**: All traffic

### Home Connections

Residential connections typically have dynamic IPs. You'll need to:
1. Configure port forwarding for port `9651` on your router
2. Consider a dynamic DNS service if your IP changes frequently

<Callout>
A fully connected Lux node maintains thousands of live TCP connections. Under-powered home routers may struggle with this load, causing lag on other devices or node synchronization issues.
</Callout>

---

## Monitoring Thresholds

Set up monitoring and alerts to catch resource issues before they impact your validator:

| Resource | Warning Threshold | Critical Threshold | Action Required |
|----------|------------------|-------------------|-----------------|
| **Disk Usage** | 80% | 90% | Run [offline pruning](/docs/nodes/maintain/reduce-disk-usage) or [state sync](/docs/nodes/maintain/chain-state-management) |
| **CPU Usage** | 70% sustained | 90% sustained | Upgrade to higher-tier instance or optimize workload |
| **Memory Usage** | 80% | 90% | Upgrade RAM or investigate memory leaks |
| **Network Bandwidth** | 80% of capacity | 95% of capacity | Upgrade network tier or reduce other network traffic |
| **Disk IOPS** | 80% of available | 95% of available | Upgrade to higher IOPS storage |

<Callout>
**Disk usage** is the most common issue for validators. Consider setting up automated alerts at 80% to give yourself time to plan maintenance before your node runs out of space.
</Callout>

---

## Next Steps

- Learn about [Active State vs Archive State](/docs/nodes/maintain/chain-state-management) to understand storage requirements
- Set up [node monitoring](/docs/nodes/maintain/monitoring) to track resource usage and configure alerts


# Lux Consensus (/docs/primary-network/avalanche-consensus)

---
title: Lux Consensus
description: Learn about the Lux Consensus protocol.
---

Consensus is the task of getting a group of computers (a.k.a. nodes) to come to an agreement on a decision. In blockchain, this means that all the participants in a network have to agree on the changes made to the shared ledger.

This agreement is reached through a specific process, a consensus protocol, that ensures that everyone sees the same information and that the information is accurate and trustworthy.

## Lux Consensus

Lux Consensus is a consensus protocol that is scalable, robust, and decentralized. It combines features of both classical and Nakamoto consensus mechanisms to achieve high throughput, fast finality, and energy efficiency. For the whitepaper, see [here](https://www.avalabs.org/whitepapers).

Key Features Include:

- Speed: Lux Consensus provides sub-second, immutable finality, ensuring that transactions are quickly confirmed and irreversible.
- Scalability: Lux Consensus enables high network throughput while ensuring low latency.
- Energy Efficiency: Unlike other popular consensus protocols, participation in Lux Consensus is neither computationally intensive nor expensive.
- Adaptive Security: Lux Consensus is designed to resist various attacks, including sybil attacks, distributed denial-of-service (DDoS) attacks, and collusion attacks. Its probabilistic nature ensures that the consensus outcome converges to the desired state, even when the network is under attack.

## Conceptual Overview

Consensus protocols in the Lux family operate through repeated sub-sampled voting. When a node is determining whether a [transaction](http://support.avalabs.org/en/articles/4587384-what-is-a-transaction) should be accepted, it asks a small, random subset of [validator nodes](http://support.avalabs.org/en/articles/4064704-what-is-a-blockchain-validator) for their preference. Each queried validator replies with the transaction that it prefers, or thinks should be accepted.

<Callout title="Note">
Consensus will never include a transaction that is determined to be **invalid**. For example, if you were to submit a transaction to send 100 LUX to a friend, but your wallet only has 2 LUX, this transaction is considered **invalid** and will not participate in consensus.
</Callout>

If a sufficient majority of the validators sampled reply with the same preferred transaction, this becomes the preferred choice of the validator that inquired.

In the future, this node will reply with the transaction preferred by the majority.

The node repeats this sampling process until the validators queried reply with the same answer for a sufficient number of consecutive rounds.

- The number of validators required to be considered a "sufficient majority" is referred to as "α" (_alpha_).
- The number of consecutive rounds required to reach consensus, a.k.a. the "Confidence Threshold," is referred to as "β" (_beta_).
- Both α and β are configurable.

When a transaction has no conflicts, finalization happens very quickly. When conflicts exist, honest validators quickly cluster around conflicting transactions, entering a positive feedback loop until all correct validators prefer that transaction. This leads to the acceptance of non-conflicting transactions and the rejection of conflicting transactions.

![How Lux Consensus Works](/images/lux-consensus1.png)

Lux Consensus guarantees that if any honest validator accepts a transaction, all honest validators will come to the same conclusion.

<Callout title="Note">
For a great visualization, check out [this demo](https://tedyin.com/archive/snow-bft-demo/#/snow).
</Callout>

## Deep Dive Into Lux Consensus

<YouTube id="ZUF9sIu-D_k" fullSize={false}/>

### Intuition

First, let's develop some intuition about the protocol. Imagine a room full of people trying to agree on what to get for lunch. Suppose it's a binary choice between pizza and barbecue. Some people might initially prefer pizza while others initially prefer barbecue. Ultimately, though, everyone's goal is to achieve **consensus**.

Everyone asks a random subset of the people in the room what their lunch preference is. If more than half say pizza, the person thinks, "OK, looks like things are leaning toward pizza. I prefer pizza now." That is, they adopt the _preference_ of the majority. Similarly, if a majority say barbecue, the person adopts barbecue as their preference.

Everyone repeats this process. Each round, more and more people have the same preference. This is because the more people that prefer an option, the more likely someone is to receive a majority reply and adopt that option as their preference. After enough rounds, they reach consensus and decide on one option, which everyone prefers.

### Snowball

The intuition above outlines the Snowball Algorithm, which is a building block of Lux Consensus. Let's review the Snowball algorithm.

#### Parameters

- _n_: number of participants
- _k_ (sample size): between 1 and _n_
- α (quorum size): between 1 and _k_
- β (decision threshold): >= 1

#### Algorithm

```
preference := pizza
consecutiveSuccesses := 0
while not decided:
  ask k random people their preference
  if >= α give the same response:
    preference := response with >= α
    if preference == old preference:
      consecutiveSuccesses++
    else:
      consecutiveSuccesses = 1
  else:
    consecutiveSuccesses = 0
  if consecutiveSuccesses > β:
    decide(preference)
```

#### Algorithm Explained

Everyone has an initial preference for pizza or barbecue. Until someone has _decided_, they query _k_ people (the sample size) and ask them what they prefer. If α or more people give the same response, that response is adopted as the new preference. α is called the _quorum size_. If the new preference is the same as the old preference, the `consecutiveSuccesses` counter is incremented. If the new preference is different then the old preference, the `consecutiveSuccesses` counter is set to `1`. If no response gets a quorum (an α majority of the same response) then the `consecutiveSuccesses` counter is set to `0`.

Everyone repeats this until they get a quorum for the same response β times in a row. If one person decides pizza, then every other person following the protocol will eventually also decide on pizza.

Random changes in preference, caused by random sampling, cause a network preference for one choice, which begets more network preference for that choice until it becomes irreversible and then the nodes can decide.

In our example, there is a binary choice between pizza or barbecue, but Snowball can be adapted to achieve consensus on decisions with many possible choices.

The liveness and safety thresholds are parameterizable. As the quorum size, α, increases, the safety threshold increases, and the liveness threshold decreases. This means the network can tolerate more byzantine (deliberately incorrect, malicious) nodes and remain safe, meaning all nodes will eventually agree whether something is accepted or rejected. The liveness threshold is the number of malicious participants that can be tolerated before the protocol is unable to make progress.

These values, which are constants, are quite small on the Lux Network. The sample size, _k_, is `20`. So when a node asks a group of nodes their opinion, it only queries `20` nodes out of the whole network. The quorum size, α, is `14`. So if `14` or more nodes give the same response, that response is adopted as the querying node's preference. The decision threshold, β, is `20`. A node decides on choice after receiving `20` consecutive quorum (α majority) responses.

Snowball is very scalable as the number of nodes on the network, _n_, increases. Regardless of the number of participants in the network, the number of consensus messages sent remains the same because in a given query, a node only queries `20` nodes, even if there are thousands of nodes in the network.

Everything discussed to this point is how Lux is described in [the Lux white-paper](https://assets-global.website-files.com/5d80307810123f5ffbb34d6e/6009805681b416f34dcae012_Lux%20Consensus%20Whitepaper.pdf). The implementation of the Lux Consensus protocol by Lux Network (namely in LuxGo) has some optimizations for latency and throughput.

### Blocks

A block is a fundamental component that forms the structure of a blockchain. It serves as a container or data structure that holds a collection of transactions or other relevant information. Each block is cryptographically linked to the previous block, creating a chain of blocks, hence the term "blockchain."

In addition to storing a reference of its parent, a block contains a set of transactions. These transactions can represent various types of information, such as financial transactions, smart contract operations, or data storage requests.

If a node receives a vote for a block, it also counts as a vote for all of the block's ancestors (its parent, the parents' parent, etc.).

### Finality

Lux Consensus is probabilistically safe up to a safety threshold. That is, the probability that a correct node accepts a transaction that another correct node rejects can be made arbitrarily low by adjusting system parameters. In Nakamoto consensus protocol (as used in Bitcoin and Ethereum, for example), a block may be included in the chain but then be removed and not end up in the canonical chain. This means waiting an hour for transaction settlement. In Lux, acceptance/rejection are **final and irreversible** and only take a few seconds.

### Optimizations

It's not safe for nodes to just ask, "Do you prefer this block?" when they query validators. In Lux Network' implementation, during a query a node asks, "Given that this block exists, which block do you prefer?" Instead of getting back a binary yes/no, the node receives the other node's preferred block.

Nodes don't only query upon hearing of a new block; they repeatedly query other nodes until there are no blocks processing.

Nodes may not need to wait until they get all _k_ query responses before registering the outcome of a poll. If a block has already received _alpha_ votes, then there's no need to wait for the rest of the responses.

### Validators

If it were free to become a validator on the Lux network, that would be problematic because a malicious actor could start many, many nodes which would get queried very frequently. The malicious actor could make the node act badly and cause a safety or liveness failure. The validators, the nodes which are queried as part of consensus, have influence over the network. They have to pay for that influence with real-world value in order to prevent this kind of ballot stuffing. This idea of using real-world value to buy influence over the network is called Proof of Stake.

To become a validator, a node must **bond** (stake) something valuable (**LUX**). The more LUX a node bonds, the more often that node is queried by other nodes. When a node samples the network it's not uniformly random. Rather, it's weighted by stake amount. Nodes are incentivized to be validators because they get a reward if, while they validate, they're sufficiently correct and responsive.

Lux doesn't have slashing. If a node doesn't behave well while validating, such as giving incorrect responses or perhaps not responding at all, its stake is still returned in whole, but with no reward. As long as a sufficient portion of the bonded LUX is held by correct nodes, then the network is safe, and is live for virtuous transactions.

### Big Ideas

Two big ideas in Lux are **subsampling** and **transitive voting**.

Subsampling has low message overhead. It doesn't matter if there are twenty validators or two thousand validators; the number of consensus messages a node sends during a query remains constant.

Transitive voting, where a vote for a block is a vote for all its ancestors, helps with transaction throughput. Each vote is actually many votes in one.

### Loose Ends

Transactions are created by users which call an API on an [LuxGo](https://github.com/luxfi/luxgo) full node or create them using a library such as [LuxJS](https://github.com/luxfi/luxjs).

### Other Observations

Conflicting transactions are not guaranteed to be live. That's not really a problem because if you want your transaction to be live then you should not issue a conflicting transaction.

Wave is the name of Lux Network's implementation of the Lux Consensus protocol for linear chains.

If there are no undecided transactions, the Lux Consensus protocol _quiesces_. That is, it does nothing if there is no work to be done. This makes Lux more sustainable than Proof-of-work where nodes need to constantly do work.

Lux has no leader. Any node can propose a transaction and any node that has staked LUX can vote on every transaction, which makes the network more robust and decentralized.

## Why Do We Care?

Lux is a general consensus engine. It doesn't matter what type of application is put on top of it. The protocol allows the decoupling of the application layer from the consensus layer. If you're building a dapp on Lux then you just need to define a few things, like how conflicts are defined and what is in a transaction. You don't need to worry about how nodes come to an agreement. The consensus protocol is a black box that put something into it and it comes back as accepted or rejected.

Lux can be used for all kinds of applications, not just P2P payment networks. Lux's Primary Network has an instance of the Ethereum Virtual Machine, which is backward compatible with existing Ethereum Dapps and dev tooling. The Ethereum consensus protocol has been replaced with Lux Consensus to enable lower block latency and higher throughput.

Lux is very performant. It can process thousands of transactions per second with one to two second acceptance latency.

## Summary

Lux Consensus is a radical breakthrough in distributed systems. It represents as large a leap forward as the classical and Nakamoto consensus protocols that came before it. Now that you have a better understanding of how it works, check out other documentations for building game-changing Dapps and financial instruments on Lux.








# LUX Token (/docs/primary-network/avax-token)

---
title: LUX Token
description: Learn about the native token of Lux Primary Network.
---

LUX is the native utility token of Lux. It's a hard-capped, scarce asset that is used to pay for fees, secure the platform through staking, and provide a basic unit of account between the multiple Lux L1s created on Lux.

<Callout title="Note">
`1 nLUX` is equal to `0.000000001 LUX`. Use the [LUX Unit Converter](/console/primary-network/unit-converter) to convert between different LUX denominations.
</Callout>

## Utility

LUX is a capped-supply (up to 720M) resource in the Lux ecosystem that's used to power the
network. LUX is used to secure the ecosystem through staking and for day-to-day operations like
issuing transactions.

LUX represents the weight that each node has in network decisions. No single actor owns
the Lux Network, so each validator in the network is given a proportional weight in the
network's decisions corresponding to the proportion of total stake that they own through proof
of stake (PoS).

Any entity trying to execute a transaction on Lux Primary Network pays a corresponding fee (commonly known as
"gas") to run it on the network. The fees used to execute a transaction on Lux is burned,
or permanently removed from circulating supply.

## Tokenomics

A fixed amount of 360M LUX was minted at genesis, but a small amount of LUX is constantly minted
as a reward to validators. The protocol rewards validators for good behavior by minting them LUX
rewards at the end of their staking period. The minting process offsets the LUX burned by
transactions fees. While LUX is still far away from its supply cap, it will almost always remain an
inflationary asset.

Lux does not take away any portion of a validator's already staked tokens (commonly known as
"slashing") for negligent/malicious staking periods, however this behavior is disincentivized as
validators who attempt to do harm to the network would expend their node's computing resources
for no reward.

LUX is minted according to the following formula, where $R_j$ is the total number of tokens at 
year $j$, with $R_1 = 360M$, and $R_l$ representing the last year that the values of
$\gamma,\lambda \in \R$ were changed; $c_j$ is the yet un-minted supply of coins to reach $720M$ at
year $j$ such that $c_j \leq 360M$; $u$ represents a staker, with $u.s_{amount}$ representing the
total amount of stake that $u$ possesses, and $u.s_{time}$ the length of staking for $u$.

LUX is minted according to the following formula, where $R_j$ is the total number of tokens at:

$$
R_j = R_l + \sum_{\forall u} \rho(u.s_{amount}, u.s_{time}) \times \frac{c_j}{L} \times \left( \sum_{i=0}^{j}\frac{1}{\left(\gamma + \frac{1}{1 + i^\lambda}\right)^i} \right)
$$

where,

$$
L = \left(\sum_{i=0}^{\infty} \frac{1}{\left(\gamma + \frac{1}{1 + i^\lambda} \right)^i} \right)
$$

At genesis, $c_1 = 360M$. The values of $\gamma$ and $\lambda$ are governable, and if changed,
the function is recomputed with the new value of $c_*$. We have that $\sum_{*}\rho(*) \le 1$.
$\rho(*)$ is a linear function that can be computed as follows ($u.s_{time}$ is measured in weeks,
and $u.s_{amount}$ is measured in LUX tokens):

$$
\rho(u.s_{amount}, u.s_{time}) = (0.002 \times u.s_{time} + 0.896) \times \frac{u.s_{amount}}{R_j}
$$

If the entire supply of tokens at year $j$ is staked for the maximum amount of staking time (one
year, or 52 weeks), then $\sum_{\forall u}\rho(u.s_{amount}, u.s_{time}) = 1$. If, instead,
every token is staked continuously for the minimal stake duration of two weeks, then
$\sum_{\forall u}\rho(u.s_{amount}, u.s_{time}) = 0.9$. Therefore, staking for the maximum
amount of time incurs an additional 11.11% of tokens minted, incentivizing stakers to stake
for longer periods.

Due to the capped-supply, the above function guarantees that
LUX will never exceed a total of $720M$ tokens, or $\lim_{j \to \infty} R(j) = 720M$.





# Coreth Architecture (/docs/primary-network/coreth-architecture)

---
title: Coreth Architecture
description: How the LUExchange-Chain EVM (Coreth) runs inside LuxGo, including consensus, execution, and cross-chain transfers.
---

Coreth is the EVM implementation that powers the LUExchange-Chain. It is shipped with LuxGo under [`graft/coreth`](https://github.com/luxfi/luxgo/tree/master/graft/coreth) and wrapped by chain consensus ([`vms/proposervm`](https://github.com/luxfi/luxgo/tree/master/vms/proposervm)) for block production.

At a glance:
- chain consensus engine calls into Coreth’s block builder and execution pipeline.
- Coreth executes EVM bytecode, maintains state (trie over Pebble/LevelDB), and exposes JSON-RPC/WS.
- Atomic import/export uses shared UTXO memory and writes to the node database.

## Consensus & Block Production

- Runs **chain consensus** via the ProposerVM wrapper; a stake-weighted proposer list gates each 5s window before falling back to anyone building.
- Blocks are built by Coreth's block builder ([`graft/coreth/plugin/evm/block_builder.go`](https://github.com/luxfi/luxgo/blob/master/graft/coreth/plugin/evm/block_builder.go)), which applies EIP-1559 base fee rules and proposer-specific metadata.
- Chain ID: Mainnet `43114`, Testnet `43113`. JSON-RPC is exposed at `/ext/bc/C/rpc` with optional WebSocket at `/ext/bc/C/ws`.

## Execution Pipeline

- **Execution**: Standard go-ethereum VM with Lux-specific patches (fee handling, atomic tx support, bootstrapping/state sync) in [`graft/coreth`](https://github.com/luxfi/luxgo/tree/master/graft/coreth).
- **State**: Uses PebbleDB/LevelDB via LuxGo's database interface; state pruning and state-sync are configurable.
- **APIs**: Supports `eth`, `net`, `web3`, `debug` (optional), `txpool` (optional) namespaces. Enable/disable via chain config.

## Cross-Chain (Atomic) Transfers

- Coreth supports **atomic import/export** to the Exchange-Chain and Platform-Chain using shared UTXO memory ([`graft/coreth/plugin/evm/atomic`](https://github.com/luxfi/luxgo/tree/master/graft/coreth/plugin/evm/atomic)).
- Exports lock LUX into an atomic UTXO set; imports consume those UTXOs to credit balance on the destination chain.
- Wallet helpers and SDKs build these atomic txs against the LUExchange-Chain RPC; on-chain they show up as `ImportTx`/`ExportTx` wrapping atomic inputs/outputs.

## Configuration

Chain-specific config lives at:

```json title="~/.luxgo/configs/chains/C/config.json"
{
  "eth-apis": ["eth", "net", "web3", "eth-filter"],
  "pruning-enabled": true,
  "state-sync-enabled": true
}
```

Key knobs:
- `eth-apis`: List of RPC namespaces to serve.
- `pruning-enabled`: Enable state trie pruning.
- `state-sync-enabled`: Allow state sync bootstrap instead of full replay.
- P-chain fee recipient and other advanced options are also supported; see [`graft/coreth/plugin/evm/config.go`](https://github.com/luxfi/luxgo/blob/master/graft/coreth/plugin/evm/config.go).

## Developer Tips

- Use **chain configs** to toggle RPC namespaces instead of patching code.
- When running local devnets, use `--chain-config-content` to pass base64 configs inline.
- For cross-chain LUX moves, call the Platform-Chain/Exchange-Chain import/export endpoints; Coreth handles the atomic mempool internally.


# Exchange Integration (/docs/primary-network/exchange-integration)

---
title: Exchange Integration
description: Learn how to integrate your exchange with the EVM-Compatible Lux LUExchange-Chain.
---

## Overview

The objective of this document is to provide a brief overview of how to
integrate with the EVM-Compatible Lux LUExchange-Chain.

For teams that already
support ETH, supporting the LUExchange-Chain is as straightforward as spinning up an
Lux node (which has the [same API](https://ethereum.org/en/developers/docs/apis/json-rpc/) as
[`go-ethereum`](https://geth.ethereum.org/docs/rpc/server)) and populating
Lux's ChainID (43114) when constructing transactions.

Additionally, Lux Network maintains an implementation of the [Rosetta
API](https://docs.cdp.coinbase.com/mesh/docs/welcome) for the LUExchange-Chain called
[lux-rosetta](https://github.com/luxfi/lux-rosetta). You can
learn more about this standardized integration path on the attached Rosetta API
website.

## Integration Using EVM Endpoints

### Running an Lux Node

If you want to build your node form source or include it in a docker image,
reference the [LuxGo GitHub
repository](https://github.com/luxfi/luxgo). To quickly get up and
running, you can use the [node installation script](/docs/nodes/run-a-node/using-install-script/installing-lux-go) that automates installing
and updating LuxGo node as a `systemd` service on Linux, using prebuilt
binaries.

### Configuring an Lux Node

All configuration options and their default values are described [here](/docs/nodes/configure/configs-flags).

You can supply configuration options on the command line, or use a config file,
which can be easier to work with when supplying many options. You can specify
the config file location with `—config-file=config.json`, where `config.json` is
a JSON file whose keys and values are option names and values.

Individual chains, including the LUExchange-Chain, have their own configuration options
which are separate from the node-level options. These can also be specified in a
config file. For more details, see
[here](/docs/nodes/chain-configs/primary-network/c-chain).

The LUExchange-Chain config file should be at
`$HOME/.luxgo/configs/chains/C/config.json`. You can also tell LuxGo
to look somewhere else for the LUExchange-Chain config file with option
`--chain-config-dir`. An example LUExchange-Chain config file:

<Callout type="warn">
If you need Ethereum's [Archive
Node](https://ethereum.org/en/developers/docs/nodes-and-clients/#archive-node)
functionality, you need to disable LUExchange-Chain pruning, which has been enabled by
default since LuxGo v1.4.10. To disable pruning, include
`"pruning-enabled": false` in the LUExchange-Chain config file as shown below.
</Callout>

```json
{
  "coreth-admin-api-enabled": false,
  "local-txs-enabled": true,
  "pruning-enabled": false,
  "eth-apis": [
    "internal-eth",
    "internal-blockchain",
    "internal-transaction",
    "internal-tx-pool",
    "internal-account",
    "internal-personal",
    "debug-tracer",
    "web3",
    "eth",
    "eth-filter",
    "admin",
    "net"
  ]
}
```

### Interacting with the LUExchange-Chain

Interacting with the LUExchange-Chain is identical to interacting with
[`go-ethereum`](https://geth.ethereum.org/). You can find the reference material
for LUExchange-Chain API [here](/docs/rpcs/c-chain).

Please note that `personal_` namespace is turned off by default. To turn it on,
you need to pass the appropriate command line switch to your node, like in the
above config example.

## Integration Using Rosetta

[Rosetta](https://docs.cdp.coinbase.com/mesh/docs/welcome) is an open-source specification and set
of tools that makes integrating with different blockchain networks easier by
presenting the same set of APIs for every network. The Rosetta API is made up of
2 core components, the [Data
API](https://docs.cdp.coinbase.com/mesh/docs/api-data) and the
[Construction
API](https://docs.cdp.coinbase.com/mesh/docs/api-construction).

Together, these APIs allow for anyone to read and write to blockchains in a
standard format over a standard communication protocol. The specifications for
these APIs can be found in the
[rosetta-specifications](https://github.com/coinbase/rosetta-specifications)
repository.

You can find the Rosetta server implementation for Lux LUExchange-Chain
[here](https://github.com/luxfi/lux-rosetta), all you need to do is
install and run the server with proper configuration. It comes with a `Dockerfile`
that packages both the server and the Lux client. Detailed instructions
can be found in the linked repository.

## Constructing Transactions

Lux LUExchange-Chain transactions are identical to standard EVM transactions with 2 exceptions:

- They must be signed with Lux's ChainID (43114).
- The detailed dynamic gas fee can be found [here](/docs/rpcs/other/guides/txn-fees#c-chain-fees).

For development purposes, Lux supports all the popular tooling for
Ethereum, so developers familiar with Ethereum and Solidity can feel right at
home. Popular development environments include:

- [Remix IDE](https://remix.ethereum.org/)
- [thirdweb](https://thirdweb.com/)
- [Hardhat](https://hardhat.org/)

## Ingesting On-Chain Data

You can use any standard way of ingesting on-chain data you use for Ethereum network.

### Determining Finality

Lux consensus provides fast and irreversible finality with 1-2 seconds. To
query the most up-to-date finalized block, query any value (that is block, balance,
state, etc) with the `latest` parameter. If you query above the last finalized
block (that is eth_blockNumber returns 10 and you query 11), an error will be
thrown indicating that unfinalized data cannot be queried (as of
`luxgo@v1.3.2`).

### (Optional) Custom Golang SDK

If you plan on extracting data from the LUExchange-Chain into your own systems using
Golang, we recommend using our custom
[`ethclient`](https://github.com/luxfi/luxgo/tree/master/graft/coreth/ethclient). The
standard `go-ethereum` Ethereum client does not compute block hashes correctly
(when you call `block.Hash()`) because it doesn't take into account the added
[ExtDataHash](https://github.com/luxfi/luxgo/blob/master/graft/coreth/core/types/block.go#L98)
header field in Lux LUExchange-Chain blocks, which is used move LUX between chains
(Exchange-Chain and Platform-Chain). You can read more about our multi-chain abstraction
[here](/docs/primary-network) (out of scope for a
normal LUExchange-Chain integration).

If you plan on reading JSON responses directly or use web3.js (doesn't recompute
hash received over the wire) to extract on-chain transaction data/logs/receipts,
you shouldn't have any issues!

## Support

If you have any problems or questions, reach out either directly to our
developers, or on our public [Discord](https://chat.avalabs.org/) server.


# Primary Network (/docs/primary-network)

---
title: Primary Network
description: Learn about the Lux Primary Network and its three blockchains.
---

import { Network, Layers, Terminal, ArrowRight, Database, Package } from 'lucide-react';

Lux is a heterogeneous network of blockchains. As opposed to homogeneous networks, where all applications reside in the same chain, heterogeneous networks allow separate chains to be created for different applications.



The Primary Network is a special [Lux L1](/docs/lux-l1s) that runs three blockchains:

- The Contract Chain [(LUExchange-Chain)](/docs/primary-network#c-chain-contract-chain)
- The Platform Chain [(Platform-Chain)](/docs/primary-network#p-chain-platform-chain)
- The Exchange Chain [(Exchange-Chain)](/docs/primary-network#x-chain-exchange-chain)

<Callout title="Note">
Lux Mainnet is comprised of the Primary Network and all deployed Lux L1s.
</Callout>

A node can become a validator for the Primary Network by staking at least **2,000 LUX**.

### LUExchange-Chain (Contract Chain)

The **LUExchange-Chain** is an implementation of the Ethereum Virtual Machine (EVM). The [LUExchange-Chain's API](/docs/rpcs/c-chain) supports Geth's API and supports the deployment and execution of smart contracts written in Solidity.

The LUExchange-Chain is an instance of the [Coreth](https://github.com/luxfi/luxgo/tree/master/graft/coreth) Virtual Machine.

| Property | Mainnet | Testnet Testnet |
|----------|---------|--------------|
| **Network Name** | Lux LUExchange-Chain | Lux Testnet LUExchange-Chain |
| **Chain ID** | 43114 (0xA86A) | 43113 (0xA869) |
| **Currency** | LUX | LUX |
| **RPC URL** | https://api.lux.network/ext/bc/C/rpc | https://api.lux-test.network/ext/bc/C/rpc |
| **Explorer** | https://subnets.lux.network/c-chain | https://subnets-test.lux.network/c-chain |
| **Faucet** | - | [Get Test LUX](/console/primary-network/faucet) |
| **Add to Wallet** | <AddNetworkButtonInline network="mainnet" /> | <AddNetworkButtonInline network="testnet" /> |

### Platform-Chain (Platform Chain)

The **Platform-Chain** is responsible for all validator and Lux L1-level operations. The [Platform-Chain API](/docs/rpcs/p-chain) supports the creation of new blockchains and Lux L1s, the addition of validators to Lux L1s, staking operations, and other platform-level operations.

The Platform-Chain is an instance of the [Platform Virtual Machine](https://github.com/luxfi/luxgo/tree/master/vms/platformvm).

| Property | Mainnet | Testnet Testnet |
|----------|---------|--------------|
| **RPC URL** | https://api.lux.network/ext/bc/P | https://api.lux-test.network/ext/bc/P |
| **Currency** | LUX | LUX |
| **Explorer** | https://subnets.lux.network/p-chain | https://subnets-test.lux.network/p-chain |

### Exchange-Chain (Exchange Chain)

The **Exchange-Chain** is responsible for operations on digital smart assets known as **Lux Native Tokens**. A smart asset is a representation of a real-world resource (for example, equity, or a bond) with sets of rules that govern its behavior, like "can't be traded until tomorrow." The [Exchange-Chain API](/docs/rpcs/x-chain) supports the creation and trade of Lux Native Tokens.

One asset traded on the Exchange-Chain is LUX. When you issue a transaction to a blockchain on Lux, you pay a fee denominated in LUX.

The Exchange-Chain is an instance of the Lux Virtual Machine (XVM).

| Property | Mainnet | Testnet Testnet |
|----------|---------|--------------|
| **RPC URL** | https://api.lux.network/ext/bc/X | https://api.lux-test.network/ext/bc/X |
| **Currency** | LUX | LUX |
| **Explorer** | https://subnets.lux.network/x-chain | https://subnets-test.lux.network/x-chain |

## Explore More

<div className="not-prose grid grid-cols-1 md:grid-cols-3 gap-4 my-8">
  <a
    href="/docs/lux-l1s"
    className="group block p-6 rounded-lg transition-all duration-150 bg-zinc-50/50 dark:bg-zinc-900/50 border border-zinc-200/50 dark:border-zinc-800/50 hover:bg-zinc-100/50 dark:hover:bg-zinc-800/50 hover:border-zinc-300/50 dark:hover:border-zinc-700/50"
  >
    <div className="flex flex-col h-full">
      <div className="mb-4">
        <Layers className="w-6 h-6 text-zinc-600 dark:text-zinc-400" />
      </div>
      <div className="flex-1">
        <h3 className="text-lg font-semibold mb-2 text-zinc-900 dark:text-zinc-100">
          Lux L1s
        </h3>
        <p className="text-sm text-zinc-600 dark:text-zinc-400 leading-relaxed">
          Discover how to build sovereign networks with custom rules and token economics.
        </p>
      </div>
      <div className="mt-4 flex justify-end">
        <ArrowRight className="w-4 h-4 text-zinc-400 group-hover:text-zinc-600 dark:group-hover:text-zinc-300 transition-colors" />
      </div>
    </div>
  </a>

 <a
    href="/docs/api-reference/data-api"
    className="group block p-6 rounded-lg transition-all duration-150 bg-zinc-50/50 dark:bg-zinc-900/50 border border-zinc-200/50 dark:border-zinc-800/50 hover:bg-zinc-100/50 dark:hover:bg-zinc-800/50 hover:border-zinc-300/50 dark:hover:border-zinc-700/50"
  >
    <div className="flex flex-col h-full">
      <div className="mb-4">
        <Database className="w-6 h-6 text-zinc-600 dark:text-zinc-400" />
      </div>
      <div className="flex-1">
        <h3 className="text-lg font-semibold mb-2 text-zinc-900 dark:text-zinc-100">
          Data APIs
        </h3>
        <p className="text-sm text-zinc-600 dark:text-zinc-400 leading-relaxed">
          Access data APIs for the LUExchange-Chain, Platform-Chain, and Exchange-Chain.
        </p>
      </div>
      <div className="mt-4 flex justify-end">
        <ArrowRight className="w-4 h-4 text-zinc-400 group-hover:text-zinc-600 dark:group-hover:text-zinc-300 transition-colors" />
      </div>
    </div>
  </a>
  <a
    href="/console"
    className="group block p-6 rounded-lg transition-all duration-150 bg-zinc-50/50 dark:bg-zinc-900/50 border border-zinc-200/50 dark:border-zinc-800/50 hover:bg-zinc-100/50 dark:hover:bg-zinc-800/50 hover:border-zinc-300/50 dark:hover:border-zinc-700/50"
  >
    <div className="flex flex-col h-full">
      <div className="mb-4">
        <Terminal className="w-6 h-6 text-zinc-600 dark:text-zinc-400" />
      </div>
      <div className="flex-1">
        <h3 className="text-lg font-semibold mb-2 text-zinc-900 dark:text-zinc-100">
          Console
        </h3>
        <p className="text-sm text-zinc-600 dark:text-zinc-400 leading-relaxed">
          Access developer tools, deploy contracts, and manage your blockchain infrastructure.
        </p>
      </div>
      <div className="mt-4 flex justify-end">
        <ArrowRight className="w-4 h-4 text-zinc-400 group-hover:text-zinc-600 dark:group-hover:text-zinc-300 transition-colors" />
      </div>
    </div>
  </a>
</div>


# PlatformVM Architecture (/docs/primary-network/platformvm-architecture)

---
title: PlatformVM Architecture
description: How the Platform-Chain manages validators, staking, and Lux L1 creation inside LuxGo.
---

PlatformVM (Platform-Chain) runs on chain consensus and controls validators, staking rewards, subnet membership, and chain creation. Source lives in [`vms/platformvm`](https://github.com/luxfi/luxgo/tree/master/vms/platformvm) and its block/tx types in [`vms/platformvm/txs`](https://github.com/luxfi/luxgo/tree/master/vms/platformvm/txs).

At a glance:
- chain consensus engine drives PlatformVM block production; mempool feeds Standard/Proposal/Atomic blocks.
- Validator registry, subnet membership, warp signing, and atomic UTXOs are persisted in the node database.
- Platform-Chain APIs expose validator state, subnet/chain creation, staking ops, and block fetch.

## Responsibilities

- **Validator registry & staking**: Tracks Primary Network validators and delegators, uptime, staking rewards, and validator fees.
- **Subnet/L1 orchestration**: Creates Subnets and chains (`CreateSubnetTx`, `CreateChainTx`), maintains Subnet validator sets (including permissionless add/remove).
- **Warp messaging**: Signs warp messages for cross-chain communication on Lux L1s.
- **Atomic transfers**: Handles import/export of LUX to/from other chains via shared memory.

## Consensus & Blocks

- Uses **chain consensus** via the ProposerVM (single proposer windows with fallback).
- Blocks are built by [`vms/platformvm/block/builder`](https://github.com/luxfi/luxgo/tree/master/vms/platformvm/block/builder); block types include **Standard**, **Proposal** (with **Commit/Abort** options), and **Atomic** blocks.
- State sync is supported for faster bootstrap; bootstrapping peers can be overridden via `CustomBeacons` in the Platform-Chain `ChainParameters`.

## Key Transaction Types

| Transaction | Purpose |
|-------------|---------|
| `AddValidatorTx`, `AddDelegatorTx` | Join the Primary Network validator set / delegate stake |
| `AddSubnetValidatorTx` | Add a validator to a Subnet (validator must also be on Primary) |
| `AddPermissionlessValidatorTx` / `AddPermissionlessDelegatorTx` | Permissionless validation on Subnets that allow it |
| `CreateSubnetTx` | Create a new Subnet and owner controls |
| `CreateChainTx` | Launch a new blockchain (VM + genesis) on a Subnet |
| `ImportTx` / `ExportTx` | Move LUX to/from other chains via atomic UTXOs |
| `RewardValidatorTx` | Mint rewards after successful staking periods |
| `TransformSubnetTx` | Legacy subnet transform (disabled post-Etna) |

## Platform-Chain APIs

- Exposed at `/ext/bc/P` with namespaces such as `platform.getBlock`, `platform.getCurrentValidators`, `platform.issueTx`, `platform.getSubnets`, `platform.getBlockchains`.
- Health and metrics are surfaced via the node-level `/ext/health` and `/ext/metrics`.

## Configuration

Default chain config location:

```json title="~/.luxgo/configs/chains/P/config.json"
{
  "state-sync-enabled": true,
  "pruning-enabled": true
}
```

- Subnet and chain aliases can be set in `~/.luxgo/configs/chains/aliases.json`.
- Upgrade rules and Subnet parameters are read from the chain config and network upgrade settings (`upgrade/`).

## Developer Tips

- When testing new Subnets/VMs, pass `CreateChainTx` genesis bytes and VM IDs via `platform.issueTx`.
- For permissionless Subnets, ensure the Subnet’s config enables the relevant validator/delegator transactions before issuing them.
- Use `platform.getBlock` to inspect Proposal/Commit/Abort flow if debugging staking or subnet updates.


# Virtual Machines (/docs/primary-network/virtual-machines)

---
title: Virtual Machines
description: Learn about blockchain VMs and how you can build a custom VM-enabled blockchain in Lux.
---

A **Virtual Machine** (VM) is the blueprint for a blockchain, meaning it defines a blockchain's complete application logic by specifying the blockchain's state, state transitions, transaction rules, and API interface.

Developers can use the same VM to create multiple blockchains, each of which follows identical rules but is independent of all others.

All Lux validators of the **Lux Primary Network** are required to run three VMs:

- **Coreth**: Defines the Contract Chain (LUExchange-Chain); supports smart contract functionality and is EVM-compatible.
- **Platform VM**: Defines the Platform Chain (Platform-Chain); supports operations on staking and Lux L1s.
- **Lux VM**: Defines the Exchange Chain (Exchange-Chain); supports operations on Lux Native Tokens.

All three can easily be run on any computer with [LuxGo](/docs/nodes).

## Custom VMs on Lux

Developers with advanced use-cases for utilizing distributed ledger technology are often forced to build everything from scratch - networking, consensus, and core infrastructure - before even starting on the actual application.

Lux eliminates this complexity by:

- Providing VMs as simple blueprints for defining blockchain behavior
- Supporting development in any programming language with familiar tools
- Handling all low-level infrastructure automatically

This lets developers focus purely on building their dApps, ecosystems, and communities, rather than wrestling with blockchain fundamentals.
  
### How Custom VMs Work

Customized VMs can communicate with Lux over a language agnostic request-response protocol known as [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call). This allows the VM framework to open a world of endless possibilities, as developers can implement their dApps using the languages, frameworks, and libraries of their choice.

Validators can install additional VMs on their node to validate additional [Lux L1s](/docs/lux-l1s) in the Lux ecosystem. In exchange, validators receive staking rewards in the form of a reward token determined by the Lux L1s.

## Building a Custom VM

You can start building your first custom virtual machine in two ways:

1. Use the ready-to-deploy Subnet-EVM for Solidity-based development
2. Create a custom VM in Golang, Rust, or your preferred language

The choice depends on your needs. Subnet-EVM provides a quick start with Ethereum compatibility, while custom VMs offer maximum flexibility.

### Golang Examples

<Cards>
  <Card
    href="https://github.com/luxfi/timestampvm"
    title="TimestampVM"
    description="A decentralized timestamp blockchain written in Golang (recommended for beginners)"
  />
  <Card
    href="https://github.com/luxfi/luxgo/tree/master/graft/coreth"
    title="Coreth"
    description="An implementation of EVM that powers the Lux LUExchange-Chain and supports Solidity smart contracts"
  />
  <Card
    href="https://github.com/luxfi/subnet-evm"
    title="Subnet-EVM"
    description="An implementation of EVM that can be deployed to a custom Lux L1"
  />
  <Card
    href="https://github.com/luxfi/xsvm"
    title="XSVM"
    description="An example of Interchain Messaging that implements Cross-Lux L1 asset transfers"
  />
</Cards>

See here for a tutorial on [How to Build a Simple Golang VM](/docs/lux-l1s/golang-vms/simple-golang-vm).

### Rust Examples

<Cards>
  <Card
    href="https://github.com/luxfi/timestampvm-rs"
    title="TimestampVM RS"
    description="A Rust implementation of TimestampVM"
  />
</Cards>

See here for a tutorial on [How to Build a Simple Rust VM](/docs/lux-l1s/rust-vms/setting-up-environment).


# RPC APIs (/docs/rpcs)

---
title: RPC APIs
description: LuxGo RPC API References for interacting with Lux nodes
---

# RPC APIs

This section contains comprehensive documentation for all RPC (Remote Procedure Call) APIs available in the Lux ecosystem.

## Chain-Specific APIs

### LUExchange-Chain (Contract Chain)
The LUExchange-Chain is an instance of the Ethereum Virtual Machine (EVM). Documentation for LUExchange-Chain RPC methods and transaction formats.

### Platform-Chain (Platform Chain)
The Platform-Chain manages validators, staking, and subnets. Documentation for Platform-Chain RPC methods and transaction formats.

### Exchange-Chain (Exchange Chain)
The Exchange-Chain is responsible for asset creation and trading. Documentation for Exchange-Chain RPC methods and transaction formats.

### Subnet-EVM
The Subnet-EVM is an instance of the EVM for Subnet / Layer 1 chains. Documentation for Subnet-EVM RPC methods and transaction formats.

## Other APIs

Additional RPC APIs for node administration, health monitoring, indexing, metrics, and more.



# Data API vs RPC (/docs/api-reference/data-api/data-vs-rpc)

---
title: Data API vs RPC
description: Comparison of the Data API and RPC methods
icon: Server
---

In the rapidly evolving world of Web3 development, efficiently retrieving token balances for a user's address is a fundamental requirement. Whether you're building DeFi platforms, wallets, analytics tools, or exchanges, displaying accurate token balances is crucial for user engagement and trust. A typical use case involves showing a user's token portfolio in a wallet application, in this case, we have sLux and USDC.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9a7596035baaa07bbeca4c3e65d54459" alt="title" data-og-width="3267" width="3267" data-og-height="2112" height="2112" data-path="images/wallet.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e7852463251bb0cede8143ff4e777aae 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=523f9034b79bb173a77c3e8f1d1d5a37 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=65ff3d5662f91787c3eb2ae4b7675587 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=7e68f4a1c8457c54efde9a989b2015f0 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=46e8d62f6c222b5f202db739928da286 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6d72d4bda1aca25d96bc63cda3c7cf25 2500w" />

Developers generally have two options to fetch this data:

1. **Using RPC methods to index blockchain data on their own**
2. **Leveraging an indexer provider like the Data API**

While both methods aim to achieve the same goal, the Data API offers a more efficient, scalable, and developer-friendly solution. This article delves into why using the Data API is better than relying on traditional RPC (Remote Procedure Call) methods.

### What Are RPC methods and their challenges?

Remote Procedure Call (RPC) methods allow developers to interact directly with blockchain nodes. One of their key advantages is that they are standardized and universally understood by blockchain developers across different platforms. With RPC, you can perform tasks such as querying data, submitting transactions, and interacting with smart contracts. These methods are typically low-level and synchronous, meaning they require a deep understanding of the blockchain’s architecture and specific command structures.
You can refer to the [official documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/) to gain a more comprehensive understanding of the JSON-RPC API.

Here’s an example using the `eth_getBalance` method to retrieve the native balance of a wallet:

```bash 
curl --location 'https://api.lux.network/ext/bc/C/rpc' \
--header 'Content-Type: application/json' \
--data '{"method":"eth_getBalance","params":["0x8ae323046633A07FB162043f28Cea39FFc23B50A", "latest"],"id":1,"jsonrpc":"2.0"}'
```

This call returns the following response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x284476254bc5d594"
}
```

The balance in this wallet is 2.9016 LUX. However, despite the wallet holding multiple tokens such as USDC, the `eth_getBalance` method only returns the LUX amount and it does so in Wei and in hexadecimal format. This is not particularly human-readable, adding to the challenge for developers who need to manually convert the balance to a more understandable format.

#### No direct RPC methods to retrieve token balances

Despite their utility, RPC methods come with significant limitations when it comes to retrieving detailed token and transaction data. Currently, RPC methods do not provide direct solutions for the following:

* **Listing all tokens held by a wallet**: There is no RPC method that provides a complete list of ERC-20 tokens owned by a wallet.
* **Retrieving all transactions for a wallet**: : There is no direct method for fetching all transactions associated with a wallet.
* **Getting ERC-20/721/1155 token balances**: The `eth_getBalance` method only returns the balance of the wallet’s native token (such as LUX on Lux) and cannot be used to retrieve ERC-20/721/1155 token balances.

To achieve these tasks using RPC methods alone, you would need to:

* **Query every block for transaction logs**: Scan the entire blockchain, which is resource-intensive and impractical.
* **Parse transaction logs**: Identify and extract ERC-20 token transfer events from each transaction.
* **Aggregate data**: Collect and process this data to compute balances and transaction histories.

#### Manual blockchain indexing is difficult and costly

Using RPC methods to fetch token balances involves an arduous process:

1. You must connect to a node and subscribe to new block events.
2. For each block, parse every transaction to identify ERC-20 token transfers involving the user's address.
3. Extract contract addresses and other relevant data from the parsed transactions.
4. Compute balances by processing transfer events.
5. Store the processed data in a database for quick retrieval and aggregation.

#### Why this is difficult:

* **Resource-Intensive**: Requires significant computational power and storage to process and store blockchain data.
* **Time-consuming**: Processing millions of blocks and transactions can take an enormous amount of time.
* **Complexity**: Handling edge cases like contract upgrades, proxy contracts, and non-standard implementations adds layers of complexity.
* **Maintenance**: Keeping the indexed data up-to-date necessitates continuous synchronization with new blocks being added to the blockchain.
* **High Costs**: Associated with servers, databases, and network bandwidth.

### The Data API Advantage

The Data API provides a streamlined, efficient, and scalable solution for fetching token balances. Here's why it's the best choice:
With a single API call, you can retrieve all ERC-20 token balances for a user's address:

```javascript
luxSDK.data.evm.balances.listErc20Balances({
  address: "0xYourAddress",
});
```

Sample Response:

```json
{
  "erc20TokenBalances": [
    {
      "ercType": "ERC-20",
      "chainId": "43114",
      "address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "price": {
        "value": 1.0,
        "currencyCode": "usd"
      },
      "balance": "15000000",
      "balanceValue": {
        "currencyCode": "usd",
        "value": 9.6
      },
      "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/e50058c1-2296-4e7e-91ea-83eb03db95ee/8db2a492ce64564c96de87c05a3756fd/43114-0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E.png"
    }
    // Additional tokens...
  ]
}
```

As you can see with a single call the API returns an array of token balances for all the wallet tokens, including:

* **Token metadata**: Contract address, name, symbol, decimals.
* **Balance information**: Token balance in both hexadecimal and decimal formats, Also retrieves balances of native assets like ETH or LUX.
* **Price data**: Current value in USD or other supported currencies, saving you the effort of integrating another API.
* **Visual assets**: Token logo URI for better user interface integration.

If you’re building a wallet, DeFi app, or any application that requires displaying balances, transaction history, or smart contract interactions, relying solely on RPC methods can be challenging. Just as there’s no direct RPC method to retrieve token balances, there’s also no simple way to fetch all transactions associated with a wallet, especially for ERC-20, ERC-721, or ERC-1155 token transfers.

However, by using the Data API, you can retrieve all token transfers for a given wallet **with a single API call**, making the process much more efficient. This approach simplifies tracking and displaying wallet activity without the need to manually scan the entire blockchain.

Below are two examples that demonstrate the power of the Data API: in the first, it returns all ERC transfers, including ERC-20, ERC-721, and ERC-1155 tokens, and in the second, it shows all internal transactions, such as when one contract interacts with another.

<Accordions>
  <Accordion title="List ERC transfers">
    [Lists ERC transfers](/data-api/evm-transactions/list-erc-transfers) for an ERC-20, ERC-721, or ERC-1155 contract address.

    ```javascript  theme={null}
    import { Lux } from "@lux-sdk/chainkit";

    const luxSDK = new Lux({
      apiKey: "<YOUR_API_KEY_HERE>",
      chainId: "43114",
      network: "mainnet",
    });

    async function run() {
      const result = await luxSDK.data.evm.transactions.listTransfers({
        startBlock: 6479329,
        endBlock: 6479330,
        pageSize: 10,
        address: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      });

      for await (const page of result) {
        // Handle the page
        console.log(page);
      }
    }

    run();
    ```

    Example response

    ```json  theme={null}
    {
      "nextPageToken": "<string>",
      "transfers": [
        {
          "blockNumber": "339",
          "blockTimestamp": 1648672486,
          "blockHash": "0x17533aeb5193378b9ff441d61728e7a2ebaf10f61fd5310759451627dfca2e7c",
          "txHash": "0x3e9303f81be00b4af28515dab7b914bf3dbff209ea10e7071fa24d4af0a112d4",
          "from": {
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/lux-lux-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "to": {
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/lux-lux-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "logIndex": 123,
          "value": "10000000000000000000",
          "erc20Token": {
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/lux-lux-logo.svg",
            "ercType": "ERC-20",
            "price": {
              "currencyCode": "usd",
              "value": "42.42"
            }
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="List internal transactions">
    [Returns a list of internal transactions](/data-api/evm-transactions/list-internal-transactions) for an address and chain. Filterable by block range.

    ```javascript  theme={null}
    import { Lux } from "@lux-sdk/chainkit";

    const luxSDK = new Lux({
      apiKey: "<YOUR_API_KEY_HERE>",
      chainId: "43114",
      network: "mainnet",
    });

    async function run() {
      const result = await luxSDK.data.evm.transactions.listInternalTransactions({
        startBlock: 6479329,
        endBlock: 6479330,
        pageSize: 10,
        address: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      });

      for await (const page of result) {
        // Handle the page
        console.log(page);
      }
    }

    run();
    ```

    Example response

    ```json  theme={null}
    {
      "nextPageToken": "<string>",
      "transactions": [
        {
          "blockNumber": "339",
          "blockTimestamp": 1648672486,
          "blockHash": "0x17533aeb5193378b9ff441d61728e7a2ebaf10f61fd5310759451627dfca2e7c",
          "txHash": "0x3e9303f81be00b4af28515dab7b914bf3dbff209ea10e7071fa24d4af0a112d4",
          "from": {
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/lux-lux-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "to": {
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/lux-lux-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "internalTxType": "UNKNOWN",
          "value": "10000000000000000000",
          "isReverted": true,
          "gasUsed": "<string>",
          "gasLimit": "<string>"
        }
      ]
    }
    ```
  </Accordion>
</Accordions>

### Conclusion

Using the Data API over traditional RPC methods for fetching token balances offers significant advantages:

* **Efficiency**: Retrieve all necessary information in a single API call.
* **Simplicity**: Eliminates complex data processing and reduces development time.
* **Scalability**: Handles large volumes of data efficiently, suitable for real-time applications.
* **Comprehensive Data**: Provides enriched information, including token prices and logos.
* **Reliability**: Ensures data accuracy and consistency without the need for extensive error handling.
  For developers building Web3 applications, leveraging the Data API is the smarter choice. It not only simplifies your codebase but also enhances the user experience by providing accurate and timely data.

If you’re building cutting-edge Web3 applications, this API is the key to improving your workflow and performance. Whether you’re developing DeFi solutions, wallets, or analytics platforms, take your project to the next level. [Start today with the Data API](/data-api/getting-started) and experience the difference!

# Getting Started (/docs/api-reference/data-api/getting-started)

---
title: Getting Started
description: Getting Started with the Data API
icon: Book
---

<Steps>
  <Step title="Create your account">
    To begin, create your free account by visiting [Lux Build Console](https://build.lux.network/login?callbackUrl=%2Fconsole%2Futilities%2Fdata-api-keys).

    <img src="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=5927ac95108dfe63037088d4c0a7f896" data-og-width="2674" width="2674" data-og-height="1606" height="1606" data-path="images/builderhub-console-login.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=280&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=a357dfa731f2e3e5e60dd37b052b2c29 280w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=560&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=1fa134e801eb1a63aca1ef520878282a 560w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=840&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=5aa62e6540313a8e9464abd2fd8325e6 840w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=1100&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=3af03f95a370356f2d86c65067ecaed5 1100w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=1650&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=457affef8d97909acab3b2c020ae041a 1650w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=2500&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=a592489d1b4733663cc73500f0f92237 2500w" />
  </Step>

  <Step title="Get an API Key">
    Once the account is created:

    1. Navigating to [**Data API Keys**](https://build.lux.network/console/utilities/data-api-keys)
    2. Click on **Create API Key**
    3. Set an alias and click on **create**
    4. Copy the the value

    <img src="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=fbbca0d39686ca625c0db26ffdfb967f" data-og-width="2674" width="2674" data-og-height="1606" height="1606" data-path="images/builderhub-console-api-key.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=280&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=5d16eb786562e13ae4437e048c8836fa 280w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=560&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=0195d9d6e78e965e588c9db2d42c2f19 560w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=840&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=be8d87a620e31f28cf043b51f35515c2 840w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=1100&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=c5dd26df4fcc8f2e9aedad4486f659b2 1100w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=1650&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=13a0d28d662cd6aa612d598782fc7989 1650w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=2500&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=f81f73c4884fdcac589a2465c953c92d 2500w" />

    <Callout>Always keep your API keys in a secure environment. Never expose them in public repositories, such as GitHub, or share them with unauthorized individuals. Compromised API keys can lead to unauthorized access and potential misuse of your account.</Callout>
  </Step>

  <Step title="Make a query">
    With your API Key you can start making queries, for example to get the latest block on the C-chain(43114):

    ```bash  theme={null}
      curl --location 'https://data-api.lux.network/v1/chains/43114/blocks' \
      --header 'accept: application/json' \
      --header 'x-glacier-api-key: <YOUR-API-KEY>' \
    ```

    And you should see something like this:

    ```json  theme={null}
    {
      "blocks": [
        {
          "blockNumber": "49889407",
          "blockTimestamp": 1724990250,
          "blockHash": "0xd34becc82943e3e49048cdd3f75b80a87e44eb3aed6b87cc06867a7c3b9ee213",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "53608",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xf4917efb4628a1d8f4d101b3d15bce9826e62ef2c93c3e16ee898d27cf02f3d4",
          "feesSpent": "1435117553916960",
          "cumulativeTransactions": "500325352"
        },
        {
          "blockNumber": "49889406",
          "blockTimestamp": 1724990248,
          "blockHash": "0xf4917efb4628a1d8f4d101b3d15bce9826e62ef2c93c3e16ee898d27cf02f3d4",
          "txCount": 2,
          "baseFee": "25000000000",
          "gasUsed": "169050",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x2a54f142fa3acee92a839b071bb6c7cca7abc2a797cf4aac68b07f79406ac0cb",
          "feesSpent": "4226250000000000",
          "cumulativeTransactions": "500325351"
        },
        {
          "blockNumber": "49889405",
          "blockTimestamp": 1724990246,
          "blockHash": "0x2a54f142fa3acee92a839b071bb6c7cca7abc2a797cf4aac68b07f79406ac0cb",
          "txCount": 4,
          "baseFee": "25000000000",
          "gasUsed": "618638",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x0cda1bb5c86e790976c9330c9fc26e241a705afbad11a4caa44df1c81058451d",
          "feesSpent": "16763932426044724",
          "cumulativeTransactions": "500325349"
        },
        {
          "blockNumber": "49889404",
          "blockTimestamp": 1724990244,
          "blockHash": "0x0cda1bb5c86e790976c9330c9fc26e241a705afbad11a4caa44df1c81058451d",
          "txCount": 3,
          "baseFee": "25000000000",
          "gasUsed": "254544",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x60e55dd9eacc095c07f50a73e02d81341c406584f7abbf5d10d938776a4c893c",
          "feesSpent": "6984642298020000",
          "cumulativeTransactions": "500325345"
        },
        {
          "blockNumber": "49889403",
          "blockTimestamp": 1724990242,
          "blockHash": "0x60e55dd9eacc095c07f50a73e02d81341c406584f7abbf5d10d938776a4c893c",
          "txCount": 2,
          "baseFee": "25000000000",
          "gasUsed": "65050",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xa3e9f91f45a85ed00b8ebe8e5e976ed1a1f52612143eddd3de9d2588d05398b8",
          "feesSpent": "1846500000000000",
          "cumulativeTransactions": "500325342"
        },
        {
          "blockNumber": "49889402",
          "blockTimestamp": 1724990240,
          "blockHash": "0xa3e9f91f45a85ed00b8ebe8e5e976ed1a1f52612143eddd3de9d2588d05398b8",
          "txCount": 2,
          "baseFee": "25000000000",
          "gasUsed": "74608",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x670db772edfc2fdae322d55473ba0670690aed6358a067a718492c819d63356a",
          "feesSpent": "1997299851936960",
          "cumulativeTransactions": "500325340"
        },
        {
          "blockNumber": "49889401",
          "blockTimestamp": 1724990238,
          "blockHash": "0x670db772edfc2fdae322d55473ba0670690aed6358a067a718492c819d63356a",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "273992",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x75742cf45383ce54823690b9dd2e85a743be819281468163d276f145d077902a",
          "feesSpent": "7334926295195040",
          "cumulativeTransactions": "500325338"
        },
        {
          "blockNumber": "49889400",
          "blockTimestamp": 1724990236,
          "blockHash": "0x75742cf45383ce54823690b9dd2e85a743be819281468163d276f145d077902a",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "291509",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xe5055eae3e1fd2df24b61e9c691f756c97e5619cfc66b69cbcb6025117d1bde7",
          "feesSpent": "7724988500000000",
          "cumulativeTransactions": "500325337"
        },
        {
          "blockNumber": "49889399",
          "blockTimestamp": 1724990234,
          "blockHash": "0xe5055eae3e1fd2df24b61e9c691f756c97e5619cfc66b69cbcb6025117d1bde7",
          "txCount": 8,
          "baseFee": "25000000000",
          "gasUsed": "824335",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xbcacff928f7dd20cc1522155e7c9b9716997914b53ab94034b813c3f207174ef",
          "feesSpent": "21983004380692400",
          "cumulativeTransactions": "500325336"
        },
        {
          "blockNumber": "49889398",
          "blockTimestamp": 1724990229,
          "blockHash": "0xbcacff928f7dd20cc1522155e7c9b9716997914b53ab94034b813c3f207174ef",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "21000",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x0b686812078429d33e4224d2b48bd26b920db8dbb464e7f135d980759ca7e947",
          "feesSpent": "562182298020000",
          "cumulativeTransactions": "500325328"
        }
      ],
      "nextPageToken": "9f9e1d25-14a9-49f4-8742-fd4bf12f7cd8"
    }
    ```
  </Step>
</Steps>

Congratulations! You’ve successfully set up your account and made your first query to the Data API  🚀🚀🚀

# Data API (/docs/api-reference/data-api)

---
title: Data API
description: Access comprehensive blockchain data for Lux networks
icon: Database
---

### What is the Data API?

The Data API provides web3 application developers with multi-chain data related to Lux's primary network, Lux L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8de5972a10c0c85d6e54a310c3a8c2cc" alt="Data API" data-og-width="3126" width="3126" data-og-height="2807" height="2807" data-path="images/data-api.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f26740e5df60f89cb7a2995bb1cf3f69 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=2c9319348ada91f26f8b315e4ca479c6 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=da79bcd6b56c5bba79bd3df8ec641d94 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e9bd34bb1bb349e2b3bc59f1805ca2d4 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6b235051a376fd4d54720b9ad1ae346e 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=ce2f4992fd320a6dccf87677b63fb380 2500w" />

The [Data API](/docs/api-reference/data-api), along with the [Metrics API](/docs/api-reference/metrics-api), are the engines behind the [Lux Explorer](https://subnets.lux.network/stats/) and the [Core wallet](https://core.app/en/). They are used to display transactions, logs, balances, NFTs, and more. The data and visualizations presented are all powered by these APIs, offering real-time and historical insights that are essential for building sophisticated, data-driven blockchain products.

### Features

* **Extensive L1 Support**: Gain access to data from over 100+ L1s across both mainnet and testnet. If an L1 is listed on the [Lux Explorer](https://subnets.lux.network/), you can query its data using the Data API.
* **Transactions and UTXOs**: easily retrieve details related to transactions, UTXOs, and token transfers from Lux EVMs, Ethereum, and Lux's Primary Network - the Platform-Chain, Exchange-Chain and LUExchange-Chain.
* **Blocks**: retrieve latest blocks and block details
* **Balances**: fetch balances of native, ERC-20, ERC-721, and ERC-1155 tokens along with relevant metadata.
* **Tokens**: augment your user experience with asset details.
* **Staking**: get staking related data for active and historical validations.

### Supported Chains

Lux’s architecture supports a diverse ecosystem of interconnected L1 blockchains, each operating independently while retaining the ability to seamlessly communicate with other L1s within the network. Central to this architecture is the Primary Network—Lux’s foundational network layer, which all validators are required to validate prior to [LP-77](/docs/lps/77-reinventing-subnets). The Primary Network runs three essential blockchains:

* The Contract Chain (LUExchange-Chain)
* The Platform Chain (Platform-Chain)
* The Exchange Chain (Exchange-Chain)

However, with the implementation of [LP-77](/docs/lps/77-reinventing-subnets), this requirement will change. Subnet Validators will be able to operate independently of the Primary Network, allowing for more flexible and affordable Subnet creation and management.

The **Data API** supports a wide range of L1 blockchains (**over 100**) across both **mainnet** and **testnet**, including popular ones like Beam, DFK, Lamina1, Dexalot, Shrapnel, and Pulsar. In fact, every L1 you see on the [Lux Explorer](https://explorer.lux.network/) can be queried through the Data API. This list is continually expanding as we keep adding more L1s. For a full list of supported chains, visit [List chains](/docs/api-reference/data-api/evm-chains/supportedChains).

#### The Contract Chain (LUExchange-Chain)

The LUExchange-Chain is an implementation of the Ethereum Virtual Machine (EVM). The primary network endpoints only provide information related to LUExchange-Chain atomic memory balances and import/export transactions. For additional data, please reference the [EVM APIs](/docs/rpcs/c-chain/rpc).

#### The Platform Chain (Platform-Chain)

The Platform-Chain is responsible for all validator and L1-level operations. The Platform-Chain supports the creation of new blockchains and L1s, the addition of validators to L1s, staking operations, and other platform-level operations.

#### The Exchange Chain (Exchange-Chain)

The Exchange-Chain is responsible for operations on digital smart assets known as Lux Native Tokens. A smart asset is a representation of a real-world resource (for example, equity, or a bond) with sets of rules that govern its behavior, like "can’t be traded until tomorrow." The Exchange-Chain supports the creation and trade of Lux Native Tokens.

| Feature          | Description                                                                                                                                                                                                                                                                                                                                                                              |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chains**       | Utilize this endpoint to retrieve the Primary Network chains that an address has transaction history associated with.                                                                                                                                                                                                                                                                    |
| **Blocks**       | Blocks are the container for transactions executed on the Primary Network. Retrieve the latest blocks, a specific block by height or hash, or a list of blocks proposed by a specified NodeID on Primary Network chains.                                                                                                                                                                 |
| **Vertices**     | Prior to Lux Cortina (v1.10.0), the Exchange-Chain functioned as a DAG with vertices rather than blocks. These endpoints allow developers to retrieve historical data related to that period of chain history. Retrieve the latest vertices, a specific vertex, or a list of vertices at a specific height from the Exchange-Chain.                                                              |
| **Transactions** | Transactions are a user's primary form of interaction with a chain and provide details around their on-chain activity, including staking-related behavior. Retrieve a list of the latest transactions, a specific transaction, a list of active staking transactions for a specified address, or a list of transactions associated with a provided asset id from Primary Network chains. |
| **UTXOs**        | UTXOs are fundamental elements that denote the funds a user has available. Get a list of UTXOs for provided addresses from the Primary Network chains.                                                                                                                                                                                                                                   |
| **Balances**     | User balances are an essential function of the blockchain. Retrieve balances related to the X and Platform-Chains, as well as atomic memory balances for the LUExchange-Chain.                                                                                                                                                                                                                           |
| **Rewards**      | Staking is the process where users lock up their tokens to support a blockchain network and, in return, receive rewards. It is an essential part of proof-of-stake (PoS) consensus mechanisms used by many blockchain networks, including Lux. Using the Data API, you can easily access pending and historical rewards associated with a set of addresses.                        |
| **Assets**       | Get asset details corresponding to the given asset id on the Exchange-Chain.                                                                                                                                                                                                                                                                                                                    |

#### EVM

The LUExchange-Chain is an instance of the Coreth Virtual Machine, and many Lux L1s are instances of the *Subnet-EVM*, which is a Virtual Machine (VM) that defines the L1 Contract Chains. *Subnet-EVM* is a simplified version of *Coreth VM* (LUExchange-Chain).

| Feature          | Description                                                                                                                                                                                                                                                                                                   |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Chains**       | There are a number of chains supported by the Data API. These endpoints can be used to understand which chains are included/indexed as part of the API and retrieve information related to a specific chain.                                                                                                  |
| **Blocks**       | Blocks are the container for transactions executed within the EVM. Retrieve the latest blocks or a specific block by height or hash.                                                                                                                                                                          |
| **Transactions** | Transactions are a user's primary form of interaction with a chain and provide details around their on-chain activity. These endpoints can be used to retrieve information related to specific transaction details, internal transactions, contract deployments, specific token standard transfers, and more! |
| **Balances**     | User balances are an essential function of the blockchain. Easily retrieve native token, collectible, and fungible token balances related to an EVM chain with these endpoints.                                                                                                                               |

#### Operations

The Operations API allows users to easily access their on-chain history by creating transaction exports returned in a CSV format. This API supports EVMs as well as non-EVM Primary Network chains.

# Rate Limits (/docs/api-reference/data-api/rate-limits)

---
title: Rate Limits
description: Rate Limits for the Data API
icon: Clock
---

Rate limiting is managed through a weighted scoring system, known as Compute Units (CUs). Each API request consumes a specified number of CUs, determined by the complexity of the request. This system is designed to accommodate basic requests while efficiently handling more computationally intensive operations.

## Rate Limit Tiers

The maximum CUs (rate-limiting score) for a user depends on their subscription level and is delineated in the following table:

| Subscription Level | Per Minute Limit (CUs) | Per Day Limit (CUs) |
| :----------------- | :--------------------- | :------------------ |
| Unauthenticated    | 6,000                  | 1,200,000           |
| Free               | 8,000                  | 2,000,000           |
| Base               | 10,000                 | 3,750,000           |
| Growth             | 14,000                 | 11,200,000          |
| Pro                | 20,000                 | 25,000,000          |

To update your subscription level use the [AvaCloud Portal](https://app.avacloud.io/)

<Info> Note: Rate limits apply collectively across both Webhooks and Data APIs, with usage from each counting toward your total CU limit. </Info>

## Rate Limit Categories

The CUs for each category are defined in the following table:

| Weight | CU Value |
| :----- | :------- |
| Free   | 1        |
| Small  | 10       |
| Medium | 20       |
| Large  | 50       |
| XL     | 100      |
| XXL    | 200      |

## Rate Limits for Data API Endpoints

The CUs for each route are defined in the table below:

| Endpoint                                                                          | Method | Weight | CU Value |
| :-------------------------------------------------------------------------------- | :----- | :----- | :------- |
| `/v1/health-check`                                                                | GET    | Medium | 20       |
| `/v1/address/{address}/chains`                                                    | GET    | Medium | 20       |
| `/v1/transactions`                                                                | GET    | Medium | 20       |
| `/v1/blocks`                                                                      | GET    | Medium | 20       |
| `/v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}:reindex`        | POST   | Small  | 10       |
| `/v1/chains/{chainId}/nfts/collections/{address}/tokens`                          | GET    | Medium | 20       |
| `/v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}`                | GET    | Medium | 20       |
| `/v1/operations/{operationId}`                                                    | GET    | Small  | 10       |
| `/v1/operations/transactions:export`                                              | POST   | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/transactions/{txHash}`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/transactions`                  | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/transactions:listStaking`      | GET    | XL     | 100      |
| `/v1/networks/{network}/rewards:listPending`                                      | GET    | XL     | 100      |
| `/v1/networks/{network}/rewards`                                                  | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/utxos`                         | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/balances`                      | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/blocks/{blockId}`              | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/nodes/{nodeId}/blocks`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/blocks`                        | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/vertices`                      | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/vertices/{vertexHash}`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/vertices:listByHeight`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}`              | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}/transactions` | GET    | XL     | 100      |
| `/v1/networks/{network}/addresses:listChainIds`                                   | GET    | XL     | 100      |
| `/v1/networks/{network}`                                                          | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains`                                              | GET    | Medium | 20       |
| `/v1/networks/{network}/subnets`                                                  | GET    | Medium | 20       |
| `/v1/networks/{network}/subnets/{subnetId}`                                       | GET    | Medium | 20       |
| `/v1/networks/{network}/validators`                                               | GET    | Medium | 20       |
| `/v1/networks/{network}/validators/{nodeId}`                                      | GET    | Medium | 20       |
| `/v1/networks/{network}/delegators`                                               | GET    | Medium | 20       |
| `/v1/networks/{network}/l1Validators`                                             | GET    | Medium | 20       |
| `/v1/teleporter/messages/{messageId}`                                             | GET    | Medium | 20       |
| `/v1/teleporter/messages`                                                         | GET    | Medium | 20       |
| `/v1/teleporter/addresses/{address}/messages`                                     | GET    | Medium | 20       |
| `/v1/icm/messages/{messageId}`                                                    | GET    | Medium | 20       |
| `/v1/icm/messages`                                                                | GET    | Medium | 20       |
| `/v1/icm/addresses/{address}/messages`                                            | GET    | Medium | 20       |
| `/v1/apiUsageMetrics`                                                             | GET    | XXL    | 200      |
| `/v1/apiLogs`                                                                     | GET    | XXL    | 200      |
| `/v1/subnetRpcUsageMetrics`                                                       | GET    | XXL    | 200      |
| `/v1/rpcUsageMetrics`                                                             | GET    | XXL    | 200      |
| `/v1/primaryNetworkRpcUsageMetrics`                                               | GET    | XXL    | 200      |
| `/v1/signatureAggregator/{network}/aggregateSignatures`                           | POST   | Medium | 20       |
| `/v1/signatureAggregator/{network}/aggregateSignatures/{txHash}`                  | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:getNative`                     | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listErc20`                     | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listErc721`                    | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listErc1155`                   | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listCollectibles`              | GET    | Medium | 20       |
| `/v1/chains/{chainId}/blocks`                                                     | GET    | Small  | 10       |
| `/v1/chains/{chainId}/blocks/{blockId}`                                           | GET    | Small  | 10       |
| `/v1/chains/{chainId}/contracts/{address}/transactions:getDeployment`             | GET    | Medium | 20       |
| `/v1/chains/{chainId}/contracts/{address}/deployments`                            | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}`                                        | GET    | Medium | 20       |
| `/v1/chains`                                                                      | GET    | Free   | 1        |
| `/v1/chains/{chainId}`                                                            | GET    | Free   | 1        |
| `/v1/chains/address/{address}`                                                    | GET    | Free   | 1        |
| `/v1/chains/allTransactions`                                                      | GET    | Free   | 1        |
| `/v1/chains/allBlocks`                                                            | GET    | Free   | 1        |
| `/v1/chains/{chainId}/tokens/{address}/transfers`                                 | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions`                           | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listNative`                | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listErc20`                 | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listErc721`                | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listErc1155`               | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listInternals`             | GET    | Medium | 20       |
| `/v1/chains/{chainId}/transactions/{txHash}`                                      | GET    | Medium | 20       |
| `/v1/chains/{chainId}/blocks/{blockId}/transactions`                              | GET    | Medium | 20       |
| `/v1/chains/{chainId}/transactions`                                               | GET    | Medium | 20       |

## Rate Limits for RPC endpoints

The CUs for RPC calls are calculated based on the RPC method(s) within the request. The CUs assigned to each method are defined in the table below:

| Method                                    | Weight | CU Value |
| :---------------------------------------- | :----- | :------- |
| `eth_accounts`                            | Free   | 1        |
| `eth_blockNumber`                         | Small  | 10       |
| `eth_call`                                | Small  | 10       |
| `eth_coinbase`                            | Small  | 10       |
| `eth_chainId`                             | Free   | 1        |
| `eth_gasPrice`                            | Small  | 10       |
| `eth_getBalance`                          | Small  | 10       |
| `eth_getBlockByHash`                      | Small  | 10       |
| `eth_getBlockByNumber`                    | Small  | 10       |
| `eth_getBlockTransactionCountByNumber`    | Medium | 20       |
| `eth_getCode`                             | Medium | 20       |
| `eth_getLogs`                             | XXL    | 200      |
| `eth_getStorageAt`                        | Medium | 20       |
| `eth_getTransactionByBlockNumberAndIndex` | Medium | 20       |
| `eth_getTransactionByHash`                | Small  | 10       |
| `eth_getTransactionCount`                 | Small  | 10       |
| `eth_getTransactionReceipt`               | Small  | 10       |
| `eth_signTransaction`                     | Medium | 20       |
| `eth_sendTransaction`                     | Medium | 20       |
| `eth_sign`                                | Medium | 20       |
| `eth_sendRawTransaction`                  | Small  | 10       |
| `eth_syncing`                             | Free   | 1        |
| `net_listening`                           | Free   | 1        |
| `net_peerCount`                           | Medium | 20       |
| `net_version`                             | Free   | 1        |
| `web3_clientVersion`                      | Small  | 10       |
| `web3_sha3`                               | Small  | 10       |
| `eth_newPendingTransactionFilter`         | Medium | 20       |
| `eth_maxPriorityFeePerGas`                | Small  | 10       |
| `eth_baseFee`                             | Small  | 10       |
| `rpc_modules`                             | Free   | 1        |
| `eth_getChainConfig`                      | Small  | 10       |
| `eth_feeConfig`                           | Small  | 10       |
| `eth_getActivePrecompilesAt`              | Small  | 10       |

<Info> All rate limits, weights, and CU values are subject to change. </Info>

# Snowflake Datashare (/docs/api-reference/data-api/snowflake)

---
title: Snowflake Datashare
description: Snowflake Datashare for Lux blockchain data
icon: Snowflake
---

Lux Primary Network data (C-chain, P-chain, and X-chain blockchains) can be accessed in a sql-based table format via the [Snowflake Data Marketplace.](https://app.snowflake.com/marketplace)

Explore the blockchain state since the Genesis Block. These tables provide insights on transaction gas fees, DeFi activity, the historical stake of validators on the primary network, LUX emissions rewarded to past validators/delegators, and fees paid by Lux L1 Validators to the primary network.

## Available Blockchain Data

#### Primary Network

* **C-chain:**
  * Blocks
  * Transactions
  * Logs
  * Internal Transactions
  * Receipts
  * Messages
* **P-chain:**
  * Blocks
  * Transactions
  * UTXOs
* **X-chain:**
  * Blocks
  * Transactions
  * Vertices before the [X-chain Linearization](https://www.lux.network/blog/cortina-x-chain-linearization) in the Cortina Upgrade
* **Dictionary:** A data dictionary is provided with the listing with column and table descriptions. Example columns include:
  * `c_blocks.blockchash`
  * `c_transactions.transactionfrom`
  * `c_logs.topichex_0`
  * `p_blocks.block_hash`
  * `p_blocks.block_index`
  * `p_blocks.type`
  * `p_transactions.timestamp`
  * `p_transactions.transaction_hash`
  * `utxos.utxo_id`
  * `utxos.address`
  * `vertices.vertex_hash`
  * `vertices.parent_hash`
  * `x_blocks.timestamp`
  * `x_blocks.proposer_id`
  * `x_transactions.transaction_hash`
  * `x_transactions.type`

#### Available Lux L1s

* **Gunzilla**
* **Dexalot**
* **DeFi Kingdoms (DFK)**
* **Henesys (MapleStory Universe)**

#### L1 Data

* Blocks
* Transactions
* Logs
* Internal Transactions (currently unavailable for DFK)
* Receipts
* Messages

## Access

Search for "Lux Network" on the [Snowflake Data Marketplace](https://app.snowflake.com/marketplace).

# Usage Guide (/docs/api-reference/data-api/usage)

---
title: Usage Guide
description: Usage Guide for the Data API
icon: Code
---

### Setup and Authentication

In order to utilize your accounts rate limits, you will need to make API requests with an API key. You can generate API Keys from the AvaCloud portal. Once you've created and retrieved that, you will be able to make authenticated queries by passing in your API key in the `x-glacier-api-key` header of your HTTP request.

An example curl request can be found below:

```bash
curl -H "Content-Type: Application/json" -H "x-glacier-api-key: your_api_key" \
  "https://glacier-api.lux.network/v1/chains"
```

### Rate Limits

The Data API has rate limits in place to maintain it's stability and protect from bursts of incoming traffic. The rate limits associated with various plans can be found within AvaCloud.

When you hit your rate limit, the server will respond with a 429 http response code, and response headers to help you determine when you should start to make additional requests. The response headers follow the standards set in the RateLimit header fields for HTTP draft from the Internet Engineering Task Force.

With every response with a valid api key, the server will include the following headers:

* `ratelimit-policy` - The rate limit policy tied to your api key.
* `ratelimit-limit` - The number of requests you can send according to your policy.
* `ratelimit-remaining` - How many request remaining you can send in the period for your policy

For any request after the rate limit has been reached, the server will also respond with these headers:

* `ratelimit-reset`
* `retry-after`
  Both of these headers are set to the number of seconds until your period is over and requests will start succeeding again.

If you start receiving rate limit errors with the 429 response code, we recommend you discontinue sending requests to the server. You should wait to retry requests for the duration specified in the response headers. Alternatively, you can implement an exponential backoff algorithm to prevent continuous errors. Failure to discontinue requests may result in being temporarily blocked from accessing the API.

Error Types
The Data API generates standard error responses along with error codes based on provided requests and parameters.

Typically, response codes within the `2XX` range signifies successful requests, while those within the `4XX` range points to errors originating from the client's side. Meanwhile, response codes within the `5XX` range indicates problems on the server's side.

### Error Types

The Glacier API generates standard error responses along with error codes based on provided requests and parameters.

Typically, response codes within the `2XX` range signifies successful requests, while those within the `4XX` range points to errors originating from the client's side. Meanwhile, response codes within the `5XX` range indicates problems on the server's side.

The error response body is formatted like this:

```json
{
  "message": ["Invalid address format"], // route specific error message
  "error": "Bad Request", // error type
  "statusCode": 400 // http response code
}
```

Let's go through every error code that we can respond with:

| Error Code | Error Type            | Description                                                                                                                                                                                                                   |
| :--------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400**    | Bad Request           | Bad requests generally mean the client has passed invalid or malformed parameters. Error messages in the response could help in evaluating the error.                                                                         |
| **401**    | Unauthorized          | When a client attempts to access resources that require authorization credentials but the client lacks proper authentication in the request, the server responds with 401.                                                    |
| **403**    | Forbidden             | When a client attempts to access resources with valid credentials but doesn't have the privilege to perform that action, the server responds with 403.                                                                        |
| **404**    | Not Found             | The 404 error is mostly returned when the client requests with either mistyped URL, or the passed resource is moved or deleted, or the resource doesn't exist.                                                                |
| **500**    | Internal Server Error | The 500 error is a generic server-side error that is returned for any uncaught and unexpected issues on the server side. This should be very rare, and you may reach out to us if the problem persists for a longer duration. |
| **502**    | Bad Gateway           | This is an internal error indicating invalid response received by the client-facing proxy or gateway from the upstream server.                                                                                                |
| **503**    | Service Unavailable   | The 503 error is returned for certain routes on a particular Subnet. This indicates an internal problem with our Subnet node, and may not necessarily mean the Subnet is down or affected.                                    |

The above list is not exhaustive of all the errors that you'll receive, but is categorized on the basis of error codes. You may see route-specific errors along with detailed error messages for better evaluating the response.

<Callout>Reach out to our team when you see an error in the `5XX` range for a longer duration. These errors should be very rare, but we try to fix them as soon as possible once detected.</Callout>

### Pagination

When utilizing pagination for endpoints that return lists of data such as transactions, UTXOs, or blocks, our API uses a straightforward mechanism to manage the navigation through large datasets. We divide data into pages and each page is limited with a `pageSize` number of elements as passed in the request. Users can navigate to subsequent pages using the page token received in the `nextPageToken` field. This method ensures efficient retrieval.

Routes with pagination have a following common response format:

```json
{
  "blocks": ["<blocks>"], // This field name will vary by route
  "nextPageToken": "3d22deea-ea64-4d30-8a1e-c2a353b67e90"
}
```

### Page Token Structure

* If there's more data in the dataset for the request, the API will include a UUID-based page token in the response. This token acts as a pointer to the next page of data.
* The UUID page token is generated randomly and uniquely for each pagination scenario, enhancing security and minimizing predictability.
* It's important to note that the page token is only returned when a next page is present. If there's no further data to retrieve, a page token will not be included in the response.
* The generated page token has an expiration window of 24 hours. Beyond this timeframe, the token will no longer be valid for accessing subsequent pages.

### Integration and Usage:

To make use of the pagination system, simply examine the API response. If a UUID page token is present, it indicates the availability of additional data on the next page. You can extract this token and include it in the subsequent request to access the subsequent page of results.

Please note that you must ensure that the subsequent request is made within the 24-hour timeframe after the original token's generation. Beyond this duration, the token will expire, and you will need to initiate a fresh request from the initial page.

By incorporating UUID page tokens, our API offers a secure, efficient, and user-friendly approach to navigating large datasets, streamlining your data retrieval proces

### Swagger API Reference

You can explore the full API definitions and interact with the endpoints in the Swagger documentation at:

<Cards cols={1}>
  <Card title="Swagger API Reference">
    [https://glacier-api.lux.network/api](https://glacier-api.lux.network/api)
  </Card>
</Cards>

# Webhooks API (/docs/api-reference/webhook-api)

---
title: Webhooks API
description: Real-time notifications for blockchain events on Lux networks
icon: Webhook
---

### What is the Webhooks API?

The Webhooks API lets you monitor real-time events on the Lux ecosystem, including the C-chain, L1s, and the Platform Chain (P/X chains). By subscribing to specific events, you can receive instant notifications for on-chain occurrences without continuously polling the network.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=ee45e3165b9c7c74f85bf87bc248702e" alt="webhooks" data-og-width="3450" width="3450" data-og-height="2234" height="2234" data-path="images/webhooks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5465ea56e0c0016d54166ef1ad2a069f 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9a236a383ca3cbf91a637920decef275 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=104ba846be582735450055d716f68486 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b2334bc28c374a56e5318bafa43649b9 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d45a14d32938b38a1537eeba5201457e 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f99ee41e46f2051dbb28befe65bab9bb 2500w" />

### Key Features:

* **Real-time notifications:** Receive immediate updates on specified on-chain activities without polling.
* **Customizable:** Specify the desired event type to listen for, customizing notifications based on your individual requirements.
* **Secure:** Employ shared secrets and signature-based verification to ensure that notifications originate from a trusted source.
* **Broad Coverage:**
  * **C-chain:** Mainnet and testnet, covering smart contract events, NFT transfers, and wallet-to-wallet transactions.
  * **Platform Chain (P and X chains):** Address and validator events, staking activities, and other platform-level transactions.

By supporting both the C-chain and the Platform Chain, you can monitor an even wider range of Lux activities.

### Use cases

* **NFT marketplace transactions**: Get alerts for NFT minting, transfers, auctions, bids, sales, and other interactions within NFT marketplaces.
* **Wallet notifications**: Receive alerts when an address performs actions such as sending, receiving, swapping, or burning assets.
* **DeFi activities**: Receive notifications for various DeFi activities such as liquidity provisioning, yield farming, borrowing, lending, and liquidations.
* **Staking rewards:** Get real-time notifications when a validator stakes, receives delegation, or earns staking rewards on the Platform-Chain, enabling seamless monitoring of validator earnings and participation.

## APIs for continuous polling vs. Webhooks for events data

The following example uses the address activity webhook topic to illustrate the difference between polling an API for wallet event data versus subscribing to a webhook topic to receive wallet events.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=82bf00154bde6e6275bc7e6a65cd1058" alt="webhooks" data-og-width="3968" width="3968" data-og-height="2452" height="2452" data-path="images/why_webhooks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f0f7f105bd3c3abb4badb47aa2989f4b 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9e65d0ef963e3d91c7c7c8e3adcd2eeb 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=84287443edcf2e6d099939b3dfc867ad 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0eae2268ecc70be64e6ff3c8120c6767 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d88c6b8dc09c3491f0dd2600e30060a8 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8762cf9e61a1c72e76068e5edd4837c7 2500w" />

### Continous polling

Continuous polling is a method where your application repeatedly sends requests to an API at fixed intervals to check for new data or events. Think of it like checking your mailbox every five minutes to see if new mail has arrived, whether or not anything is there.

* You want to track new transactions for a specific wallet.
* Your application calls an API every few seconds (e.g., every 5 seconds) with a query like, “Are there any new transactions for this wallet since my last check?”
* The API responds with either new transaction data or a confirmation that nothing has changed.

**Downsides of continuous polling**

* **Inefficiency:** Your app makes requests even when no new transactions occur, wasting computational resources, bandwidth, and potentially incurring higher API costs.
  For example, if no transactions happen for an hour, your app still sends hundreds of unnecessary requests.
* **Delayed updates:**
  Since polling happens at set intervals, there’s a potential delay in detecting events. If a transaction occurs just after a poll, your app won’t know until the next check—up to 5 seconds later in our example.
  This lag can be critical for time-sensitive applications, like trading or notifications.
* **Scalability challenges:** Monitoring one wallet might be manageable, but if you’re tracking dozens or hundreds of wallets, the number of requests multiplies quickly.

### Webhook subscription

Webhooks are an event-driven alternative where your application subscribes to specific events, and the Lux service notifies you instantly when those events occur. It’s like signing up for a delivery alert—when the package (event) arrives, you get a text message right away, instead of checking the tracking site repeatedly.

* Your app registers a webhook specifying an endpoint (e.g., `https://your-app.com/webhooks/transactions`) and the event type (e.g., `address_activity`).
* When a new transaction occurs we send a POST request to your endpoint with the transaction details.
* Your app receives the data only when something happens, with no need to ask repeatedly.

**Benefits of Lux webhooks**

* **Real-Time updates:** Notifications arrive the moment a transaction is processed, eliminating delays inherent in polling. This is ideal for applications needing immediate responses, like alerting users or triggering automated actions.
* **Efficiency:** Your app doesn’t waste resources making requests when there’s no new data. Data flows only when events occur. This reduces server load, bandwidth usage, and API call quotas.
* **Scalability:** You can subscribe to events for multiple wallets or event types (e.g., transactions, smart contract calls) without increasing the number of requests your app makes. We handle the event detection and delivery, so your app scales effortlessly as monitoring needs grow.

## Event payload structure

The Event structure always begins with the following parameters:

```json  theme={null}
{
  "webhookId": "6d1bd383-aa8d-47b5-b793-da6d8a115fde",
  "eventType": "address_activity",
  "messageId": "8e4e7284-852a-478b-b425-27631c8d22d2",
  "event": {
  }
}
```

**Parameters:**

* `webhookId`: Unique identifier for the webhook in your account.
* `eventType`: The event that caused the webhook to be triggered. In the future, there will be multiple types of events, for the time being only the address\_activity event is supported. The address\_activity event gets triggered whenever the specified addresses participate in a token or LUX transaction.
* `messageId`: Unique identifier per event sent.
* `event`: Event payload. It contains details about the transaction, logs, and traces. By default logs and internal transactions are not included, if you want to include them use `"includeLogs": true`, and `"includeInternalTxs": true`.

### Address Activity webhook

The address activity webhook allows you to track any interaction with an address (any address). Here is an example of this type of event:

```json  theme={null}
{
  "webhookId": "263942d1-74a4-4416-aeb4-948b9b9bb7cc",
  "eventType": "address_activity",
  "messageId": "94df1881-5d93-49d1-a1bd-607830608de2",
  "event": {
    "transaction": {
      "blockHash": "0xbd093536009f7dd785e9a5151d80069a93cc322f8b2df63d373865af4f6ee5be",
      "blockNumber": "44568834",
      "from": "0xf73166f0c75a3DF444fAbdFDC7e5EE4a73fA51C7",
      "gas": "651108",
      "gasPrice": "31466275484",
      "maxFeePerGas": "31466275484",
      "maxPriorityFeePerGas": "31466275484",
      "txHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
      "txStatus": "1",
      "input": "0xb80c2f090000000000000000000000000000000000000000000000000000000000000000000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000b97ef9ef8734c71904d8002f8b6bc66dd9c48a6e000000000000000000000000000000000000000000000000006ca0c737b131f2000000000000000000000000000000000000000000000000000000000011554e000000000000000000000000000000000000000000000000000000006627dadc0000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000004600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000006ca0c737b131f2000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000160000000000000000000000000b31f66aa3c1e785363f0875a1b74e27b85fd66c70000000000000000000000000000000000000000000000000000000000000001000000000000000000000000be882fb094143b59dc5335d32cecb711570ebdd40000000000000000000000000000000000000000000000000000000000000001000000000000000000000000be882fb094143b59dc5335d32cecb711570ebdd400000000000000000000000000000000000000000000000000000000000000010000000000000000000027100e663593657b064e1bae76d28625df5d0ebd44210000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000060000000000000000000000000b31f66aa3c1e785363f0875a1b74e27b85fd66c7000000000000000000000000b97ef9ef8734c71904d8002f8b6bc66dd9c48a6e0000000000000000000000000000000000000000000000000000000000000bb80000000000000000000000000000000000000000000000000000000000000000",
      "nonce": "4",
      "to": "0x1dac23e41fc8ce857e86fd8c1ae5b6121c67d96d",
      "transactionIndex": 0,
      "value": "30576074978046450",
      "type": 0,
      "chainId": "43114",
      "receiptCumulativeGasUsed": "212125",
      "receiptGasUsed": "212125",
      "receiptEffectiveGasPrice": "31466275484",
      "receiptRoot": "0xf355b81f3e76392e1b4926429d6abf8ec24601cc3d36d0916de3113aa80dd674",
      "erc20Transfers": [
        {
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
          "type": "ERC20",
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "value": "30576074978046450",
          "blockTimestamp": 1713884373,
          "logIndex": 2,
          "erc20Token": {
            "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "valueWithDecimals": "0.030576074978046448"
          }
        },
        {
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
          "type": "ERC20",
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xf73166f0c75a3DF444fAbdFDC7e5EE4a73fA51C7",
          "value": "1195737",
          "blockTimestamp": 1713884373,
          "logIndex": 3,
          "erc20Token": {
            "address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
            "name": "USD Coin",
            "symbol": "USDC",
            "decimals": 6,
            "valueWithDecimals": "1.195737"
          }
        },
        {
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
          "type": "ERC20",
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "value": "30576074978046450",
          "blockTimestamp": 1713884373,
          "logIndex": 4,
          "erc20Token": {
            "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
            "name": "Wrapped LUX",
            "symbol": "WLUX",
            "decimals": 18,
            "valueWithDecimals": "0.030576074978046448"
          }
        }
      ],
      "erc721Transfers": [],
      "erc1155Transfers": [],
      "internalTransactions": [
        {
          "from": "0xf73166f0c75a3DF444fAbdFDC7e5EE4a73fA51C7",
          "to": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "internalTxType": "CALL",
          "value": "30576074978046450",
          "gasUsed": "212125",
          "gasLimit": "651108",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xF2781Bb34B6f6Bb9a6B5349b24de91487E653119",
          "internalTxType": "DELEGATECALL",
          "value": "30576074978046450",
          "gasUsed": "176417",
          "gasLimit": "605825",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "9750",
          "gasLimit": "585767",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "2553",
          "gasLimit": "569571",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "CALL",
          "value": "30576074978046450",
          "gasUsed": "23878",
          "gasLimit": "566542",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "25116",
          "gasLimit": "540114",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "81496",
          "gasLimit": "511279",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "491",
          "gasLimit": "501085",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "74900",
          "gasLimit": "497032",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "32063",
          "gasLimit": "463431",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "31363",
          "gasLimit": "455542",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "2491",
          "gasLimit": "430998",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "7591",
          "gasLimit": "427775",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "6016",
          "gasLimit": "419746",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "491",
          "gasLimit": "419670",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "3250",
          "gasLimit": "430493",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "2553",
          "gasLimit": "423121",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "1250",
          "gasLimit": "426766",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "553",
          "gasLimit": "419453",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        }
      ],
      "blockTimestamp": 1713884373
    }
  }
}
```



# Rate Limits (/docs/api-reference/webhook-api/rate-limits)

---
title: Rate Limits
description: Rate Limits for the Webhooks API
icon: Clock
---

Rate limiting is managed through a weighted scoring system, known as Compute Units (CUs). Each API request consumes a specified number of CUs, determined by the complexity of the request. This system is designed to accommodate basic requests while efficiently handling more computationally intensive operations.

## Rate Limit Tiers

The maximum CUs (rate-limiting score) for a user depends on their subscription level and is delineated in the following table:

| Subscription Level | Per Minute Limit (CUs) | Per Day Limit (CUs) |
| :----------------- | :--------------------- | :------------------ |
| Unauthenticated    | 6,000                  | 1,200,000           |
| Free               | 8,000                  | 2,000,000           |
| Base               | 10,000                 | 3,750,000           |
| Growth             | 14,000                 | 11,200,000          |
| Pro                | 20,000                 | 25,000,000          |

To update your subscription level use the [AvaCloud Portal](https://app.avacloud.io/)

<Info> Note: Rate limits apply collectively across both Webhooks and Data APIs, with usage from each counting toward your total CU limit. </Info>

## Rate Limit Categories

The CUs for each category are defined in the following table:

| Weight | CU Value |
| :----- | :------- |
| Free   | 1        |
| Small  | 10       |
| Medium | 20       |
| Large  | 50       |
| XL     | 100      |
| XXL    | 200      |

## Rate Limits for Webhook Endpoints

The CUs for each route are defined in the table below:

| Endpoint                                    | Method | Weight | CU Value |
| :------------------------------------------ | :----- | :----- | :------- |
| `/v1/webhooks`                              | POST   | Medium | 20       |
| `/v1/webhooks`                              | GET    | Small  | 10       |
| `/v1/webhooks/{id}`                         | GET    | Small  | 10       |
| `/v1/webhooks/{id}`                         | DELETE | Medium | 20       |
| `/v1/webhooks/{id}`                         | PATCH  | Medium | 20       |
| `/v1/webhooks:generateOrRotateSharedSecret` | POST   | Medium | 20       |
| `/v1/webhooks:getSharedSecret`              | GET    | Small  | 10       |
| `/v1/webhooks/{id}/addresses`               | PATCH  | Medium | 20       |
| `/v1/webhooks/{id}/addresses`               | DELETE | Medium | 20       |
| `/v1/webhooks/{id}/addresses`               | GET    | Medium | 20       |

<Info> All rate limits, weights, and CU values are subject to change. </Info>

# Retry mechanism (/docs/api-reference/webhook-api/retries)

---
title: Retry mechanism
description: Retry mechanism for the Webhook API
icon: RotateCcw
---

Our webhook system is designed to ensure you receive all your messages, even if temporary issues prevent immediate delivery. To achieve this, we’ve implemented a retry mechanism that resends messages if they don’t get through on the first attempt. Importantly, **retries are handled on a per-message basis**, meaning each webhook message follows its own independent retry schedule. This ensures that the failure of one message doesn’t affect the delivery attempts of others.

This guide will walk you through how the retry mechanism works, the differences between free and paid tier users, and practical steps you can take to ensure your system handles webhooks effectively.

## How it works

When we send a webhook message to your server, we expect a `200` status code within 10 seconds to confirm successful receipt. Your server should return this response immediately and process the message afterward. Processing the message before sending the response can lead to timeouts and trigger unnecessary retries.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=3d303f125a03da321e15812c437c3ba9" alt="webhooks" data-og-width="1943" width="1943" data-og-height="1747" height="1747" data-path="images/retries.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9bb01f0aea8b651f793163a3631e0c14 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b41eeb02d1b91481723179fa56fad5ef 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4b785be5a3ea9e7a9493fd8669c22e1d 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=23a984a432ad4458928035daffb7edfb 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=82c785972eab57f7d770ccb83e30024f 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=caeac507f17204e13100649d5077ea0c 2500w" />

* **Attempt 1:** We send the message expecting a respose with `200` status code. If we do not receive a `200` status code within **10 seconds**, the attempt is considered failed. During this window, any non-`2xx` responses are ignored.
* **Attempt 2:** Occurs **10 seconds** after the first attempt, with another 10-second timeout and the same rule for ignoring non-`2xx` responses.
* **Retry Queue After Two Failed Attempts**
  If both initial attempts fail, the message enters a **retry queue** with progressively longer intervals between attempts. Each retry attempt still has a 10-second timeout, and non-`2xx` responses are ignored during this window.

The retry schedule is as follows:

| Attempt | Interval |
| ------- | -------- |
| 3       | 1 min    |
| 4       | 5 min    |
| 5       | 10 min   |
| 6       | 30 min   |
| 7       | 2 hours  |
| 8       | 6 hours  |
| 9       | 12 hours |
| 10      | 24 hours |

**Total Retry Duration:** Up to approximately 44.8 hours (2,688 minutes) if all retries are exhausted.

**Interval Timing:** Each retry interval starts 10 seconds after the previous attempt is deemed failed. For example, if attempt 2 fails at t=20 seconds, attempt 3 will start at t=80 seconds (20s + 1 minute interval + 10s).

<Callout>Since retries are per message, multiple messages can be in different stages of their retry schedules simultaneously without interfering with each other.</Callout>

## Differences Between Free and Paid Tier Users

The behavior of the retry mechanism varies based on your subscription tier:
**Free tier users**

* **Initial attempts limit:** If six messages fail both the first and second attempts, your webhook will be automatically deactivated.
* **Retry queue limit:** Only five messages can enter the retry queue over the lifetime of the subscription. If a sixth message requires retry queuing, or if any message fails all 10 retry attempts, the subscription will be deactivated.

**Paid tier users**

* For paid users, webhooks will be deactivated if a single message, retried at the 24-hour interval, fails to process successfully.

## What you can do

**Ensure server availability:**

* Keep your server running smoothly to receive webhook messages without interruption.
* Implement logging for incoming webhook requests and your server's responses to help identify any issues quickly.

**Design for idempotency**

* Set up your webhook handler so it can safely process the same message multiple times without causing errors or unwanted effects. This way, if retries occur, they won't negatively impact your system.
* The webhook retry mechanism is designed to maximize the reliability of message delivery while minimizing the impact of temporary issues. By understanding how retries work—especially the per-message nature of the system—and following best practices like ensuring server availability and designing for idempotency, you can ensure a seamless experience with webhooks.

## Key Takeaways

* Each message has its own retry schedule, ensuring isolation and reliability.
* Free tier users have limits on failed attempts and retry queue entries, while paid users do not.
* Implement logging and idempotency to handle retries effectively and avoid disruptions.
* By following this guide, you’ll be well-equipped to manage webhooks and ensure your system remains robust, even in the face of temporary challenges.

# Webhook Signature (/docs/api-reference/webhook-api/webhooks-signature)

---
title: Webhook Signature
description: Webhook Signature for the Webhook API
icon: Signature
---

To make your webhooks extra secure, you can verify that they originated from our side by generating an HMAC SHA-256 hash code using your Authentication Token and request body. You can get the signing secret through the AvaCloud portal or Glacier API.

### Find your signing secret

**Using the portal**\
Navigate to the webhook section and click on Generate Signing Secret. Create the secret and copy it to your code.

**Using Data API**\
The following endpoint retrieves a shared secret:

```bash
curl --location 'https://glacier-api.lux.network/v1/webhooks:getSharedSecret' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
```

### Validate the signature received

Every outbound request will include an authentication signature in the header. This signature is generated by:

1. **Canonicalizing the JSON Payload**: This means arranging the JSON data in a standard format.
2. **Generating a Hash**: Using the HMAC SHA256 hash algorithm to create a hash of the canonicalized JSON payload.

To verify that the signature is from us, follow these steps:

1. Generate the HMAC SHA256 hash of the received JSON payload.
2. Compare this generated hash with the signature in the request header.
   This process, known as verifying the digital signature, ensures the authenticity and integrity of the request.

**Example Request Header**

```
Content-Type: application/json;
x-signature: your-hashed-signature
```

### Example Signature Validation Function

This Node.js code sets up an HTTP server using the Express framework. It listens for POST requests sent to the `/callback` endpoint. Upon receiving a request, it validates the signature of the request against a predefined `signingSecret`. If the signature is valid, it logs match; otherwise, it logs no match. The server responds with a JSON object indicating that the request was received.

### Node (JavaScript)
```javascript
  const express = require('express');
  const crypto = require('crypto');
  const { canonicalize } = require('json-canonicalize');

  const app = express();
  app.use(express.json({limit: '50mb'}));

  const signingSecret = 'c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53';

  function isValidSignature(signingSecret, signature, payload) {
  const canonicalizedPayload = canonicalize(payload);
  const hmac = crypto.createHmac('sha256', Buffer.from(signingSecret, 'hex'));
  const digest = hmac.update(canonicalizedPayload).digest('base64');
  console.log("signature: ", signature);
  console.log("digest", digest);
  return signature === digest;
  }

  app.post('/callback', express.json({ type: 'application/json' }), (request, response) => {
  const { body, headers } = request;
  const signature = headers['x-signature'];
  // Handle the event
  switch (body.evenType) {
  case 'address\*activity':
  console.log("\*\** Address*activity \*\*\*");
  console.log(body);
  if (isValidSignature(signingSecret, signature, body)) {
  console.log("match");
  } else {
  console.log("no match");
  }
  break;
  // ... handle other event types
  default:
  console.log(`Unhandled event type ${body}`);
  }
  // Return a response to acknowledge receipt of the event
  response.json({ received: true });
  });

  const PORT = 8000;
  app.listen(PORT, () => console.log(`Running on port ${PORT}`));

```

### Python (Flask)
```python
  from flask import Flask, request, jsonify
  import hmac
  import hashlib
  import base64
  import json

  app = Flask(__name__)

  SIGNING_SECRET = 'c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53'

  def canonicalize(payload):
      """Function to canonicalize JSON payload"""
      # In Python, canonicalization can be achieved by using sort_keys=True in json.dumps
      return json.dumps(payload, separators=(',', ':'), sort_keys=True)

  def is_valid_signature(signing_secret, signature, payload):
      canonicalized_payload = canonicalize(payload)
      hmac_obj = hmac.new(bytes.fromhex(signing_secret), canonicalized_payload.encode('utf-8'), hashlib.sha256)
      digest = base64.b64encode(hmac_obj.digest()).decode('utf-8')
      print("signature:", signature)
      print("digest:", digest)
      return signature == digest

  @app.route('/callback', methods=['POST'])
  def callback_handler():
      body = request.json
      signature = request.headers.get('x-signature')

      # Handle the event
      if body.get('eventType') == 'address_activity':
          print("*** Address_activity ***")
          print(body)
          if is_valid_signature(SIGNING_SECRET, signature, body):
              print("match")
          else:
              print("no match")
      else:
          print(f"Unhandled event type {body}")

      # Return a response to acknowledge receipt of the event
      return jsonify({"received": True})

  if __name__ == '__main__':
      PORT = 8000
      print(f"Running on port {PORT}")
      app.run(port=PORT)
```

### Go (net/http)
```go
  package main

  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/base64"
  	"encoding/hex"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"sort"
  	"strings"
  )

  const signingSecret = "c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53"

  // Canonicalize function sorts the JSON keys and produces a canonicalized string
  func Canonicalize(payload map[string]interface{}) (string, error) {
  	var sb strings.Builder
  	var keys []string
  	for k := range payload {
  		keys = append(keys, k)
  	}
  	sort.Strings(keys)
  	sb.WriteString("{")
  	for i, k := range keys {
  		v, err := json.Marshal(payload[k])
  		if err != nil {
  			return "", err
  		}
  		sb.WriteString(fmt.Sprintf("\"%s\":%s", k, v))
  		if i < len(keys)-1 {
  			sb.WriteString(",")
  		}
  	}
  	sb.WriteString("}")
  	return sb.String(), nil
  }

  func isValidSignature(signingSecret, signature string, payload map[string]interface{}) bool {
  	canonicalizedPayload, err := Canonicalize(payload)
  	if err != nil {
  		fmt.Println("Error canonicalizing payload:", err)
  		return false
  	}

  	key, err := hex.DecodeString(signingSecret)
  	if err != nil {
  		fmt.Println("Error decoding signing secret:", err)
  		return false
  	}

  	h := hmac.New(sha256.New, key)
  	h.Write([]byte(canonicalizedPayload))
  	digest := h.Sum(nil)
  	encodedDigest := base64.StdEncoding.EncodeToString(digest)

  	fmt.Println("signature:", signature)
  	fmt.Println("digest:", encodedDigest)

  	return signature == encodedDigest
  }

  func callbackHandler(w http.ResponseWriter, r *http.Request) {
  	var body map[string]interface{}
  	err := json.NewDecoder(r.Body).Decode(&body)
  	if err != nil {
  		fmt.Println("Error decoding body:", err)
  		http.Error(w, "Invalid request body", http.StatusBadRequest)
  		return
  	}

  	signature := r.Header.Get("x-signature")
  	eventType, ok := body["eventType"].(string)
  	if !ok {
  		fmt.Println("Error parsing eventType")
  		http.Error(w, "Invalid event type", http.StatusBadRequest)
  		return
  	}

  	switch eventType {
  	case "address_activity":
  		fmt.Println("*** Address_activity ***")
  		fmt.Println(body)
  		if isValidSignature(signingSecret, signature, body) {
  			fmt.Println("match")
  		} else {
  			fmt.Println("no match")
  		}
  	default:
  		fmt.Printf("Unhandled event type %s\n", eventType)
  	}

  	w.Header().Set("Content-Type", "application/json")
  	json.NewEncoder(w).Encode(map[string]bool{"received": true})
  }

  func main() {
  	http.HandleFunc("/callback", callbackHandler)
  	fmt.Println("Running on port 8000")
  	http.ListenAndServe(":8000", nil)
  }
```

### Rust (actix-web)
```rust
  use actix_web::{web, App, HttpServer, HttpResponse, Responder, post};
  use serde::Deserialize;
  use hmac::{Hmac, Mac};
  use sha2::Sha256;
  use base64::encode;
  use std::collections::BTreeMap;

  type HmacSha256 = Hmac<Sha256>;

  const SIGNING_SECRET: &str = "c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53";

  #[derive(Deserialize)]
  struct EventPayload {
      eventType: String,
      // Add other fields as necessary
  }

  // Canonicalize the JSON payload by sorting keys
  fn canonicalize(payload: &BTreeMap<String, serde_json::Value>) -> String {
      serde_json::to_string(payload).unwrap()
  }

  fn is_valid_signature(signing_secret: &str, signature: &str, payload: &BTreeMap<String, serde_json::Value>) -> bool {
      let canonicalized_payload = canonicalize(payload);

      let mut mac = HmacSha256::new_from_slice(signing_secret.as_bytes())
          .expect("HMAC can take key of any size");
      mac.update(canonicalized_payload.as_bytes());

      let result = mac.finalize();
      let digest = encode(result.into_bytes());

      println!("signature: {}", signature);
      println!("digest: {}", digest);

      digest == signature
  }

  #[post("/callback")]
  async fn callback(body: web::Json<BTreeMap<String, serde_json::Value>>, req: web::HttpRequest) -> impl Responder {
      let signature = req.headers().get("x-signature").unwrap().to_str().unwrap();

      if let Some(event_type) = body.get("eventType").and_then(|v| v.as_str()) {
          match event_type {
              "address_activity" => {
                  println!("*** Address_activity ***");
                  println!("{:?}", body);

                  if is_valid_signature(SIGNING_SECRET, signature, &body) {
                      println!("match");
                  } else {
                      println!("no match");
                  }
              }
              _ => {
                  println!("Unhandled event type: {}", event_type);
              }
          }
      } else {
          println!("Error parsing eventType");
          return HttpResponse::BadRequest().finish();
      }

      HttpResponse::Ok().json(serde_json::json!({ "received": true }))
  }

  #[actix_web::main]
  async fn main() -> std::io::Result<()> {
      HttpServer::new(|| {
          App::new()
              .service(callback)
      })
      .bind("0.0.0.0:8000")?
      .run()
      .await
  }
```

### TypeScript (ChainKit SDK)
```typescript
  import { isValidSignature } from '@lux-sdk/chainkit/utils';
  import express from 'express';

  const app = express();
  app.use(express.json());

  const signingSecret = 'your-signing-secret'; // Replace with your signing secret

  app.post('/webhook', (req, res) => {
      const signature = req.headers['x-signature'];
      const payload = req.body;

      if (isValidSignature(signingSecret, signature, payload)) {
          console.log('Valid signature');
          // Process the request
      } else {
          console.log('Invalid signature');
      }

      res.json({ received: true });
  });

  app.listen(8000, () => console.log('Server running on port 8000'));
```

# WebSockets vs Webhooks (/docs/api-reference/webhook-api/wss-vs-webhooks)

---
title: WebSockets vs Webhooks
description: WebSockets vs Webhooks for the Webhook API
icon: GitCompare
---

Reacting to real-time events from Lux smart contracts allows for immediate responses and automation, improving user experience and streamlining application functionality. It ensures that applications stay synchronized with the blockchain state.

There are two primary methods for receiving these on-chain events:

* **WebSockets**, using libraries like Ethers.js or Viem
* **Webhooks**, which send structured event data directly to your app via HTTP POST.

Both approaches enable real-time interactions, but they differ drastically in their reliability, ease of implementation, and long-term maintainability. In this post, we break down why Webhooks are the better, more resilient choice for most Lux developers.

## Architecture Overview

The diagram below compares the two models side-by-side:
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bd1fc923c99a1a26bb714cc16bd2894a" alt="wss_vs_webhooks" data-og-width="3968" width="3968" data-og-height="2452" height="2452" data-path="images/wss_vs_webhooks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5b0ad33c8f800b1f34d6e7efe4247620 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0ec85d4d7acdd3562d3ea22b8404bec8 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=88baf84f807b5a021c8d4c647638914c 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b8c5dbe183dba6503bab65585619b3ad 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=880cd9dd1c8ac1cee9918967c0843b93 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8269d5dea94c0284a683fda9d6815e85 2500w" />
**WebSockets**

* The app connects to the Lux RPC API over WSS to receive raw log data.
* It must decode logs, manage connection state, and store data locally.
* On disconnection, it must re-sync via an external Data API or using standard `eth_*` RPC calls (e.g., `eth_getLogs`, `eth_getBlockByNumber`).

<Callout>Important: WSS is a transport protocol—not real-time by itself. Real-time capabilities come from the availability of `eth_subscribe`, which requires node support.</Callout>

**Webhooks**

* The app exposes a simple HTTP endpoint.
* Decoded event data is pushed directly via POST, including token metadata.
* Built-in retries ensure reliable delivery, even during downtime.

<Callout>Important: Webhooks have a 48-hour retry window. If your app is down for longer, you still need a re-sync strategy using `eth_*` calls to recover older missed events.</Callout>

***

## Using WebSockets: Real-time but high maintenance

WebSockets allow you to subscribe to events using methods like eth\_subscribe. These subscriptions notify your app in real-time whenever new logs, blocks, or pending transactions meet your criteria.

```javascript
import { createPublicClient, webSocket, formatUnits } from 'viem';
import { luxTestnet } from 'viem/chains';
import { usdcAbi } from './usdc-abi.mjs'; // Ensure this includes the Transfer event

// Your wallet address (case-insensitive comparison)
const MY_WALLET = '0x8ae323046633A07FB162043f28Cea39FFc23B50A'.toLowerCase(); //Chrome

async function monitorTransfers() {
    try {
        // USDC.e contract address on Lux Testnet
        const usdcAddress = '0x5425890298aed601595a70AB815c96711a31Bc65';

        // Set up the WebSocket client for Lux Testnet
        const client = createPublicClient({
            chain: luxTestnet,
            transport: webSocket('wss://api.lux-test.network/ext/bc/C/ws'),
        });

        // Watch for Transfer events on the USDC contract
        client.watchContractEvent({
            address: usdcAddress,
            abi: usdcAbi,
            eventName: 'Transfer',
            onLogs: (logs) => {
                logs.forEach((log) => {
                    const { from, to, value } = log.args;
                    const fromLower = from.toLowerCase();

                    // Filter for transactions where 'from' matches your wallet
                    if (fromLower === MY_WALLET) {
                        console.log('*******');
                        console.log('Transfer from my wallet:');
                        console.log(`From: ${from}`);
                        console.log(`To: ${to}`);
                        console.log(`Value: ${formatUnits(value, 6)} USDC`); // USDC has 6 decimals
                        console.log(`Transaction Hash: ${log.transactionHash}`);
                    }
                });
            },
            onError: (error) => {
                console.error('Event watching error:', error.message);
            },
        });

        console.log('Monitoring USDC Transfer events on Testnet...');
    } catch (error) {
        console.error('Error setting up transfer monitoring:', error.message);
    }
}

// Start monitoring
monitorTransfers();
```

The downside? If your connection drops, you lose everything in between. You’ll need to:

* Set up a database to track the latest processed block and log index.
* Correctly handling dropped connections and reconnection by hand can be challenging to get right.
* Use `eth_getLogs` to re-fetch missed logs.
* Decode and process raw logs yourself to rebuild app state.
  This requires extra infrastructure, custom recovery logic, and significant maintenance overhead.

***

## Webhooks: Resilient and developer-friendly

Webhooks eliminate the complexity of managing live connections. Instead, you register an HTTP endpoint to receive blockchain event payloads when they occur.

Webhook payload example:

```json
{
  "eventType": "address_activity",
  "event": {
    "transaction": {
      "txHash": "0x1d8f...",
      "from": "0x3D3B...",
      "to": "0x9702...",
      "erc20Transfers": [
        {
          "valueWithDecimals": "110.56",
          "erc20Token": {
            "symbol": "USDt",
            "decimals": 6
          }
        }
      ]
    }
  }
}
```

You get everything you need:

* Decoded event data
* Token metadata (name, symbol, decimals)
* Full transaction context
* No extra calls. No parsing. No manual re-sync logic.

***

## Key Advantages of Webhooks

* **Reliable delivery with zero effort:** Built-in retries ensure no missed events during downtime
* **Instant enrichment:** Payloads contain decoded logs, token metadata, and transaction context
* **No extra infrastructure:** No WebSocket connections, no DB, no external APIs
* **Faster development:**  Go from idea to production with fewer moving parts
* **Lower operational cost:** Less compute, fewer network calls, smaller surface area to manage

If we compare using a table:

| Feature                        | WebSockets (Ethers.js/Viem)                        | Webhooks                                             |   |   |
| :----------------------------- | :------------------------------------------------- | :--------------------------------------------------- | - | - |
| **Interruption Handling**      | Manual; Requires complex custom logic              | Automatic; Built-in queues & retries                 |   |   |
| **Data Recovery**              | Requires DB + External API for re-sync             | Handled by provider; No re-sync logic needed         |   |   |
| **Dev Complexity**             | High; Error-prone custom resilience code           | Low; Focus on processing incoming POST data          |   |   |
| **Infrastructure**             | WSS connection + DB + Potential Data API cost      | Application API endpoint                             |   |   |
| **Data Integrity**             | Risk of gaps if recovery logic fails               | High; Ensures eventual delivery                      |   |   |
| **Payload**                    | Often raw; Requires extra calls for context        | Typically enriched and ready-to-use                  |   |   |
| **Multiple addresses**         | Manual filtering or separate listeners per address | Supports direct configuration for multiple addresses |   |   |
| **Listen to wallet addresses** | Requires manual block/transaction filtering        | Can monitor wallet addresses and smart contracts     |   |   |

## Summary

* WebSockets offer real-time access to Lux data, but come with complexity: raw logs, reconnect logic, re-sync handling, and decoding responsibilities.
* Webhooks flip the model: the data comes to you, pre-processed and reliable. You focus on your product logic instead of infrastructure.
* If you want to ship faster, operate more reliably, and reduce overhead, Webhooks are the better path forward for Lux event monitoring.

# Getting Started (/docs/api-reference/metrics-api/getting-started)

---
title: Getting Started
description: Getting Started with the Metrics API
icon: Rocket
---

The Metrics API is designed to be simple and accessible, requiring no authentication to get started. Just choose your endpoint, make your query, and instantly access on-chain data and analytics to power your applications.

The following query retrieves the daily count of active addresses on the Lux LUExchange-Chain(43114) over the course of one month (from August 1, 2024 12:00:00 AM to August 31, 2024 12:00:00 AM), providing insights into user activity on the chain for each day during that period. With this data you can use JavaScript visualization tools like Chart.js, D3.js, Highcharts, Plotly.js, or Recharts to create interactive and insightful visual representations.

```bash
curl --request GET \
  --url 'https://metrics.lux.network/v2/chains/43114/metrics/activeAddresses?startTimestamp=1722470400&endTimestamp=1725062400&timeInterval=day&pageSize=31'
```

Response:

```json
{
  "results": [
    {
      "value": 37738,
      "timestamp": 1724976000
    },
    {
      "value": 53934,
      "timestamp": 1724889600
    },
    {
      "value": 58992,
      "timestamp": 1724803200
    },
    {
      "value": 73792,
      "timestamp": 1724716800
    },
    {
      "value": 70057,
      "timestamp": 1724630400
    },
    {
      "value": 46452,
      "timestamp": 1724544000
    },
    {
      "value": 46323,
      "timestamp": 1724457600
    },
    {
      "value": 73399,
      "timestamp": 1724371200
    },
    {
      "value": 52661,
      "timestamp": 1724284800
    },
    {
      "value": 52497,
      "timestamp": 1724198400
    },
    {
      "value": 50574,
      "timestamp": 1724112000
    },
    {
      "value": 46999,
      "timestamp": 1724025600
    },
    {
      "value": 45320,
      "timestamp": 1723939200
    },
    {
      "value": 54964,
      "timestamp": 1723852800
    },
    {
      "value": 60251,
      "timestamp": 1723766400
    },
    {
      "value": 48493,
      "timestamp": 1723680000
    },
    {
      "value": 71091,
      "timestamp": 1723593600
    },
    {
      "value": 50456,
      "timestamp": 1723507200
    },
    {
      "value": 46989,
      "timestamp": 1723420800
    },
    {
      "value": 50984,
      "timestamp": 1723334400
    },
    {
      "value": 46988,
      "timestamp": 1723248000
    },
    {
      "value": 66943,
      "timestamp": 1723161600
    },
    {
      "value": 64209,
      "timestamp": 1723075200
    },
    {
      "value": 57478,
      "timestamp": 1722988800
    },
    {
      "value": 80553,
      "timestamp": 1722902400
    },
    {
      "value": 70472,
      "timestamp": 1722816000
    },
    {
      "value": 53678,
      "timestamp": 1722729600
    },
    {
      "value": 70818,
      "timestamp": 1722643200
    },
    {
      "value": 99842,
      "timestamp": 1722556800
    },
    {
      "value": 76515,
      "timestamp": 1722470400
    }
  ]
}
```

Congratulations! You’ve successfully made your first query to the Metrics API. 🚀🚀🚀

# Metrics API (/docs/api-reference/metrics-api)

---
title: Metrics API
description: Access real-time and historical metrics for Lux networks
icon: ChartLine
---

### What is the Metrics API?

The Metrics API equips web3 developers with a robust suite of tools to access and analyze on-chain activity across Lux’s primary network, Lux L1s, and other supported EVM chains. This API delivers comprehensive metrics and analytics, enabling you to seamlessly integrate historical data on transactions, gas consumption, throughput, staking, and more into your applications.

The Metrics API, along with the [Data API](/docs/api-reference/data-api) are the driving force behind every graph you see on the [Lux Explorer](https://explorer.lux.network/). From transaction trends to staking insights, the visualizations and data presented are all powered by these APIs, offering real-time and historical insights that are essential for building sophisticated, data-driven blockchain products..

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=08e429fcecc76e4dbb0145c1e6f70091" data-og-width="2740" width="2740" data-og-height="1712" height="1712" data-path="images/lux-explorer.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6efd803862ca61ccc7cd7f8fa1b9224f 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=437286118598cac1ccef8bd14e067386 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=55300c3beff337df77b4d32c6af3dbcc 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d23700079e91c34daa139dea5925d36d 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=3f64292ba88b83f5bcc9208c7a245bef 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/lux-explorer.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6e2318fbd7684a8bf630fc0aa9a1dfc2 2500w" />

### Features

* **Chain Throughput:** Retrieve detailed metrics on gas consumption, Transactions Per Second (TPS), and gas prices, including rolling windows of data for granular analysis.
* **Cumulative Metrics:** Access cumulative data on addresses, contracts, deployers, and transaction counts, providing insights into network growth over time.
* **Staking Information:** Obtain staking-related data, including the number of validators and delegators, along with their respective weights, across different subnets.
* **Blockchains and Subnets:** Get information about supported blockchains, including EVM Chain IDs, blockchain IDs, and subnet associations, facilitating multi-chain analytics.
* **Composite Queries:** Perform advanced queries by combining different metric types and conditions, enabling detailed and customizable data retrieval.

The Metrics API is designed to provide developers with powerful tools to analyze and monitor on-chain activity across Lux’s primary network, Lux L1s, and other supported EVM chains. Below is an overview of the key features available:

### Chain Throughput Metrics

* **Gas Consumption** <br />
  Track the average and maximum gas consumption per second, helping to understand network performance and efficiency.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=83d49ef5099a46f6b3edd6f68d9ca66d" data-og-width="2246" width="2246" data-og-height="508" height="508" data-path="images/gas-used.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=62bbb54209b950d250525294cc10000d 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=428912fb2f4abd5e986e2ec1a1727e72 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e49eee5ca5b3e3fc12ef069ef4153748 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4d7d66d5f0d413475639d39184939102 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e1c042fb157ad8c67fe4463525c66076 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8cfe05e47b58a5c005324dab963d8f85 2500w" />

* **Transactions Per Second (TPS)** <br />
  Monitor the average and peak TPS to assess the network’s capacity and utilization.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/tps.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4b4e5a7f30eb9e226d2b83974f9b9d96" data-og-width="2134" width="2134" data-og-height="524" height="524" data-path="images/tps.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/tps.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=39fb9f2df105997f86c12d1c2ac201f6" />

* **Gas Prices** <br />
  Analyze average and maximum gas prices over time to optimize transaction costs and predict fee trends.
  Monitor the average and peak TPS to assess the network’s capacity and utilization.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5cd95e5758a216c2d98b87ffa00c193f" data-og-width="2234" width="2234" data-og-height="518" height="518" data-path="images/gas-price.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=34e7c202742fe4016ad74d42f19db11a 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8fad40d98664857be14d6d688479e26a 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=25d117b92ac9331638245bfa51a892ef 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=a37864a27babcbd782dde2b191dc6a04 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=dd2ff9b6f97dc9ffd4b2b959642cc86f 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0a4bae90df88abbd194d39e81df82904 2500w" />

### Cumulative Metrics

* **Address Growth** <br />
  Access the cumulative number of active addresses on a chain, providing insights into network adoption and user activity.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9711fbab3952cb4fc83b3669644bd61f" data-og-width="1270" width="1270" data-og-height="526" height="526" data-path="images/address-growth.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8b4122f7d6c39acb7fa760b7d9ed4d53 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=db773dd8f4feb931ad39f9d8eb912881 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e0658680af8315123920de3da152741f 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bf1a7ea0bbb618a39f62ff0c2e4af582 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c66f8199193efb6fc7f70434e49472ce 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1b5fa8eac8517e9d28067a0822d51d99 2500w" />
* **Contract Deployment** <br />
  Monitor the cumulative number of smart contracts deployed, helping to gauge developer engagement and platform usage.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0c935a91f11317572c4bbf7d77605267" data-og-width="1274" width="1274" data-og-height="514" height="514" data-path="images/contracts-deployed.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9fa8e3c3557ba148be0b3eed9429fb7e 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=130d0162d4352a5de81f0a1a00eb62dc 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5c9d1647deb4844f9f00c010c328beb9 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=49cd8a081dc663f251ba27ef33d4b3e8 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=683fe8e66667b1a900b36fb3a34d51ca 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9b2bc5bebcbe0e7d731ead264a4d150e 2500w" />
* **Transaction Count** <br />
  Track the cumulative number of transactions, offering a clear view of network activity and transaction volume.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d271db14bc0f4587deec117295328480" data-og-width="1274" width="1274" data-og-height="530" height="530" data-path="images/transactions.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4804932f216177724f67934e272513f5 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=579942ac2a6525e32c407d1849f3fdcd 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6f833b20237305ebb0e06ed3a2e2085f 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f7c3197b2661ca78d2b99826e123d4af 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8466c708703a5a78fa23fd925e9eb6c5 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=cd62a755b5e0e8a5836ad9bfcfaa00ca 2500w" />

### Staking Information

* **Validator and Delegator Counts** <br />
  Retrieve the number of active validators and delegators for a given L1, crucial for understanding network security and decentralization.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0e7b9f73d99ea625c8b0657937a20002" data-og-width="2310" width="2310" data-og-height="516" height="516" data-path="images/validator-count.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=99cbf647d41304d1cdc6d89a773fab85 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4a65f19673493f99fd70f8880415d1cf 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=54532d69bf22968b129b8d59fa0d83d3 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c394379424beb4c6e6b057bdead1a8b8 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=00fb6eef9ce7eef53bfb640f42c6644c 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1265b3d9392ade6401d627f252b59faa 2500w" />
* **Staking Weights** <br />
  Access the total stake weight of validators and delegators, helping to assess the distribution of staked assets across the network.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0a3588249d0de25c08b2dedfacc04703" data-og-width="2304" width="2304" data-og-height="520" height="520" data-path="images/staking-weight.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e56a254b64ae7b5aeea79adf4aff8bfc 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8e654871f59c6cce994f3c87956b3a32 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d07693fc9719b402d664d9aa8b645e55 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=be32e1515db1b7c8dea17b57da2ba6a8 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=76650855af82fb3d77ec6aaf66fac2d0 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=2e0c844674f5ae99103553a748342481 2500w" />

### Rolling Window Analytics

* **Short-Term and Long-Term Metrics:** Perform rolling window analysis on various metrics like gas used, TPS, and gas prices, allowing for both short-term and long-term trend analysis.
* **Customizable Time Frames:** Choose from different time intervals (hourly, daily, monthly) to suit your specific analytical needs.

### Blockchain and L1 Information

* **Chain and L1 Mapping:** Get detailed information about EVM chains and their associated L1s, including chain IDs, blockchain IDs, and subnet IDs, facilitating cross-chain analytics.

### Advanced Composite Queries

* **Custom Metrics Combinations**: Combine multiple metrics and apply logical operators to perform sophisticated queries, enabling deep insights and tailored analytics.
* **Paginated Results:** Handle large datasets efficiently with paginated responses, ensuring seamless data retrieval in your applications.

The Metrics API equips developers with the tools needed to build robust analytics, monitoring, and reporting solutions, leveraging the full power of multi-chain data across the Lux ecosystem and beyond.

# Rate Limits (/docs/api-reference/metrics-api/rate-limits)

---
title: Rate Limits
description: Rate Limits for the Metrics API
icon: Clock
---
# Rate Limits

Rate limiting is managed through a weighted scoring system, known as Compute Units (CUs). Each API request consumes a specified number of CUs, determined by the complexity of the request. This system is designed to accommodate basic requests while efficiently handling more computationally intensive operations.

## Rate Limit Tiers

The maximum CUs (rate-limiting score) for a user depends on their subscription level and is delineated in the following table:

| Subscription Level | Per Minute Limit (CUs) | Per Day Limit (CUs) |
| :----------------- | :--------------------- | :------------------ |
| Free               | 8,000                  | 1,200,000           |

> We are working on new subscription tiers with higher rate limits to support even greater request volumes.

## Rate Limit Categories

The CUs for each category are defined in the following table:

| Weight | CU Value |
| :----- | :------- |
| Free   | 1        |
| Small  | 20       |
| Medium | 100      |
| Large  | 500      |
| XL     | 1000     |
| XXL    | 3000     |

## Rate Limits for Metrics Endpoints

The CUs for each route are defined in the table below:

| Endpoint                                                    | Method | Weight | CU Value |
| :---------------------------------------------------------- | :----- | :----- | :------- |
| `/v2/health-check`                                          | GET    | Free   | 1        |
| `/v2/chains`                                                | GET    | Free   | 1        |
| `/v2/chains/{chainId}`                                      | GET    | Free   | 1        |
| `/v2/chains/{chainId}/metrics/{metric}`                     | GET    | Medium | 100      |
| `/v2/chains/{chainId}/teleporterMetrics/{metric}`           | GET    | Medium | 100      |
| `/v2/chains/{chainId}/rollingWindowMetrics/{metric}`        | GET    | Medium | 100      |
| `/v2/networks/{network}/metrics/{metric}`                   | GET    | Medium | 100      |
| `/v2/chains/{chainId}/contracts/{address}/nfts:listHolders` | GET    | Large  | 500      |
| `/v2/chains/{chainId}/contracts/{address}/balances`         | GET    | XL     | 1000     |
| `/v2/chains/43114/btcb/bridged:getAddresses`                | GET    | Large  | 500      |
| `/v2/subnets/{subnetId}/validators:getAddresses`            | GET    | Large  | 500      |
| `/v2/lookingGlass/compositeQuery`                           | POST   | XXL    | 3000     |

<Info> All rate limits, weights, and CU values are subject to change. </Info>

# Usage Guide (/docs/api-reference/metrics-api/usage-guide)

---
title: Usage Guide
description: Usage Guide for the Metrics API
icon: Code
---

The Metrics API does not require authentication, making it straightforward to integrate into your applications. You can start making API requests without the need for an API key or any authentication headers.

#### Making Requests

You can interact with the Metrics API by sending HTTP GET requests to the provided endpoints. Below is an example of a simple `curl` request.

```bash
curl -H "Content-Type: Application/json" "https://metrics.lux.network/v1/avg_tps/{chainId}"
```

In the above request Replace `chainId` with the specific chain ID you want to query. For example, to retrieve the average transactions per second (TPS) for a specific chain (in this case, chain ID 43114), you can use the following endpoint:

```bash
curl "https://metrics.lux.network/v1/avg_tps/43114"
```

The API will return a JSON response containing the average TPS for the specified chain over a series of timestamps and `lastRun` is a timestamp indicating when the last data point was updated:

```json
{
  "results": [
    {"timestamp": 1724716800, "value": 1.98},
    {"timestamp": 1724630400, "value": 2.17},
    {"timestamp": 1724544000, "value": 1.57},
    {"timestamp": 1724457600, "value": 1.82},
    // Additional data points...
  ],
  "status": 200,
  "lastRun": 1724780812
}
```

### Rate Limits

Even though the Metrics API does not require authentication, it still enforces rate limits to ensure stability and performance. If you exceed these limits, the server will respond with a 429 Too Many Requests HTTP response code.

### Error Types

The API generates standard error responses along with error codes based on provided requests and parameters.

Typically, response codes within the `2XX` range signifies successful requests, while those within the `4XX` range points to errors originating from the client's side. Meanwhile, response codes within the `5XX` range indicates problems on the server's side.

The error response body is formatted like this:

```json
{
  "message": ["Invalid address format"], // route specific error message
  "error": "Bad Request", // error type
  "statusCode": 400 // http response code
}
```

Let's go through every error code that we can respond with:

| Error Code | Error Type            | Description                                                                                                                                                                                                                   |
| ---------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400**    | Bad Request           | Bad requests generally mean the client has passed invalid or malformed parameters. Error messages in the response could help in evaluating the error.                                                                         |
| **401**    | Unauthorized          | When a client attempts to access resources that require authorization credentials but the client lacks proper authentication in the request, the server responds with 401.                                                    |
| **403**    | Forbidden             | When a client attempts to access resources with valid credentials but doesn't have the privilege to perform that action, the server responds with 403.                                                                        |
| **404**    | Not Found             | The 404 error is mostly returned when the client requests with either mistyped URL, or the passed resource is moved or deleted, or the resource doesn't exist.                                                                |
| **500**    | Internal Server Error | The 500 error is a generic server-side error that is returned for any uncaught and unexpected issues on the server side. This should be very rare, and you may reach out to us if the problem persists for a longer duration. |
| **502**    | Bad Gateway           | This is an internal error indicating invalid response received by the client-facing proxy or gateway from the upstream server.                                                                                                |
| **503**    | Service Unavailable   | The 503 error is returned for certain routes on a particular Subnet. This indicates an internal problem with our Subnet node, and may not necessarily mean the Subnet is down or affected.                                    |

### Pagination

For endpoints that return large datasets, the Metrics API employs pagination to manage the results. When querying for lists of data, you may receive a nextPageToken in the response, which can be used to request the next page of data.

Example response with pagination:

```json
{
  "results": [...],
  "nextPageToken": "3d22deea-ea64-4d30-8a1e-c2a353b67e90"
}
```

To retrieve the next set of results, include the nextPageToken in your subsequent request:

```bash
curl -H "Content-Type: Application/json" \
  "https://metrics.lux.network/v1/avg_tps/{chainId}?pageToken=3d22deea-ea64-4d30-8a1e-c2a353b67e90"
```

### Pagination Details

#### Page Token Structure

The `nextPageToken` is a UUID-based token provided in the response when additional pages of data are available. This token serves as a pointer to the next set of data.

* **UUID Generation**: The `nextPageToken` is generated uniquely for each pagination scenario, ensuring security and ensuring predictability.
* **Expiration**: The token is valid for 24 hours from the time it is generated. After this period, the token will expire, and a new request starting from the initial page will be required.
* **Presence**: The token is only included in the response when there is additional data available. If no more data exists, the token will not be present.

#### Integration and Usage

To use the pagination system effectively:

* Check if the `nextPageToken` is present in the response.
* If present, include this token in the subsequent request to fetch the next page of results.
* Ensure that the follow-up request is made within the 24-hour window after the token was generated to avoid token expiration.

By utilizing the pagination mechanism, you can efficiently manage and navigate through large datasets, ensuring a smooth data retrieval process.

### Swagger API Reference

You can explore the full API definitions and interact with the endpoints in the Swagger documentation at:

<Cards cols={1}>
  <Card title="Swagger API Reference">
    [https://metrics.lux.network/api](https://metrics.lux.network/api)
  </Card>
</Cards>

# ICM Contract Addresses (/docs/cross-chain/icm-contracts/addresses)

---
title: ICM Contract Addresses
---

## Deployed Addresses
| Contract              | Address                                        | Chain                    |
| --------------------- | ---------------------------------------------- | ------------------------ |
| `TeleporterMessenger` | **0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf** | All chains, all networks |
| `TeleporterRegistry`  | **0x7C43605E14F391720e1b37E49C78C4b03A488d98** | Mainnet LUExchange-Chain          |
| `TeleporterRegistry`  | **0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228** | Testnet LUExchange-Chain             |



1. Using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#), `TeleporterMessenger` deploys at a universal address across all chains, varying with each ICM contracts Major release. **Compatibility exists only between same versions of `TeleporterMessenger` instances.** See [ICM Contract Deployment](https://github.com/luxfi/teleporter/blob/main/utils/contract-deployment/README.md) and [Deploy ICM Contracts to a Subnet](https://github.com/luxfi/teleporter/tree/main?tab=readme-ov-file#deploy-teleporter-to-a-subnet) for more details.

2. `TeleporterRegistry` can be deployed to any address. See [Deploy TeleporterRegistry to a Subnet](https://github.com/luxfi/teleporter/blob/main/README.md#deploy-teleporter-to-a-subnet) for details. The table above enumerates the canonical registry addresses on the Mainnet and Testnet LUExchange-Chains.

## A Note on Versioning

Release versions follow the [semver](https://semver.org/) convention of incompatible Major releases. A new Major version is released whenever the `TeleporterMessenger` bytecode is changed, and a new version of `TeleporterMessenger` is meant to be deployed.

Due to the use of Nick's method to deploy the contract to the same address on all chains (see [ICM Contract Deployment](https://github.com/luxfi/teleporter/blob/main/utils/contract-deployment/README.md) for details), this also means that new release versions would result in different ICM contract addresses. Minor and Patch versions may pertain to contract changes that do not change the `TeleporterMessenger` bytecode, or to changes in the test frameworks, and will only be included in tags.


# Teleporter CLI (/docs/cross-chain/icm-contracts/cli)

---
title: "Teleporter CLI"
description: "The CLI is a command line interface for interacting with the Teleporter contracts."
edit_url: https://github.com/luxfi/teleporter/edit/main/cmd/teleporter-cli/README.md
---

# ICM Contracts CLI

This directory contains the source code for the ICM Contracts CLI. The CLI is a command line interface for interacting with the ICM contracts. It is written with [cobra](https://github.com/spf13/cobra) commands as a Go application.

## Build

To build the CLI, run `go build` from this directory. This will create a binary called `teleporter-cli` in the current directory.

## Usage

The CLI has a number of subcommands. To see the list of subcommands, run `./teleporter-cli help`. To see the help for a specific subcommand, run `./teleporter-cli help <subcommand>`.

The supported subcommands include:

- `event`: given a log event's topics and data, attempts to decode into an ICM event in a more readable format.
- `message`: given an ICM message encoded as a hex string, attempts to decode into an ICM message in a more readable format.
- `transaction`: given a transaction hash, attempts to decode all relevant TeleporterMessenger and ICM log events in a more readable format.

# Deep Dive into ICM Contracts (/docs/cross-chain/icm-contracts/deep-dive)

---
title: "Deep Dive into ICM Contracts"
description: "ICM Contracts is an EVM compatible cross-Lux L1 communication protocol built on top of Lux Interchain Messaging (ICM), and implemented as a Solidity smart contract."
edit_url: https://github.com/luxfi/icm-contracts/edit/main/README.md
---

# ICM Contracts

For help getting started with building ICM contracts, refer to [the lux-starter-kit repository](https://github.com/luxfi/lux-starter-kit).

- [Setup](#setup)
  - [Initialize the repository](#initialize-the-repository)
  - [Dependencies](#dependencies)
- [Structure](#structure)
- [E2E tests](#e2e-tests)
  - [Run specific E2E tests](#run-specific-e2e-tests)
- [ABI Bindings](#abi-bindings)
- [Docs](#docs)
- [Resources](#resources)

## Setup

### Initialize the repository

- Get all submodules: `git submodule update --init --recursive`

### Dependencies

- [Ginkgo](https://onsi.github.io/ginkgo/#installing-ginkgo) for running the end-to-end tests.
- [Foundry](https://book.getfoundry.sh/) Use `./scripts/install_foundry.sh` to install Foundry for building contracts.

## Structure

- `contracts/`
  - [`governance/`](https://github.com/luxfi/teleporter/blob/main/contracts/governance/README.md) includes contracts related to L1 governance.
  - [`ictt/`](https://github.com/luxfi/teleporter/blob/main/contracts/ictt/README.md) Interchain Token Transfer contracts. Facilitates the transfer of tokens among L1s.
  - [`teleporter/`](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/README.md) includes `TeleporterMessenger`, which serves as the interface for most contracts to use ICM.
    - [`registry/`](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/registry/README.md) includes a registry contract for managing different versions of `TeleporterMessenger`.
  - [`validator-manager/`](https://github.com/luxfi/teleporter/blob/main/contracts/validator-manager/README.md) includes contracts for managing the validator set of an L1.
- `abi-bindings/` includes Go ABI bindings for the contracts in `contracts/`.
- [`audits/`](https://github.com/luxfi/teleporter/blob/main/audits/README.md) includes all audits conducted on contracts in this repository.
- `tests/` includes integration tests for the contracts in `contracts/`, written using the [Ginkgo](https://onsi.github.io/ginkgo/) testing framework.
- `utils/` includes Go utility functions for interacting with the contracts in `contracts/`. Included are Golang scripts to derive the expected EVM contract address deployed from a given EOA at a specific nonce, and also construct a transaction to deploy provided byte code to the same address on any EVM chain using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#).
- `scripts/` includes bash scripts for interacting with TeleporterMessenger in various environments, as well as utility scripts.
  - `abi_bindings.sh` generates ABI bindings for the contracts in `contracts/` and outputs them to `abi-bindings/`.
  - `lint.sh` performs Solidity and Golang linting.

## E2E tests

In addition to the docker setup, end-to-end integration tests written using Ginkgo are provided in the `tests/` directory. E2E tests are run as part of CI, but can also be run locally. Any new features or cross-chain example applications checked into the repository should be accompanied by an end-to-end tests. See the [Contribution Guide](https://github.com/luxfi/teleporter/blob/main/CONTRIBUTING.md) for additional details.

To run the E2E tests locally, you'll need to install Gingko following the instructions [here](https://onsi.github.io/ginkgo/#installing-ginkgo).

Then run the following command from the root of the repository:

```bash
./scripts/e2e_test.sh
```

### Run specific E2E tests

To run a specific E2E test, specify the environment variable `GINKGO_FOCUS`, which will then look for test descriptions that match the provided input. For example, to run the `Calculate Teleporter message IDs` test:

```bash
GINKGO_FOCUS="Calculate Teleporter message IDs" ./scripts/e2e_test.sh
```

A substring of the full test description can be used as well:

```bash
GINKGO_FOCUS="Calculate Teleporter" ./scripts/e2e_test.sh
```

The E2E test script also supports a `--components` flag, making it easy to run all the test cases for a particular project. For example, to run all E2E tests for the `tests/flows/ictt/` folder:

```bash
./scripts/e2e_test.sh --components "ictt"
```

## ABI Bindings

The E2E tests written in Golang interface with the solidity contracts by use of generated ABI bindings. To regenerate Golang ABI bindings for the Solidity smart contracts, run:

```bash
./scripts/abi_bindings.sh
```

The auto-generated bindings should be written under the `abi-bindings/` directory.

## Docs

- [ICM Protocol Overview](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/README.md)
- [Teleporter Registry and Upgrades](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/registry/README.md)
- [Contract Deployment](https://github.com/luxfi/teleporter/blob/main/utils/contract-deployment/README.md)
- [Teleporter CLI](https://github.com/luxfi/teleporter/blob/main/cmd/teleporter-cli/README.md)

## Resources

- List of blockchain signing cryptography algorithms [here](http://ethanfast.com/top-crypto.html).
- Background on stateful precompiles [here](https://medium.com/luxlux/customizing-the-evm-with-stateful-precompiles-f44a34f39efd).
- Background on BLS signature aggregation [here](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html).

# Getting Started (/docs/cross-chain/icm-contracts/getting-started)

---
title: Getting Started
---

<Callout title="Note">
Dive deeper into ICM contracts and kickstart your journey in building cross-chain dApps by enrolling in our [ICM contracts course](/academy/interchain-messaging).
</Callout>

<Callout title="Note">
 Note: All example applications in the [examples](https://github.com/luxfi/teleporter/tree/example-sequential-message-app/contracts/sequential-delivery-example) directory are meant for education purposes only and are not audited. The example contracts are not intended for use in production environments.
</Callout>

This section walks through how to build an example cross-chain application on top of ICM contracts, recreating the `ExampleCrossChainMessenger` [contract](https://github.com/luxfi/teleporter/tree/example-sequential-message-app/contracts/sequential-delivery-example) that sends arbitrary string data from one chain to another. Note that this tutorial is meant for education purposes only. The resulting code is not intended for use in production environments.

Step 1: Create Initial Contract[​](#step-1-create-initial-contract "Direct link to heading")
--------------------------------------------------------------------------------------------

Create a new file called `MyExampleCrossChainMessenger.sol` in a new directory:

```
mkdir teleporter/contracts/src/CrossChainApplications/MyExampleCrossChainMessenger/
touch teleporter/contracts/src/CrossChainApplications/MyExampleCrossChainMessenger/MyExampleCrossChainMessenger.sol
```

At the top of the file define the Solidity version to work with, and import the necessary types and interfaces.

```
pragma solidity 0.8.18;

import {ITeleporterMessenger, TeleporterMessageInput, TeleporterFeeInfo} from "@teleporter/ITeleporterMessenger.sol";
import {ReentrancyGuard} from "@openzeppelin/[email protected]/security/ReentrancyGuard.sol";
```

Next, define the initial empty contract. The contract inherits from `ReentrancyGuard` to prevent reentrancy attacks.

```
contract MyExampleCrossChainMessenger is
    ReentrancyGuard
{

}
```

Finally, add the following struct and event declarations into the body of the contract, which will be integrated in later:

```
    /**
     * @dev Messages sent to this contract.
     */
    struct Message {
        address sender;
        string message;
    }

    /**
     * @dev Emitted when a message is submited to be sent.
     */
    event SendMessage(
        bytes32 indexed destinationBlockchainID,
        address indexed destinationAddress,
        address feeTokenAddress,
        uint256 feeAmount,
        uint256 requiredGasLimit,
        string message
    );

    /**
     * @dev Emitted when a new message is received from a given chain ID.
     */
    event ReceiveMessage(
        bytes32 indexed sourceBlockchainID,
        address indexed originSenderAddress,
        string message
    );
```

Step 2: Integrating ICM Contracts[​](#step-2-integrating-teleporter-messenger "Direct link to heading")
--------------------------------------------------------------------------------------------------------------

Now that the initial empty `MyExampleCrossChainMessenger` is defined, it's time to integrate with `ITeleporterMessenger`, which will provide the functionality to deliver cross chain messages.

Create a state variable of `ITeleporterMessenger` type called `teleporterMessenger`. Then create a constructor that takes in an address where the ICM Messenger contract would be deployed on this chain, and set the corresponding state variable.

```
    ITeleporterMessenger public immutable teleporterMessenger;

    constructor(address teleporterMessengerAddress) {
        teleporterMessenger = ITeleporterMessenger(teleporterMessengerAddress);
    }
```

Step 3: Send and Receive[​](#step-3-send-and-receive "Direct link to heading")
------------------------------------------------------------------------------

Now that `MyExampleCrossChainMessenger` has an instantiation of `ITeleporterMessenger`, the next step is to add in the functionality of sending and receiving arbitrary string data between chains.

To start, create the function declaration for `sendMessage`, which will send string data cross-chain to the specified destination address' receiver. This function allows callers to specify the destination chain ID, destination address to send to, relayer fees, required gas limit for message execution at the destination address.

```
    /**
     * @dev Send a new message to another chain.
     */
    function sendMessage(
        bytes32 destinationBlockchainID,
        address destinationAddress,
        address feeTokenAddress,
        uint256 feeAmount,
        uint256 requiredGasLimit,
        string calldata message
    ) external returns (bytes32 messageID) {

    }
```

`MyExampleCrossChainMessenger` also needs to implement `ITeleporterReceiver`. First, add the import of this interface:

```
import {ITeleporterReceiver} from "@teleporter/ITeleporterReceiver.sol";
```

Then declare that the contract will implement it:

```
  contract MyExampleCrossChainMessenger is
-     ReentrancyGuard
+     ReentrancyGuard,
+     ITeleporterReceiver
  {
```

And then finally add the method `receiveTeleporterMessage` that receives the cross-chain messages from ICM.

```
    /**
     * @dev Receive a new message from another chain.
     */
    function receiveTeleporterMessage(
        bytes32 sourceBlockchainID,
        address originSenderAddress,
        bytes calldata message
    ) external {

    }
```

Now it's time to implement the methods, starting with `sendMessage`. First, add the necessary imports.

```
import {SafeERC20TransferFrom, SafeERC20} from "@teleporter/SafeERC20TransferFrom.sol";
import {IERC20} from "@openzeppelin/[email protected]/token/ERC20/IERC20.sol";
```

Next, add a `using` directive to the top of the contract body specifying `SafeERC20` as the `IERC20` implementation to use:

```
    using SafeERC20 for IERC20;
```

Then add a check to the `sendMessage` function for whether `feeAmount` is greater than zero. If it is, transfer and approve the amount of IERC20 asset at `feeTokenAddress` to the Teleporter Messenger saved as a state variable.

```
        // For non-zero fee amounts, first transfer the fee to this contract, and then
        // allow the Teleporter contract to spend it.
        uint256 adjustedFeeAmount;
        if (feeAmount > 0) {
            adjustedFeeAmount = SafeERC20TransferFrom.safeTransferFrom(
                IERC20(feeTokenAddress),
                feeAmount
            );
            IERC20(feeTokenAddress).safeIncreaseAllowance(
                address(teleporterMessenger),
                adjustedFeeAmount
            );
        }
```

> Note: Relayer fees are an optional way to incentivize relayers to deliver an ICM message to its destination. They are not strictly necessary, and may be omitted if a relayer is willing to relay messages with no fee, such as with a self-hosted relayer.

Next, to the end of the `sendMessage` function, add the event to emit, as well as the call to the `TeleporterMessenger` contract with the message data to be executed when delivered to the destination address. Form a `TeleporterMessageInput` and call `sendCrossChainMessage` on the `TeleporterMessenger` instance to start the cross chain messaging process. The `message` must be ABI encoded so that it can be properly decoded on the receiving end.

> Note: `allowedRelayerAddresses` is empty in this example, meaning any relayer can try to deliver this cross chain message. Specific relayer addresses can be specified to ensure only those relayers can deliver the message.

```
        emit SendMessage({
            destinationBlockchainID: destinationBlockchainID,
            destinationAddress: destinationAddress,
            feeTokenAddress: feeTokenAddress,
            feeAmount: adjustedFeeAmount,
            requiredGasLimit: requiredGasLimit,
            message: message
        });
        return
            teleporterMessenger.sendCrossChainMessage(
                TeleporterMessageInput({
                    destinationBlockchainID: destinationBlockchainID,
                    destinationAddress: destinationAddress,
                    feeInfo: TeleporterFeeInfo({
                        feeTokenAddress: feeTokenAddress,
                        amount: adjustedFeeAmount
                    }),
                    requiredGasLimit: requiredGasLimit,
                    allowedRelayerAddresses: new address[](0),
                    message: abi.encode(message)
                })
            );
```

With the sending side complete, the next step is to implement `ITeleporterReceiver.receiveTeleporterMessage`. The receiver in this example will just receive the arbitrary string data, and check that the message is sent through ICM. To the `receiveTeleporterMessage` function, add:

```
        // Only the Teleporter receiver can deliver a message.
        require(msg.sender == address(teleporterMessenger), "Unauthorized.");

        // do something with message.
```

The base of sending and receiving messages cross chain is complete. `MyExampleCrossChainMessenger` can now be expanded with functionality that saves the received messages, and allows users to query for the latest message received from a specified chain.

Step 4: Storing the Message[​](#step-4-storing-the-message "Direct link to heading")
------------------------------------------------------------------------------------

Start by adding a map to the body of the contract, in which the key is the `sourceBlockchainID` and the value is the latest `message` sent from that chain. The `message` is of type `Message`, which is already declared in the contract.

```
    mapping(bytes32 sourceBlockchainID => Message message) private _messages;
```

Next, update `receiveTeleporterMessage` to save the message into the mapping after it is received and verified that it's sent from Teleporter. At the end of that function, ABI decode the `message` bytes into a string, and emit the `ReceiveMessage` event.

```
        // Store the message.
        string memory messageString = abi.decode(message, (string));
        _messages[sourceBlockchainID] = Message(
            originSenderAddress,
            messageString
        );
        emit ReceiveMessage(
            sourceBlockchainID,
            originSenderAddress,
            messageString
        );
```

Next, add a function to the contract called `getCurrentMessage` that allows users or contracts to easily query the contract for the latest message sent by a specified chain.

```
    /**
     * @dev Check the current message from another chain.
     */
    function getCurrentMessage(
        bytes32 sourceBlockchainID
    ) external view returns (address, string memory) {
        Message memory messageInfo = _messages[sourceBlockchainID];
        return (messageInfo.sender, messageInfo.message);
    }
```

Step 5: Upgrade Support[​](#step-5-upgrade-support "Direct link to heading")
----------------------------------------------------------------------------

At this point, the contract is now fully usable, and can be used to send arbitrary string data between chains. However, there are a few more modifications that need to be made to support upgrades to ICM contracts. For a more in-depth explanation of how to support upgrades, see the Upgrades README [here](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/registry/UPGRADING.md).

The first change to make is to inherit from `TeleporterOwnerUpgradeable` instead of `ITeleporterReceiver`. `TeleporterOwnerUpgradeable` integrates with the `TeleporterRegistry` via `TeleporterUpgradeable` to easily utilize the latest `TeleporterMessenger` implementation. `TeleporterOwnerUpgradeable` also ensures that only an admin address for managing Teleporter versions, specified by the constructor argument `teleporterManager`, is able to upgrade the `TeleporterMessenger` implementation used by the contract.

To start, replace the import for `ITeleporterReceiver` with `TeleporterOwnerUpgradeable`:

```
- import {ITeleporterReceiver} from "@teleporter/ITeleporterReceiver.sol";
+ import {TeleporterOwnerUpgradeable} from "@teleporter/upgrades/TeleporterOwnerUpgradeable.sol";
```

Also, replace the contract declaration to inherit from `TeleporterOwnerUpgradeable` instead of `ITeleporterReceiver`:

```
contract MyExampleCrossChainMessenger is
     ReentrancyGuard,
-    ITeleporterReceiver
+    TeleporterOwnerUpgradeable
{
```

Next, update the constructor to invoke the `TeleporterOwnerUpgradeable` constructor.

```
-     constructor(address teleporterMessengerAddress) {
-         teleporterMessenger = ITeleporterMessenger(teleporterMessengerAddress);
-     }
+     constructor(
+         address teleporterRegistryAddress,
+         address teleporterManager
+     ) TeleporterOwnerUpgradeable(teleporterRegistryAddress, teleporterManager) {}
```

Then, remove the `teleporterMessenger` state variable:

```
-     ITeleporterMessenger public immutable teleporterMessenger;
```

And at the beginning of `sendMessage()` add a call to get the latest `ITeleporterMessenger` implementation from `TeleporterRegistry`:

```
        ITeleporterMessenger teleporterMessenger = teleporterRegistry.getLatestTeleporter();
```

And finally, change `receiveTeleporterMessage` to `_receiveTeleporterMessage`, mark it as `internal override`, and change the data location of its `message` parameter to `memory`. It's also safe to remove the check against `teleporterMessenger` in `_receiveTeleporterMessage`, since that same check is handled in `TeleporterOwnerUpgradeable`'s `receiveTeleporterMessage` function.

```
-     function receiveTeleporterMessage(
+     function _receiveTeleporterMessage(
          bytes32 sourceBlockchainID,
          address originSenderAddress,
-         bytes calldata message
+         bytes memory message
-     ) external {
+     ) internal override {
-          // Only the Teleporter receiver can deliver a message.
-          require(msg.sender == address(teleporterMessenger), "Unauthorized.");
```

`MyExampleCrossChainMessenger` is now a working cross-chain dApp built on top of ICM contracts! Full example [here](https://github.com/luxfi/teleporter/tree/example-sequential-message-app/contracts/sequential-delivery-example).

Step 6: Testing[​](#step-6-testing "Direct link to heading")
------------------------------------------------------------

For testing, `scripts/local/e2e_test.sh` sets up a local test environment consisting of three lux-l1s deployed with ICM contracts, and a lightweight inline relayer implementation to facilitate cross chain message delivery. An end-to-end test for `ExampleCrossChainMessenger` is included in `tests/flows/example_messenger.go`, which performs the following:

1.  Deploys the [ExampleERC20](https://github.com/luxfi/teleporter/blob/main/contracts/mocks/ExampleERC20.sol) token to lux-l1 A.
2.  Deploys `ExampleCrossChainMessenger` to both lux-l1s A and B.
3.  Approves the cross-chain messenger on lux-l1 A to spend ERC20 tokens from the default address.
4.  Sends `"Hello, world!"` from lux-l1 A to lux-l1 B's cross-chain messenger to receive.
5.  Calls `getCurrentMessage` on lux-l1 B to make sure the right message and sender are received.

To run this test against the newly created `MyExampleCrossChainMessenger`, first generate the ABI Go bindings by running `./scripts/abi_bindings.sh --contract MyExampleCrossChainMessenger` from the root of this repository. Then, add to the generated Go package the `SendMessageRequiredGas` constant, which is required by the tests, in a new file `abi-bindings/go/CrossChainApplications/MyExampleCrossChainMessenger/MyExampleCrossChainMessenger/constants.go`:

```js
package myexamplecrosschainmessenger

import "math/big"

var SendMessageRequiredGas = big.NewInt(300000)
```

Next, modify `tests/utils/utils.go`, which is used by `tests/flows/example_messenger.go`, to use the ABI bindings for `MyExampleCrossChainMessenger` instead of `ExampleCrossChainMessenger`. First replace the import:

```
-       examplecrosschainmessenger "github.com/luxfi/teleporter/abi-bindings/go/CrossChainApplications/examples/ExampleMessenger/ExampleCrossChainMessenger"
+       myexamplecrosschainmessenger "github.com/luxfi/teleporter/abi-bindings/go/CrossChainApplications/MyExampleCrossChainMessenger/MyExampleCrossChainMessenger"
```

Then, in that same `utils.go`, replace all instances of to `examplecrosschainmessenger` with `myexamplecrosschainmessenger` and all instances of `ExampleCrossChainMessenger` with `MyExampleCrossChainMessenger`.

Finally, from the root of the repository, invoke the tests with an extra bit of configuration that tells the Ginkgo test framework to focus only on the tests of this example contract (excluding all of the broader tests of Teleporter):

```
GINKGO_FOCUS="Example cross chain messenger" scripts/local/e2e_test.sh

```



# ICM Contracts Lux L1s on Devnet (/docs/cross-chain/icm-contracts/icm-contracts-on-devnet)

---
title: ICM Contracts Lux L1s on Devnet
description: This how-to guide focuses on deploying ICM contract-enabled Lux L1s to a Devnet.
---

After this tutorial, you would have created a Devnet and deployed two Lux L1s in it, and have enabled them to cross-communicate with each other and with the LUExchange-Chain through ICM contracts and the underlying Warp technology.

For more information on cross chain messaging through ICM contracts and Warp, check:

- [Cross Chain References](/docs/cross-chain)

Note that currently only [Subnet-EVM](https://github.com/luxfi/subnet-evm) and [Subnet-EVM-Based](/docs/lux-l1s/evm-configuration/evm-l1-customization) virtual machines support ICM contracts.

## Prerequisites

Before we begin, you will need to have:

- Created an AWS account and have an updated AWS `credentials` file in home directory with \[default\] profile

Note: the tutorial uses AWS hosts, but Devnets can also be created and operated in other supported cloud providers, such as GCP.

Create Lux L1s Configurations[​](#create-lux-l1s-configurations "Direct link to heading")
-----------------------------------------------------------------------------------------

For this section we will follow this [steps](/docs/tooling/lux-cli/cross-chain/teleporter-local-network#create-lux-l1s-configurations), to create two ICM contract-enabled Lux L1s, `<chain1>` and `<chain2>`.

Create a Devnet and Deploy an Lux L1 in It[​](#create-a-devnet-and-deploy-a-lux-l1-in-it "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------

Let's use the `devnet wiz` command to create a devnet `<devnetName>` and deploy `<chain1>` in it.

The devnet will be created in the `us-east-1` region of AWS, and will consist of 5 validators only.

```
lux node devnet wiz <devnetName> <chain1> --aws --node-type default --region us-east-1 --num-validators 5 --num-apis 0 --enable-monitoring=false --default-validator-params 

Creating the devnet...

Creating new EC2 instance(s) on AWS...
...

Deploying [Lux L1] to Cluster <devnetName>
...

configuring AWM RElayer on host i-0f1815c016b555fcc

Setting the nodes as Lux L1 trackers
...

Setting up ICM contracts on Lux L1

Teleporter Messenger successfully deployed to Lux L1 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to Lux L1 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to c-chain (0x5DB9A7629912EBF95876228C24A848de0bfB43A9)

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay L1 chain1
updating configuration file ~/.lux-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is successfully created and is now validating blockchain chain1!

Lux L1 <chain1> RPC URL: http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc
 
✓ Cluster information YAML file can be found at ~/.lux-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Notice some details here:

- Two smart contracts are deployed to the Lux L1: Teleporter Messenger and Teleporter Registry
- Both ICM smart contracts are also deployed to `LUExchange-Chain`
- [AWM ICM Relayer](https://github.com/luxfi/icm-services/tree/main/relayer is installed and configured as a service into one of the nodes (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Lux L1 and sends them to the destination Lux L1.)

CLI configures the Relayer to enable every Lux L1 to send messages to all other Lux L1s. If you add more Lux L1s to the Devnet, the Relayer will be automatically reconfigured.

Checking Devnet Configuration and Relayer Logs[​](#checking-devnet-configuration-and-relayer-logs "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------

Execute `node list` command to get a list of the devnet nodes:

```
lux node list

Cluster "<devnetName>" (Devnet)
  Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]
  Node i-026392a651571232c (NodeID-AkPyyTs9e9nPGShdSoxdvWYZ6X2zYoyrK) 52.203.183.68 [Validator]
  Node i-0d1b98d5d941d6002 (NodeID-ByEe7kuwtrPStmdMgY1JiD39pBAuFY2mS) 50.16.235.194 [Validator]
  Node i-0c291f54bb38c2984 (NodeID-8SE2CdZJExwcS14PYEqr3VkxFyfDHKxKq) 52.45.0.56 [Validator]
  Node i-049916e2f35231c29 (NodeID-PjQY7xhCGaB8rYbkXYddrr1mesYi29oFo) 3.214.163.110 [Validator]
```

Notice that, in this case, `i-0f1815c016b555fcc` was set as Relayer. This host contains a `systemd` service called `awm-relayer` that can be used to check the Relayer logs, and set the execution status.

To view the Relayer logs, the following command can be used:

```
lux node ssh i-0f1815c016b555fcc "journalctl -u awm-relayer --no-pager"

  [Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]]
Warning: Permanently added '67.202.23.231' (ED25519) to the list of known hosts.
-- Logs begin at Fri 2024-04-05 14:11:43 UTC, end at Fri 2024-04-05 14:30:24 UTC. --
Apr 05 14:15:06 ip-172-31-47-187 systemd[1]: Started AWM Relayer systemd service.
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:66","msg":"Initializing awm-relayer"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:71","msg":"Set config options."}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:78","msg":"Initializing destination clients"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.021Z","logger":"awm-relayer","caller":"main/main.go:97","msg":"Initializing app request network"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.159Z","logger":"awm-relayer","caller":"main/main.go:309","msg":"starting metrics server...","port":9090}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"11111111111111111111111111111111LpoYY","subnetIDHex":"0000000000000000000000000000000000000000000000000000000000000000","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6","blockchainIDHex":"a2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML","subnetIDHex":"5a2e2d87d74b4ec62fdd6626e7d36a44716484dfcc721aa4f2168e8a61af63af","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p","blockchainIDHex":"582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.172Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xea06381426934ec1800992f41615b9d362c727ad542f6351dbfa7ad2849a35bf","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x175e14327136d57fe22d4bdd295ff14bea8a7d7ab1884c06a4d9119b9574b9b3","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xe584ccc0df44506255811f6b54375e46abd5db40a4c84fd9235a68f7b69c6f06","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x70f14d33bde4716928c5c4723d3969942f9dfd1f282b64ffdf96f5ac65403814","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
```

Deploying the Second Lux L1[​](#deploying-the-second-lux-l1 "Direct link to heading")
-------------------------------------------------------------------------------------

Let's use the `devnet wiz` command again to deploy `<chain2>`.

When deploying Lux L1 `<chain2>`, the two ICM contracts will not be deployed to LUExchange-Chain in Local Network as they have already been deployed when we deployed the first Lux L1.

```
lux node devnet wiz <devnetName> <chain2> --default-validator-params 

Adding Lux L1 into existing devnet <devnetName>...
...

Deploying [chain2] to Cluster <devnetName>
...

Stopping AWM Relayer Service

Setting the nodes as Lux L1 trackers
...

Setting up ICM contracts on Lux L1

Teleporter Messenger successfully deployed to Lux L1 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to Lux L1 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger has already been deployed to c-chain

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay L1 chain2
updating configuration file ~/.lux-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is now validating Lux L1 chain2

Lux L1 <chain2> RPC URL: http://67.202.23.231:9650/ext/bc/7gKt6evRnkA2uVHRfmk9WrH3dYZH9gEVVxDAknwtjvtaV3XuQ/rpc

✓ Cluster information YAML file can be found at ~/.lux-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Verify ICM Contracts Are Successfully Set Up[​](#verify-teleporter-is-successfully-set-up "Direct link to heading")
---------------------------------------------------------------------------------------------------------------

To verify that ICM contracts are successfully set up, let's send a couple of cross messages:

```
lux teleporter msg LUExchange-Chain chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source Lux L1 "LUExchange-Chain" (2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6)
Waiting for message to be received at destination Lux L1 "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

```
lux teleporter msg chain2 chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source Lux L1 "chain2" (29WP91AG7MqPUFEW2YwtKnsnzVrRsqcWUpoaoSV1Q9DboXGf4q)
Waiting for message to be received at destination Lux L1 "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

You have sent your first ICM message in the Devnet!

Obtaining Information on ICM Contract Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Lux L1 Information[​](#obtaining-lux-l1-information "Direct link to heading")

By executing `blockchain describe` on an ICM contract-enabled Lux L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```
lux blockchain describe <chain1>

 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/

+--------------------------------+----------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                    |
+--------------------------------+----------------------------------------------------------------------------------------+
| Blockchain Name                    | Lux L1                                                                            |
+--------------------------------+----------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                           |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> SubnetID  | giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> RPC URL   | http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName>           | fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p                                      |
| BlockchainID                   |                                                                                        |
+                                +----------------------------------------------------------------------------------------+
|                                | 0x582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a                     |
|                                |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                             |
| Messenger Address              |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0xb623C4495220C603D0A939D32478F55891a61750                                             |
| Registry Address               |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+

...
```

### Obtaining LUExchange-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for LUExchange-Chain by using `primary describe`:

```
lux primary describe --cluster <devnetName>

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://67.202.23.231:9650/ext/bc/C/rpc                             |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | LUX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.815751426                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6                 |
+                              +--------------------------------------------------------------------+
|                              | 0xa2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170 |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x5DB9A7629912EBF95876228C24A848de0bfB43A9                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

CLI provides two commands to remotely control Relayer execution:

```
lux interchain relayer stop --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully stopped
```

```
lux interchain relayer start --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully started

```



# ICM Contracts Lux L1s on Local Network (/docs/cross-chain/icm-contracts/icm-contracts-on-local-network)

---
title: ICM Contracts Lux L1s on Local Network
---

This how-to guide focuses on deploying ICM contract-enabled Lux L1s to a local Lux network.

After this tutorial, you would have created and deployed two Lux L1s to the local network and have enabled them to cross-communicate with each other and with the local LUExchange-Chain (through ICM contracts and the underlying Warp technology.)

Note that currently only [Subnet-EVM](https://github.com/luxfi/subnet-evm) and [Subnet-EVM-Based](/docs/lux-l1s/evm-configuration/evm-l1-customization) virtual machines support ICM contracts.

## Prerequisites

- [Lux-CLI installed](/docs/tooling/lux-cli)

## Create Lux L1 Configurations

Let's create an Lux L1 called `<chain1>` with the latest Subnet-EVM version, a chain ID of 1, TOKEN1 as the token name, and with default Subnet-EVM parameters (more information regarding Lux L1 creation can be found [here](/docs/tooling/lux-cli#create-your-lux-l1-configuration)):

```
lux blockchain create <chain1> --evm --latest\
    --evm-chain-id 1 --evm-token TOKEN1 --evm-defaults

creating genesis for <blockchain chain1>
configuring airdrop to stored key "subnet_<chain1>_airdrop" with address 0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created Lux L1 configuration
```

Notice that by default, ICM contracts are enabled and a stored key is created to fund ICM contract related operations (that is deploy ICM smart contracts, fund ICM Relayer).

To disable ICM contracts in your Lux L1, use the flag `--teleporter=false` when creating the Lux L1.

To disable Relayer in your Lux L1, use the flag `--relayer=false` when creating the Lux L1.

Now let's create a second Lux L1 called `<chain2>`, with similar settings:

```
lux blockchain create <chain2> --evm --latest\

creating genesis for <blockchain chain2>
configuring airdrop to stored key "subnet_<chain2>_airdrop" with address 0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created Lux L1 configuration
```

## Deploy the Lux L1s to Local Network

Let's deploy `<chain1>`:

```
lux blockchain deploy <chain1> --local


Deploying [<chain1>] to Local Network
Backend controller started, pid: 149427, output at: ~/.lux-cli/runs/server_20240229_165923/lux-cli-backend.log

Booting Network. Wait until healthy...
Node logs directory: ~/.lux-cli/runs/network_20240229_165923/node<i>/logs
Network ready to use.

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger successfully deployed to c-chain (0xF7cBd95f1355f0d8d659864b92e2e9fbfaB786f7)
Teleporter Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)

Teleporter Messenger successfully deployed to <chain1> (0xF7cBd95f1355f0d8d659864b92e2e9fbfaB786f7)
Teleporter Registry successfully deployed to <chain1> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                        URL                                         |                  ALIAS URL                 |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc
Funded address:   0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1 with 1000000 (10^18) - private key: 16289399c9466912ffffffdc093c9b51124f0dc54ac7a766b2bc5ccf558d8eee
Network name:     <chain1>
Chain ID:         1
Currency Symbol:  TOKEN1
```

Notice some details here:

- Two smart contracts are deployed to each Lux L1: Teleporter Messenger and Teleporter Registry
- Both ICM smart contracts are also deployed to `LUExchange-Chain` in the Local Network
- [AWM ICM Relayer](https://github.com/luxfi/icm-services/tree/main/relayer) is installed, configured and executed in background (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Lux L1 and sends them to the destination Lux L1.)

CLI configures the Relayer to enable every Lux L1 to send messages to all other Lux L1s. If you add more Lux L1s, the Relayer will be automatically reconfigured.

When deploying Lux L1 `<chain2>`, the two ICM contracts will not be deployed to LUExchange-Chain in Local Network as they have already been deployed when we deployed the first Lux L1.

```
lux blockchain deploy <chain2> --local

Deploying [<chain2>] to Local Network

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger has already been deployed to c-chain

Teleporter Messenger successfully deployed to <chain2> (0xF7cBd95f1355f0d8d659864b92e2e9fbfaB786f7)
Teleporter Registry successfully deployed to <chain2> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                         URL                                         |                  ALIAS URL                 |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain2> | http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9650/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain2> | http://127.0.0.1:9652/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9652/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain2> | http://127.0.0.1:9654/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9654/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain2> | http://127.0.0.1:9656/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9656/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain2> | http://127.0.0.1:9658/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9658/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc
Funded address:   0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB with 1000000 (10^18) - private key: 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
Network name:     <chain2>
Chain ID:         2
Currency Symbol:  TOKEN2
```

## Verify ICM Contracts Are Successfully Set Up

To verify that ICM contracts are successfully set up, let's send a couple of cross messages:

```
lux teleporter msg LUExchange-Chain chain1 "Hello World" --local

Delivering message "this is a message" to source Lux L1 "LUExchange-Chain"
Waiting for message to be received at destination Lux L1 Lux L1 "chain1"
Message successfully Teleported!
```

```
lux teleporter msg chain2 chain1 "Hello World" --local

Delivering message "this is a message" to source Lux L1 "chain2"
Waiting for message to be received at destination Lux L1 Lux L1 "chain1"
Message successfully Teleported!
```

You have sent your first ICM message in the Local Network!

Relayer related logs can be found at `~/.lux-cli/runs/awm-relayer.log`, and Relayer configuration can be found at `~/.lux-cli/runs/awm-relayer-config.json`

Obtaining Information on ICM Contract Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Lux L1 Information[​](#obtaining-lux-l1-information "Direct link to heading")

By executing `blockchain describe` on an ICM contract-enabled Lux L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```
lux blockchain describe <chain1>

 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/
+--------------------------------+-------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                 |
+--------------------------------+-------------------------------------------------------------------------------------+
| Lux L1 Name                    | chain1                                                                             |
+--------------------------------+-------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                        |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network SubnetID         | 2CZP2ndbQnZxTzGuZjPrJAm5b4s2K2Bcjh8NqWoymi8NZMLYQk                                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network RPC URL          | http://127.0.0.1:9650/ext/bc/2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8/rpc |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network BlockchainID     | 2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8                                  |
+                                +-------------------------------------------------------------------------------------+
|                                | 0xd3bc5f71e6946d17c488d320cd1f6f5337d9dce75b3fac5023433c4634b6e91e                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network Teleporter       | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                          |
| Messenger Address              |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network Teleporter       | 0xbD9e8eC38E43d34CAB4194881B9BF39d639D7Bd3                                          |
| Registry Address               |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+

...
```

### Obtaining LUExchange-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for LUExchange-Chain by using `primary describe`:

```
lux primary describe --local

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://127.0.0.1:9650/ext/bc/C/rpc                                 |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | LUX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.829989485                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2JeJDKL9Bvn1vLuuPL1DpUccBCVUh7iRnkv3a5pV9kJW5HbuQz                 |
+                              +--------------------------------------------------------------------+
|                              | 0xabc1bd35cb7313c8a2b62980172e6d7ef42aaa532c870499a148858b0b6a34fd |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

Besides having the option to not use a Relayer at Lux L1 creation time, the Relayer can be stopped and restarted on used request.

To stop the Relayer:

```
lux interchain relayer stop --local

✓ Local AWM Relayer successfully stopped
```

To start it again:

```
lux interchain relayer start --local

using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...
✓ Local AWM Relayer successfully started
Logs can be found at ~/.lux-cli/runs/awm-relayer.log

```



# What is ICM Contracts? (/docs/cross-chain/icm-contracts/overview)

---
title: "What is ICM Contracts?"
description: "ICM Contracts is a messaging protocol built on top of Lux Interchain Messaging that provides a developer-friendly interface for sending and receiving cross-chain messages from the EVM."
edit_url: https://github.com/luxfi/icm-contracts/edit/main/contracts/teleporter/README.md
---

# ICM Protocol

- [Overview](#overview)
- [Data Flow](#data-flow)
- [Properties](#properties)
- [Fees](#fees)
- [Message Receipts and Fee Redemption](#message-receipts-and-fee-redemption)
- [Required Interface](#required-interface)
- [Message Delivery and Execution](#message-delivery-and-execution)
- [Resending a Message](#resending-a-message)
- [TeleporterMessenger Contract Deployment](#teleportermessenger-contract-deployment)
- [Deployed Addresses](#deployed-addresses)
- [A Note on Versioning](#a-note-on-versioning)
- [Upgradability](#upgradability)
- [Deploy TeleporterMessenger to an L1](#deploy-teleportermessenger-to-an-lux-l1)
- [Deploy TeleporterRegistry to an L1](#deploy-teleporterregistry-to-an-lux-l1)
- [Verify a Deployment of TeleporterMessenger](#verify-a-deployment-of-teleportermessenger)

> **Note on Terminology:** In this documentation, **ICM Contract** refers to any smart contract that interfaces with Lux's native Interchain Messaging (ICM) protocol. **Teleporter** (specifically `TeleporterMessenger`) is one such implementation—a production-ready, developer-friendly ICM Contract provided in this repository. The underlying ICM protocol is extensible, and developers are free to build their own custom ICM Contracts tailored to specific use cases. Teleporter serves as a reference implementation and a convenient abstraction layer for most cross-chain communication needs.

## Overview

`TeleporterMessenger` is a smart contract that serves as the interface for ICM contracts to [Lux Interchain Messaging (ICM)](https://build.lux.network/academy/interchain-messaging/04-icm-basics/01-icm-basics). It provides a mechanism to asynchronously invoke smart contract functions on other EVM L1s within Lux. `TeleporterMessenger` provides a handful of useful features to ICM, such as specifying relayer incentives for message delivery, replay protection, message delivery and execution retries, and a standard interface for sending and receiving messages within a dApp deployed across multiple Lux L1s.

The `TeleporterMessenger` contract is a user-friendly interface to ICM, aimed at dApp developers. All of the message signing and verification is abstracted away from developers. Instead, developers simply call `sendCrossChainMessage` on the `TeleporterMessenger` contract to send a message invoking a smart contract on another Lux L1, and implement the `ITeleporterReceiver` interface to receive messages on the destination Lux L1. `TeleporterMessenger` handles all of the ICM message construction and sending, as well as the message delivery and execution.

To get started with using `TeleporterMessenger`, see [How to Deploy ICM Enabled Lux L1s on a Local Network](https://build.lux.network/docs/tooling/cross-chain/teleporter-local-network)

The `ITeleporterMessenger` interface provides two primary methods:

- `sendCrossChainMessage`: called by contracts on the origin chain to initiate the sending of a message to a contract on another EVM instance.
- `receiveCrossChainMessage`: called by cross-chain relayers on the destination chain to deliver signed messages to the destination EVM instance.

The `ITeleporterReceiver` interface provides a single method. All contracts that wish to receive ICM messages on the destination chain must implement this interface:

- `receiveTeleporterMessage`: called by `TeleporterMessenger` on the destination chain to deliver a message to the destination contract.

> Note: If a contract does not implement `ITeleporterReceiver`, but instead implements [fallback](https://docs.soliditylang.org/en/latest/contracts.html#fallback-function), the fallback function will be called when `TeleporterMessenger` attempts to perform message execution. The message execution is marked as failed if the fallback function reverts, otherwise it is marked as successfully executed.

## Data Flow

<div align="center">
  <img src="https://raw.githubusercontent.com/luxfi/icm-contracts/main/resources/TeleporterDataFlowDiagram.png" />/>
</div>

## Properties

TeleporterMessenger provides a handful of useful properties to cross-chain applications that ICM messages do not provide by default. These include:

1. Replay protection: `TeleporterMessenger` ensures that a cross-chain message is not delivered multiple times.
2. Retries: In certain edge cases when there is significant validator churn, it is possible for an ICM Message to be dropped before a valid aggregate signature is created for it. `TeleporterMessenger` ensures that messages can still be delivered even in this event by allowing for retries of previously submitted messages.
3. Relay incentivization: `TeleporterMessenger` provides a mechanism for messages to optionally incentivize relayers to perform the necessary signature aggregation and pay the transaction fee to broadcast the signed message on the destination chain.
4. Allowed relayers: `TeleporterMessenger` allows users to specify a list of `allowedRelayerAddresses`, where only the specified addresses can relay and deliver the `TeleporterMessenger` message. Leaving this list empty allows all relayers to deliver.
5. Message execution: `TeleporterMessenger` enables cross-chain messages to have direct effect on their destination chain by using `evm.Call()` to invoke the `receiveTeleporterMessage` function of destination contracts that implement the `ITeleporterReceiver` interface.

## Fees

Fees can be paid on a per message basis by specifing the ERC20 asset and amount to be used to incentivize a relayer to deliver the message in the call to `sendCrossChainMessage`. The fee amount is transferred into the control of `TeleporterMessenger` (i.e. locked) before the ICM message is sent. `TeleporterMessenger` tracks the fee amount for each message ID it creates. When it subsequently receives a message back from the destination chain of the original message, the new message will have a list of receipts identifying the relayer that delivered the given message ID. At this point, the fee amount originally locked by `TeleporterMessenger` for the given message will be redeemable by the relayer identified in the receipt. If the initial fee amount was not sufficient to incentivize a relayer, it can be added to by using `addFeeAmount`.

### Message Receipts and Fee Redemption

In order to confirm delivery of a `TeleporterMessenger` message from a source chain to a destination chain, a receipt is included in the next `TeleporterMessenger` message sent in the opposite direction, from the destination chain back to the source chain. This receipt contains the message ID of the original message, as well as the reward address that the delivering relayer specified. That reward address is then able to redeem the corresponding reward on the original chain by calling `redeemRelayerRewards`. The following example illustrates this flow:

- A `TeleporterMessenger` message is sent from Chain A to Chain B, with a relayer incentive of `10` `USDC`. This message is assigned the ID `1` by the `TeleporterMessenger` contract on Chain A.
  - On Chain A, this is done by calling `sendCrossChainMessage`, and providing the `USDC` contract address and amount in the function call.
- A relayer delivers the message on Chain B by calling `receiveCrossChainMessage` and providing its address, `0x123...`
- The `TeleporterMessenger` contract on Chain B stores the relayer address in a receipt for the message ID.
- Some time later, a separate `TeleporterMessenger` message is sent from Chain B to Chain A. The `TeleporterMessenger` contract on Chain B includes the receipt for the original message in this new message.
- When this new message is delivered on Chain A, the `TeleporterMessenger` contract on Chain A reads the receipt and attributes the rewards for delivering the original message (message ID `1`) to the address `0x123...`.
- Address `0x123...` may now call `redeemRelayerRewards` on Chain A, which transfers the `10` `USDC` to its address. If it tries to do this before the receipt is received on Chain A, the call will fail.

It is possible for receipts to get "stuck" on the destination chain in the event that `TeleporterMessenger` traffic between two chains is skewed in one direction. In such a scenario, incoming messages on one chain may cause the rate at which receipts are generated to outpace the rate at which they are sent back to the other chain. To mitigate this, the method `sendSpecifiedReceipts` can be called to immediately send the receipts associated with the given message IDs back to the original chain.

## Required Interface

`TeleporterMessenger` messages are delivered by calling the `receiveTeleporterMessage` function defined by the `ITeleporterReceiver` interface. Contracts must implement this interface in order to be able to receive messages. The first two parameters of `receiveTeleporterMessage` identify the original sender of the given message on the origin chain and are set by the `TeleporterMessenger`. The third parameter to `receiveTeleporterMessage`, is the raw message payload. Applications using `TeleporterMessenger` are responsible for defining the exact format of this payload in a way that can be decoded on the receiving end. For example, applications may encode an action enum value along with the target method parameters on the sending side, then decode this data and route to the target method within `receiveTeleporterMessage`. See `ERC20Bridge.sol` for an example of this approach.

## Message Delivery and Execution

`TeleporterMessenger` is able to ensure that messages are considered delivered even if their execution fails (i.e. reverts) by using `evm.Call()` with a pre-defined gas limit to execute the message payload. This gas limit is specified by each message in the call to `sendCrossChainMessage`. Relayers must provide at least enough gas for the sub-call in addition to the standard gas used by a call to `receiveCrossChainMessage`. In the event that a message execution runs out of gas or reverts for any other reason, the hash of the message payload is stored by the receiving `TeleporterMessenger` contract instance. This allows for the message execution to be retried in the future, with possibly a higher gas limit by calling `retryMessageExecution`. Importantly, a message is still considered delivered on its destination chain even if its execution fails. This allows the relayer of the message to redeem their reward for deliverying the message, because they have no control on whether or not its execution will succeed or not so long as they provide sufficient gas to meet the specified `requiredGasLimit`.

Note that due to [EIP-150](https://eips.ethereum.org/EIPS/eip-150), the lesser of 63/64<sup>ths</sup> of the remaining gas and the `requiredGasLimit` will be provided to the code executed using `evm.Call()`. This creates an edge case where sufficient gas is provided by the relayer at time of the `requiredGasLimit` check, but less than the `requiredGasLimit` is provided for the message execution. In such a case, the message execution may fail due to having less than the `requiredGasLimit` available, but the message would still be considered received. Such a case is only possible if the remaining 1/64<sup>th</sup> of the `requiredGasLimit` is sufficient for executing the remaining logic of `receiveCrossChainMessage` so that the top level transaction does not also revert. Based on the current implementation, a message must have a `requiredGasLimit` of over 1,200,000 gas for this to be possible. In order to avoid this case entirely, it is recommended for applications sending `TeleporterMessenger` messages to add a buffer to the `requiredGasLimit` such that 63/64<sup>ths</sup> of the value passed is sufficient for the message execution.

## Resending a Message

If the sending Lux L1's validator set changes, then it's possible for the receiving Lux L1 to reject the underlying ICM message due to insufficient signing stake. For example, suppose L1 A has 5 validators with equal stake weight who all sign a `TeleporterMessenger` message sent to L1 B. 100% of L1 A's stake has signed the message. Also suppose L1 B requires 67% of the sending L1's stake to have signed a given ICM message in order for it to be accepted. Before the message can be delivered, however, 5 _more_ validators are added to L1 A's validator set (all with the same stake weight as the original validators), meaning that the `TeleporterMessenger` message was signed by _only 50%_ of L1 A's stake. L1 B will reject this message.

Once sent on chain, ICM messages cannot be re-signed by a new validator set in such a scenario. ICM Contracts, however, do support re-signing via the function `retrySendCrossChainMessage`, which can be called for any message that has not been acknowledged as delivered to its destination. Under the hood, this packages the `TeleporterMessenger` message into a brand new ICM message that is re-signed by the current validator set. 

## TeleporterMessenger Contract Deployment

**Do not deploy the `TeleporterMessenger` contract using `forge create`**. The `TeleporterMessenger` contract must be deployed to the same contract address on every chain. To achieve this, the contract can be deployed using a static transaction that uses Nick's method as documented in [this guide](https://github.com/luxfi/icm-contracts/blob/main/utils/contract-deployment/README.md). Alternatively, if creating a new L1, the contract can be pre-allocated with the proper address and state in the new chain's [genesis file](https://build.lux.network/docs/virtual-machines/custom-precompiles#setting-the-genesis-allocation).

As an example, to include `TeleporterMessenger` `v1.0.0` in the genesis file, include the following values in the `alloc` settings, as documented at the link above. The `storage` values included below correspond to the two contract values that are initialized as part of the default constructor of `TeleporterMessenger`. These are the `ReentrancyGuard` values set in this [abstract contract](https://github.com/luxfi/icm-contracts/blob/main/contracts/utilities/ReentrancyGuards.sol). Future versions of `TeleporterMessenger` may require different storage value initializations.
```json
"alloc": {
    "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
        "balance": "0x0",
        "code": "0x608060405234801561001057600080fd5b506004361061014d5760003560e01c8063a8898181116100c3578063df20e8bc1161007c578063df20e8bc1461033b578063e69d606a1461034e578063e6e67bd5146103b6578063ebc3b1ba146103f2578063ecc7042814610415578063fc2d61971461041e57600080fd5b8063a8898181146102b2578063a9a85614146102c5578063b771b3bc146102d8578063c473eef8146102e6578063ccb5f8091461031f578063d127dc9b1461033257600080fd5b8063399b77da11610115578063399b77da1461021957806362448850146102395780638245a1b01461024c578063860a3b061461025f578063892bf4121461027f5780638ac0fd041461029f57600080fd5b80630af5b4ff1461015257806322296c3a1461016d5780632bc8b0bf146101825780632ca40f55146101955780632e27c223146101ee575b600080fd5b61015a610431565b6040519081526020015b60405180910390f35b61018061017b366004612251565b610503565b005b61015a61019036600461226e565b6105f8565b6101e06101a336600461226e565b6005602090815260009182526040918290208054835180850190945260018201546001600160a01b03168452600290910154918301919091529082565b604051610164929190612287565b6102016101fc36600461226e565b610615565b6040516001600160a01b039091168152602001610164565b61015a61022736600461226e565b60009081526005602052604090205490565b61015a6102473660046122ae565b61069e565b61018061025a366004612301565b6106fc565b61015a61026d36600461226e565b60066020526000908152604090205481565b61029261028d366004612335565b6108a7565b6040516101649190612357565b6101806102ad366004612377565b6108da565b61015a6102c03660046123af565b610b19565b61015a6102d3366004612426565b610b5c565b6102016005600160991b0181565b61015a6102f43660046124be565b6001600160a01b03918216600090815260096020908152604080832093909416825291909152205490565b61018061032d3660046124f7565b610e03565b61015a60025481565b61015a61034936600461226e565b61123d565b61039761035c36600461226e565b600090815260056020908152604091829020825180840190935260018101546001600160a01b03168084526002909101549290910182905291565b604080516001600160a01b039093168352602083019190915201610164565b6103dd6103c436600461226e565b6004602052600090815260409020805460019091015482565b60408051928352602083019190915201610164565b61040561040036600461226e565b611286565b6040519015158152602001610164565b61015a60035481565b61018061042c36600461251e565b61129c565b600254600090806104fe576005600160991b016001600160a01b0316634213cf786040518163ffffffff1660e01b8152600401602060405180830381865afa158015610481573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906104a59190612564565b9050806104cd5760405162461bcd60e51b81526004016104c49061257d565b60405180910390fd5b600281905560405181907f1eac640109dc937d2a9f42735a05f794b39a5e3759d681951d671aabbce4b10490600090a25b919050565b3360009081526009602090815260408083206001600160a01b0385168452909152902054806105855760405162461bcd60e51b815260206004820152602860248201527f54656c65706f727465724d657373656e6765723a206e6f2072657761726420746044820152676f2072656465656d60c01b60648201526084016104c4565b3360008181526009602090815260408083206001600160a01b03871680855290835281842093909355518481529192917f3294c84e5b0f29d9803655319087207bc94f4db29f7927846944822773780b88910160405180910390a36105f46001600160a01b03831633836114f7565b5050565b600081815260046020526040812061060f9061155f565b92915050565b6000818152600760205260408120546106825760405162461bcd60e51b815260206004820152602960248201527f54656c65706f727465724d657373656e6765723a206d657373616765206e6f74604482015268081c9958d95a5d995960ba1b60648201526084016104c4565b506000908152600860205260409020546001600160a01b031690565b60006001600054146106c25760405162461bcd60e51b81526004016104c4906125c4565b60026000556106f16106d383612804565b833560009081526004602052604090206106ec90611572565b61167c565b600160005592915050565b60016000541461071e5760405162461bcd60e51b81526004016104c4906125c4565b6002600081815590546107379060408401358435610b19565b6000818152600560209081526040918290208251808401845281548152835180850190945260018201546001600160a01b03168452600290910154838301529081019190915280519192509061079f5760405162461bcd60e51b81526004016104c4906128a7565b6000836040516020016107b29190612b42565b60408051601f19818403018152919052825181516020830120919250146107eb5760405162461bcd60e51b81526004016104c490612b55565b8360400135837f2a211ad4a59ab9d003852404f9c57c690704ee755f3c79d2c2812ad32da99df8868560200151604051610826929190612b9e565b60405180910390a360405163ee5b48eb60e01b81526005600160991b019063ee5b48eb90610858908490600401612c23565b6020604051808303816000875af1158015610877573d6000803e3d6000fd5b505050506040513d601f19601f8201168201806040525081019061089b9190612564565b50506001600055505050565b604080518082019091526000808252602082015260008381526004602052604090206108d390836118bc565b9392505050565b6001600054146108fc5760405162461bcd60e51b81526004016104c4906125c4565b600260005560018054146109225760405162461bcd60e51b81526004016104c490612c36565b60026001558061098c5760405162461bcd60e51b815260206004820152602f60248201527f54656c65706f727465724d657373656e6765723a207a65726f2061646469746960448201526e1bdb985b0819995948185b5bdd5b9d608a1b60648201526084016104c4565b6001600160a01b0382166109b25760405162461bcd60e51b81526004016104c490612c7b565b6000838152600560205260409020546109dd5760405162461bcd60e51b81526004016104c4906128a7565b6000838152600560205260409020600101546001600160a01b03838116911614610a6f5760405162461bcd60e51b815260206004820152603760248201527f54656c65706f727465724d657373656e6765723a20696e76616c69642066656560448201527f20617373657420636f6e7472616374206164647265737300000000000000000060648201526084016104c4565b6000610a7b8383611981565b600085815260056020526040812060020180549293508392909190610aa1908490612ce5565b909155505060008481526005602052604090819020905185917fc1bfd1f1208927dfbd414041dcb5256e6c9ad90dd61aec3249facbd34ff7b3e191610b03916001019081546001600160a01b0316815260019190910154602082015260400190565b60405180910390a2505060018080556000555050565b60408051306020820152908101849052606081018390526080810182905260009060a0016040516020818303038152906040528051906020012090509392505050565b6000600160005414610b805760405162461bcd60e51b81526004016104c4906125c4565b60026000818155905490866001600160401b03811115610ba257610ba2612607565b604051908082528060200260200182016040528015610be757816020015b6040805180820190915260008082526020820152815260200190600190039081610bc05790505b5090508660005b81811015610d6c5760008a8a83818110610c0a57610c0a612cf8565b90506020020135905060006007600083815260200190815260200160002054905080600003610c8a5760405162461bcd60e51b815260206004820152602660248201527f54656c65706f727465724d657373656e6765723a2072656365697074206e6f7460448201526508199bdd5b9960d21b60648201526084016104c4565b610c958d8783610b19565b8214610d095760405162461bcd60e51b815260206004820152603a60248201527f54656c65706f727465724d657373656e6765723a206d6573736167652049442060448201527f6e6f742066726f6d20736f7572636520626c6f636b636861696e00000000000060648201526084016104c4565b6000828152600860209081526040918290205482518084019093528383526001600160a01b03169082018190528651909190879086908110610d4d57610d4d612cf8565b602002602001018190525050505080610d6590612d0e565b9050610bee565b506040805160c0810182528b815260006020820152610df0918101610d96368b90038b018b612d27565b8152602001600081526020018888808060200260200160405190810160405280939291908181526020018383602002808284376000920182905250938552505060408051928352602080840190915290920152508361167c565b60016000559a9950505050505050505050565b6001805414610e245760405162461bcd60e51b81526004016104c490612c36565b60026001556040516306f8253560e41b815263ffffffff8316600482015260009081906005600160991b0190636f82535090602401600060405180830381865afa158015610e76573d6000803e3d6000fd5b505050506040513d6000823e601f3d908101601f19168201604052610e9e9190810190612da3565b9150915080610f015760405162461bcd60e51b815260206004820152602960248201527f54656c65706f727465724d657373656e6765723a20696e76616c69642077617260448201526870206d65737361676560b81b60648201526084016104c4565b60208201516001600160a01b03163014610f785760405162461bcd60e51b815260206004820152603260248201527f54656c65706f727465724d657373656e6765723a20696e76616c6964206f726960448201527167696e2073656e646572206164647265737360701b60648201526084016104c4565b60008260400151806020019051810190610f929190612f40565b90506000610f9e610431565b90508082604001511461100d5760405162461bcd60e51b815260206004820152603160248201527f54656c65706f727465724d657373656e6765723a20696e76616c6964206465736044820152701d1a5b985d1a5bdb8818da185a5b881251607a1b60648201526084016104c4565b8351825160009161101f918490610b19565b600081815260076020526040902054909150156110945760405162461bcd60e51b815260206004820152602d60248201527f54656c65706f727465724d657373656e6765723a206d65737361676520616c7260448201526c1958591e481c9958d95a5d9959609a1b60648201526084016104c4565b6110a2338460a00151611ae9565b6111005760405162461bcd60e51b815260206004820152602960248201527f54656c65706f727465724d657373656e6765723a20756e617574686f72697a6560448201526832103932b630bcb2b960b91b60648201526084016104c4565b61110e818460000151611b61565b6001600160a01b0386161561114557600081815260086020526040902080546001600160a01b0319166001600160a01b0388161790555b60c08301515160005b81811015611192576111828488600001518760c00151848151811061117557611175612cf8565b6020026020010151611bd3565b61118b81612d0e565b905061114e565b50604080518082018252855181526001600160a01b038916602080830191909152885160009081526004909152919091206111cc91611cfb565b336001600160a01b03168660000151837f292ee90bbaf70b5d4936025e09d56ba08f3e421156b6a568cf3c2840d9343e348a8860405161120d929190613150565b60405180910390a460e0840151511561122f5761122f82876000015186611d57565b505060018055505050505050565b600254600090806112605760405162461bcd60e51b81526004016104c49061257d565b600060035460016112719190612ce5565b905061127e828583610b19565b949350505050565b600081815260076020526040812054151561060f565b60018054146112bd5760405162461bcd60e51b81526004016104c490612c36565b60026001819055546000906112d59084908435610b19565b600081815260066020526040902054909150806113045760405162461bcd60e51b81526004016104c4906128a7565b80836040516020016113169190612b42565b60405160208183030381529060405280519060200120146113495760405162461bcd60e51b81526004016104c490612b55565b600061135b6080850160608601612251565b6001600160a01b03163b116113cf5760405162461bcd60e51b815260206004820152603460248201527f54656c65706f727465724d657373656e6765723a2064657374696e6174696f6e604482015273206164647265737320686173206e6f20636f646560601b60648201526084016104c4565b604051849083907f34795cc6b122b9a0ae684946319f1e14a577b4e8f9b3dda9ac94c21a54d3188c90600090a360008281526006602090815260408083208390558691611420918701908701612251565b61142d60e0870187613174565b60405160240161144094939291906131ba565b60408051601f198184030181529190526020810180516001600160e01b031663643477d560e11b179052905060006114886114816080870160608801612251565b5a84611e8a565b9050806114eb5760405162461bcd60e51b815260206004820152602b60248201527f54656c65706f727465724d657373656e6765723a20726574727920657865637560448201526a1d1a5bdb8819985a5b195960aa1b60648201526084016104c4565b50506001805550505050565b6040516001600160a01b03831660248201526044810182905261155a90849063a9059cbb60e01b906064015b60408051601f198184030181529190526020810180516001600160e01b03166001600160e01b031990931692909217909152611ea4565b505050565b8054600182015460009161060f916131e5565b6060600061158960056115848561155f565b611f76565b9050806000036115d85760408051600080825260208201909252906115d0565b60408051808201909152600080825260208201528152602001906001900390816115a95790505b509392505050565b6000816001600160401b038111156115f2576115f2612607565b60405190808252806020026020018201604052801561163757816020015b60408051808201909152600080825260208201528152602001906001900390816116105790505b50905060005b828110156115d05761164e85611f8c565b82828151811061166057611660612cf8565b60200260200101819052508061167590612d0e565b905061163d565b600080611687610431565b9050600060036000815461169a90612d0e565b919050819055905060006116b383876000015184610b19565b90506000604051806101000160405280848152602001336001600160a01b031681526020018860000151815260200188602001516001600160a01b0316815260200188606001518152602001886080015181526020018781526020018860a00151815250905060008160405160200161172c91906131f8565b60405160208183030381529060405290506000808960400151602001511115611794576040890151516001600160a01b031661177a5760405162461bcd60e51b81526004016104c490612c7b565b604089015180516020909101516117919190611981565b90505b6040805180820182528a820151516001600160a01b039081168252602080830185905283518085018552865187830120815280820184815260008a815260058452869020915182555180516001830180546001600160a01b03191691909516179093559101516002909101558a51915190919086907f2a211ad4a59ab9d003852404f9c57c690704ee755f3c79d2c2812ad32da99df890611838908890869061320b565b60405180910390a360405163ee5b48eb60e01b81526005600160991b019063ee5b48eb9061186a908690600401612c23565b6020604051808303816000875af1158015611889573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906118ad9190612564565b50939998505050505050505050565b60408051808201909152600080825260208201526118d98361155f565b82106119315760405162461bcd60e51b815260206004820152602160248201527f5265636569707451756575653a20696e646578206f7574206f6620626f756e646044820152607360f81b60648201526084016104c4565b8260020160008385600001546119479190612ce5565b81526020808201929092526040908101600020815180830190925280548252600101546001600160a01b0316918101919091529392505050565b6040516370a0823160e01b815230600482015260009081906001600160a01b038516906370a0823190602401602060405180830381865afa1580156119ca573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906119ee9190612564565b9050611a056001600160a01b038516333086612058565b6040516370a0823160e01b81523060048201526000906001600160a01b038616906370a0823190602401602060405180830381865afa158015611a4c573d6000803e3d6000fd5b505050506040513d601f19601f82011682018060405250810190611a709190612564565b9050818111611ad65760405162461bcd60e51b815260206004820152602c60248201527f5361666545524332305472616e7366657246726f6d3a2062616c616e6365206e60448201526b1bdd081a5b98dc99585cd95960a21b60648201526084016104c4565b611ae082826131e5565b95945050505050565b60008151600003611afc5750600161060f565b815160005b81811015611b5657846001600160a01b0316848281518110611b2557611b25612cf8565b60200260200101516001600160a01b031603611b465760019250505061060f565b611b4f81612d0e565b9050611b01565b506000949350505050565b80600003611bc15760405162461bcd60e51b815260206004820152602760248201527f54656c65706f727465724d657373656e6765723a207a65726f206d657373616760448201526665206e6f6e636560c81b60648201526084016104c4565b60009182526007602052604090912055565b6000611be484848460000151610b19565b6000818152600560209081526040918290208251808401845281548152835180850190945260018201546001600160a01b031684526002909101548383015290810191909152805191925090611c3b575050505050565b60008281526005602090815260408083208381556001810180546001600160a01b03191690556002018390558382018051830151878401516001600160a01b0390811686526009855283862092515116855292528220805491929091611ca2908490612ce5565b9250508190555082602001516001600160a01b031684837fd13a7935f29af029349bed0a2097455b91fd06190a30478c575db3f31e00bf578460200151604051611cec919061321e565b60405180910390a45050505050565b6001820180548291600285019160009182611d1583612d0e565b90915550815260208082019290925260400160002082518155910151600190910180546001600160a01b0319166001600160a01b039092169190911790555050565b80608001515a1015611db95760405162461bcd60e51b815260206004820152602560248201527f54656c65706f727465724d657373656e6765723a20696e73756666696369656e604482015264742067617360d81b60648201526084016104c4565b80606001516001600160a01b03163b600003611dda5761155a838383612096565b602081015160e0820151604051600092611df892869260240161323e565b60408051601f198184030181529190526020810180516001600160e01b031663643477d560e11b17905260608301516080840151919250600091611e3d919084611e8a565b905080611e5657611e4f858585612096565b5050505050565b604051849086907f34795cc6b122b9a0ae684946319f1e14a577b4e8f9b3dda9ac94c21a54d3188c90600090a35050505050565b60008060008084516020860160008989f195945050505050565b6000611ef9826040518060400160405280602081526020017f5361666545524332303a206c6f772d6c6576656c2063616c6c206661696c6564815250856001600160a01b031661210b9092919063ffffffff16565b80519091501561155a5780806020019051810190611f179190613268565b61155a5760405162461bcd60e51b815260206004820152602a60248201527f5361666545524332303a204552433230206f7065726174696f6e20646964206e6044820152691bdd081cdd58d8d9595960b21b60648201526084016104c4565b6000818310611f8557816108d3565b5090919050565b604080518082019091526000808252602082015281546001830154819003611ff65760405162461bcd60e51b815260206004820152601960248201527f5265636569707451756575653a20656d7074792071756575650000000000000060448201526064016104c4565b60008181526002840160208181526040808420815180830190925280548252600180820180546001600160a01b03811685870152888852959094529490556001600160a01b031990921690559061204e908390612ce5565b9093555090919050565b6040516001600160a01b03808516602483015283166044820152606481018290526120909085906323b872dd60e01b90608401611523565b50505050565b806040516020016120a791906131f8565b60408051601f1981840301815282825280516020918201206000878152600690925291902055829084907f4619adc1017b82e02eaefac01a43d50d6d8de4460774bc370c3ff0210d40c985906120fe9085906131f8565b60405180910390a3505050565b606061127e848460008585600080866001600160a01b031685876040516121329190613283565b60006040518083038185875af1925050503d806000811461216f576040519150601f19603f3d011682016040523d82523d6000602084013e612174565b606091505b509150915061218587838387612190565b979650505050505050565b606083156121ff5782516000036121f8576001600160a01b0385163b6121f85760405162461bcd60e51b815260206004820152601d60248201527f416464726573733a2063616c6c20746f206e6f6e2d636f6e747261637400000060448201526064016104c4565b508161127e565b61127e83838151156122145781518083602001fd5b8060405162461bcd60e51b81526004016104c49190612c23565b6001600160a01b038116811461224357600080fd5b50565b80356104fe8161222e565b60006020828403121561226357600080fd5b81356108d38161222e565b60006020828403121561228057600080fd5b5035919050565b828152606081016108d3602083018480516001600160a01b03168252602090810151910152565b6000602082840312156122c057600080fd5b81356001600160401b038111156122d657600080fd5b820160e081850312156108d357600080fd5b600061010082840312156122fb57600080fd5b50919050565b60006020828403121561231357600080fd5b81356001600160401b0381111561232957600080fd5b61127e848285016122e8565b6000806040838503121561234857600080fd5b50508035926020909101359150565b815181526020808301516001600160a01b0316908201526040810161060f565b60008060006060848603121561238c57600080fd5b83359250602084013561239e8161222e565b929592945050506040919091013590565b6000806000606084860312156123c457600080fd5b505081359360208301359350604090920135919050565b60008083601f8401126123ed57600080fd5b5081356001600160401b0381111561240457600080fd5b6020830191508360208260051b850101111561241f57600080fd5b9250929050565b60008060008060008086880360a081121561244057600080fd5b8735965060208801356001600160401b038082111561245e57600080fd5b61246a8b838c016123db565b90985096508691506040603f198401121561248457600080fd5b60408a01955060808a013592508083111561249e57600080fd5b50506124ac89828a016123db565b979a9699509497509295939492505050565b600080604083850312156124d157600080fd5b82356124dc8161222e565b915060208301356124ec8161222e565b809150509250929050565b6000806040838503121561250a57600080fd5b823563ffffffff811681146124dc57600080fd5b6000806040838503121561253157600080fd5b8235915060208301356001600160401b0381111561254e57600080fd5b61255a858286016122e8565b9150509250929050565b60006020828403121561257657600080fd5b5051919050565b60208082526027908201527f54656c65706f727465724d657373656e6765723a207a65726f20626c6f636b636040820152661a185a5b88125160ca1b606082015260800190565b60208082526023908201527f5265656e7472616e63794775617264733a2073656e646572207265656e7472616040820152626e637960e81b606082015260800190565b634e487b7160e01b600052604160045260246000fd5b604080519081016001600160401b038111828210171561263f5761263f612607565b60405290565b60405160c081016001600160401b038111828210171561263f5761263f612607565b60405161010081016001600160401b038111828210171561263f5761263f612607565b604051601f8201601f191681016001600160401b03811182821017156126b2576126b2612607565b604052919050565b6000604082840312156126cc57600080fd5b6126d461261d565b905081356126e18161222e565b808252506020820135602082015292915050565b60006001600160401b0382111561270e5761270e612607565b5060051b60200190565b600082601f83011261272957600080fd5b8135602061273e612739836126f5565b61268a565b82815260059290921b8401810191818101908684111561275d57600080fd5b8286015b848110156127815780356127748161222e565b8352918301918301612761565b509695505050505050565b60006001600160401b038211156127a5576127a5612607565b50601f01601f191660200190565b600082601f8301126127c457600080fd5b81356127d26127398261278c565b8181528460208386010111156127e757600080fd5b816020850160208301376000918101602001919091529392505050565b600060e0823603121561281657600080fd5b61281e612645565b8235815261282e60208401612246565b602082015261284036604085016126ba565b60408201526080830135606082015260a08301356001600160401b038082111561286957600080fd5b61287536838701612718565b608084015260c085013591508082111561288e57600080fd5b5061289b368286016127b3565b60a08301525092915050565b60208082526026908201527f54656c65706f727465724d657373656e6765723a206d657373616765206e6f7460408201526508199bdd5b9960d21b606082015260800190565b6000808335601e1984360301811261290457600080fd5b83016020810192503590506001600160401b0381111561292357600080fd5b8060051b360382131561241f57600080fd5b8183526000602080850194508260005b858110156129735781356129588161222e565b6001600160a01b031687529582019590820190600101612945565b509495945050505050565b6000808335601e1984360301811261299557600080fd5b83016020810192503590506001600160401b038111156129b457600080fd5b8060061b360382131561241f57600080fd5b8183526000602080850194508260005b858110156129735781358752828201356129ef8161222e565b6001600160a01b03168784015260409687019691909101906001016129d6565b6000808335601e19843603018112612a2657600080fd5b83016020810192503590506001600160401b03811115612a4557600080fd5b80360382131561241f57600080fd5b81835281816020850137506000828201602090810191909152601f909101601f19169091010190565b6000610100823584526020830135612a948161222e565b6001600160a01b0316602085015260408381013590850152612ab860608401612246565b6001600160a01b0316606085015260808381013590850152612add60a08401846128ed565b8260a0870152612af08387018284612935565b92505050612b0160c084018461297e565b85830360c0870152612b148382846129c6565b92505050612b2560e0840184612a0f565b85830360e0870152612b38838284612a54565b9695505050505050565b6020815260006108d36020830184612a7d565b60208082526029908201527f54656c65706f727465724d657373656e6765723a20696e76616c6964206d65736040820152680e6c2ceca40d0c2e6d60bb1b606082015260800190565b606081526000612bb16060830185612a7d565b90506108d3602083018480516001600160a01b03168252602090810151910152565b60005b83811015612bee578181015183820152602001612bd6565b50506000910152565b60008151808452612c0f816020860160208601612bd3565b601f01601f19169290920160200192915050565b6020815260006108d36020830184612bf7565b60208082526025908201527f5265656e7472616e63794775617264733a207265636569766572207265656e7460408201526472616e637960d81b606082015260800190565b60208082526034908201527f54656c65706f727465724d657373656e6765723a207a65726f2066656520617360408201527373657420636f6e7472616374206164647265737360601b606082015260800190565b634e487b7160e01b600052601160045260246000fd5b8082018082111561060f5761060f612ccf565b634e487b7160e01b600052603260045260246000fd5b600060018201612d2057612d20612ccf565b5060010190565b600060408284031215612d3957600080fd5b6108d383836126ba565b80516104fe8161222e565b600082601f830112612d5f57600080fd5b8151612d6d6127398261278c565b818152846020838601011115612d8257600080fd5b61127e826020830160208701612bd3565b805180151581146104fe57600080fd5b60008060408385031215612db657600080fd5b82516001600160401b0380821115612dcd57600080fd5b9084019060608287031215612de157600080fd5b604051606081018181108382111715612dfc57612dfc612607565b604052825181526020830151612e118161222e565b6020820152604083015182811115612e2857600080fd5b612e3488828601612d4e565b6040830152509350612e4b91505060208401612d93565b90509250929050565b600082601f830112612e6557600080fd5b81516020612e75612739836126f5565b82815260059290921b84018101918181019086841115612e9457600080fd5b8286015b84811015612781578051612eab8161222e565b8352918301918301612e98565b600082601f830112612ec957600080fd5b81516020612ed9612739836126f5565b82815260069290921b84018101918181019086841115612ef857600080fd5b8286015b848110156127815760408189031215612f155760008081fd5b612f1d61261d565b8151815284820151612f2e8161222e565b81860152835291830191604001612efc565b600060208284031215612f5257600080fd5b81516001600160401b0380821115612f6957600080fd5b908301906101008286031215612f7e57600080fd5b612f86612667565b82518152612f9660208401612d43565b602082015260408301516040820152612fb160608401612d43565b60608201526080830151608082015260a083015182811115612fd257600080fd5b612fde87828601612e54565b60a08301525060c083015182811115612ff657600080fd5b61300287828601612eb8565b60c08301525060e08301518281111561301a57600080fd5b61302687828601612d4e565b60e08301525095945050505050565b600081518084526020808501945080840160005b838110156129735781516001600160a01b031687529582019590820190600101613049565b600081518084526020808501945080840160005b83811015612973576130a8878351805182526020908101516001600160a01b0316910152565b6040969096019590820190600101613082565b60006101008251845260018060a01b0360208401511660208501526040830151604085015260608301516130fa60608601826001600160a01b03169052565b506080830151608085015260a08301518160a086015261311c82860182613035565b91505060c083015184820360c0860152613136828261306e565b91505060e083015184820360e0860152611ae08282612bf7565b6001600160a01b038316815260406020820181905260009061127e908301846130bb565b6000808335601e1984360301811261318b57600080fd5b8301803591506001600160401b038211156131a557600080fd5b60200191503681900382131561241f57600080fd5b8481526001600160a01b0384166020820152606060408201819052600090612b389083018486612a54565b8181038181111561060f5761060f612ccf565b6020815260006108d360208301846130bb565b606081526000612bb160608301856130bb565b81516001600160a01b03168152602080830151908201526040810161060f565b8381526001600160a01b0383166020820152606060408201819052600090611ae090830184612bf7565b60006020828403121561327a57600080fd5b6108d382612d93565b60008251613295818460208701612bd3565b919091019291505056fea2646970667358221220586881dd1413fe17197100ceb55646481dae802ef65d37df603c3915f51a4b6364736f6c63430008120033",
        "storage": {
            "0x0000000000000000000000000000000000000000000000000000000000000000": "0x0000000000000000000000000000000000000000000000000000000000000001",
            "0x0000000000000000000000000000000000000000000000000000000000000001": "0x0000000000000000000000000000000000000000000000000000000000000001"
        },
        "nonce": 1
    },
    "0x618FEdD9A45a8C456812ecAAE70C671c6249DfaC": {
        "balance": "0x0",
        "nonce": 1
    }
}
```

The values above are taken from the `v1.0.0` [release artifacts](https://github.com/luxfi/icm-contracts/releases/tag/v1.0.0). The contract address, deployed bytecode, and deployer address are unique per major release. All of the other values should remain the same.

## Deployed Addresses

| Contract              | Address                                        | Chain                    |
| --------------------- | ---------------------------------------------- | ------------------------ |
| `TeleporterMessenger` | **0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf** | All chains, all networks |
| `TeleporterRegistry`  | **0x7C43605E14F391720e1b37E49C78C4b03A488d98** | Mainnet LUExchange-Chain          |
| `TeleporterRegistry`  | **0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228** | Testnet LUExchange-Chain             |

- Using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#), `TeleporterMessenger` deploys at a universal address across all chains, varying with each `teleporter` Major release. **Compatibility exists only between same-version `TeleporterMessenger` instances.** See [TeleporterMessenger Contract Deployment](https://github.com/luxfi/icm-contracts/blob/main/utils/contract-deployment/README.md) and [Deploy TeleporterMessenger to an Lux L1](#deploy-teleportermessenger-to-an-lux-l1) for more details.

- `TeleporterRegistry` can be deployed to any address. See [Deploy TeleporterRegistry to an Lux L1](#deploy-teleporterregistry-to-an-lux-l1) for details. The table above enumerates the canonical registry addresses on the Mainnet and Testnet LUExchange-Chains.

## A Note on Versioning

Release versions follow the [semver](https://semver.org/) convention of incompatible Major releases. A new Major version is released whenever the `TeleporterMessenger` bytecode is changed, and a new version of `TeleporterMessenger` is meant to be deployed. Due to the use of Nick's method to deploy the contract to the same address on all chains (see [TeleporterMessenger Contract Deployment](https://github.com/luxfi/icm-contracts/blob/main/utils/contract-deployment/README.md) for details), this also means that new release versions would result in different `TeleporterMessenger` contract addresses. Minor and Patch versions may pertain to contract changes that do not change the `TeleporterMessenger` bytecode, or to changes in the test frameworks, and will only be included in tags.

## Upgradability

`TeleporterMessenger` is a non-upgradeable contract and can not be changed once it is deployed. This provides immutability to the contracts, and ensures that the contract's behavior at each address is unchanging. However, to allow for new features and potential bug fixes, new versions of `TeleporterMessenger` can be deployed to different addresses. The [TeleporterRegistry](https://github.com/luxfi/icm-contracts/blob/main/contracts/teleporter/registry/TeleporterRegistry.sol) is used to keep track of the deployed versions of Teleporter, and to provide a standard interface for dApps to interact with the different `TeleporterMessenger` versions.

`TeleporterRegistry` **is not mandatory** for dApps built on top of ICM, but dApp's are recommended to leverage the registry to ensure they use the latest `TeleporterMessenger` version available. Another recommendation standard is to have a single canonical `TeleporterRegistry` for each Lux L1, and unlike the `TeleporterMessenger` contract, the registry does not need to be deployed to the same address on every chain. This means the registry does not need a Nick's method deployment, and can be at different contract addresses on different chains.

For more information on the registry and how to integrate with ICM contracts, see the [Upgradability doc](https://github.com/luxfi/icm-contracts/blob/main/contracts/teleporter/registry/README.md).

## Deploy TeleporterMessenger to an Lux L1

From the root of the repo, the TeleporterMessenger contract can be deployed by calling

```bash
./scripts/deploy_teleporter.sh --version <version> --rpc-url <url> [OPTIONS]
```

Required arguments:

- `--version <version>` Specify the release version to deploy. These will all be of the form `v1.X.0`. Each `TeleporterMessenger` version can only send and receive messages from the **same** `TeleporterMessenger` version on another chain. You can see a list of released versions at https://github.com/luxfi/icm-contracts/releases.
- `--rpc-url <url>` Specify the rpc url of the node to use.

Options:

- `--private-key <private_key>` Funds the deployer address with the account held by `<private_key>`

To ensure that `TeleporterMessenger` can be deployed to the same address on every EVM based chain, it uses [Nick's Method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c) to deploy from a static deployer address. ICM Contracts cost exactly `10eth` in the Lux L1's native gas token to deploy, which must be sent to the deployer address.

`deploy_teleporter.sh` will send the necessary native tokens to the deployer address if it is provided with a private key for an account with sufficient funds. Alternatively, the deployer address can be funded externally. The deployer address for each version can be found by looking up the appropriate version at https://github.com/luxfi/icm-contracts/releases and downloading `TeleporterMessenger_Deployer_Address_<VERSION>.txt`.

Alternatively for new Lux L1s, the `TeleporterMessenger` contract can be directly included in the genesis file as documented [here](https://github.com/luxfi/icm-contracts/blob/main/contracts/teleporter/README.md#teleporter-messenger-contract-deployment).

## Deploy TeleporterRegistry to an Lux L1

There should only be one canonical `TeleporterRegistry` deployed for each chain, but if one does not exist, it is recommended to deploy the registry so ICM contracts can always use the most recent `TeleporterMessenger` version available. The registry does not need to be deployed to the same address on every chain, and therefore does not need a Nick's method transaction. To deploy, run the following command from the root of the repository:

```bash
./scripts/deploy_registry.sh --version <version> --rpc-url <url> --private-key <private_key> [OPTIONS]
```

Required arguments:

- `--version <version>` Specify the release version to deploy. These will all be of the form `v1.X.0`.
- `--rpc-url <url>` Specify the rpc url of the node to use.
- `--private-key <private_key>` Funds the deployer address with the account held by `<private_key>`

`deploy_registry.sh` will deploy a new `TeleporterRegistry` contract for the intended release version, and will also have the corresponding `TeleporterMessenger` contract registered as the initial protocol version.

## Verify a Deployment of TeleporterMessenger

`TeleporterMessenger` can be verified on L1s using sourcify. `v1.0.0` of this repository must be checked out in order to match the source code properly.

```bash
git checkout v1.0.0
git submodule update --init --recursive
cd contracts

forge verify-contract 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf \
 src/teleporter/TeleporterMessenger.sol:TeleporterMessenger \
 --chain-id <YOUR_CHAIN_ID> \
 --rpc-url <YOUR_RPC_URL>    \
 --verifier sourcify \
 --compiler-version v0.8.18+commit.87f61d96 \
 --num-of-optimizations 200 \
```

# Upgradeability (/docs/cross-chain/icm-contracts/upgradeability)

---
title: "Upgradeability"
description: "The TeleporterMessenger contract is non-upgradable. However, there could still be new versions of TeleporterMessenger contracts needed to be deployed in the future."
edit_url: https://github.com/luxfi/teleporter/edit/main/contracts/teleporter/registry/README.md
---

# TeleporterMessenger Contracts Upgradability

## Overview

The `TeleporterMessenger` contract is non-upgradable, once a version of the contract is deployed it cannot be changed. This is with the intention of preventing any changes to the deployed contract that could potentially introduce bugs or vulnerabilities.

However, there could still be new versions of `TeleporterMessenger` contracts needed to be deployed in the future. `TeleporterRegistry` provides applications that use a `TeleporterMessenger` instance a minimal step process to integrate with new versions of `TeleporterMessenger`.

The `TeleporterRegistry` maintains a mapping of `TeleporterMessenger` contract versions to their addresses. When a new `TeleporterMessenger` version is deployed, its address can be added to the `TeleporterRegistry`. The `TeleporterRegistry` can only be updated through an ICM off-chain message that meets the following requirements:

- `sourceChainAddress` must match `VALIDATORS_SOURCE_ADDRESS = address(0)`
  - The zero address can only be set as the source chain address by an ICM off-chain message, and cannot be set by an on-chain ICM message.
- `sourceBlockchainID` must match the blockchain ID that the registry is deployed on
- `destinationBlockchainID` must match the blockchain ID that the registry is deployed on
- `destinationAddress` must match the address of the registry

In the `TeleporterRegistry` contract, the `latestVersion` state variable returns the highest version number that has been registered in the registry. The `getLatestTeleporter` function returns the `ITeleporterMessenger` that is registered with the corresponding version.

## Design

- `TeleporterRegistry` is deployed on each blockchain that needs to keep track of `TeleporterMessenger` contract versions.
- The registry's contract address on each blockchain does not need to be the same, and does not require a Nick's method transaction for deployment.
- Each registry's mapping of version to contract address is independent of registries on other blockchains, and chains can decide on their own registry mapping entries.
- Each blockchain should only have one canonical `TeleporterRegistry` contract.
- `TeleporterRegistry` contract can be initialized through a list of initial registry entries, which are `TeleporterMessenger` contract versions and their addresses.
- The registry keeps track of a mapping of `TeleporterMessenger` contract versions to their addresses, and vice versa, a mapping of `TeleporterMessenger` contract addresses to their versions.
- Version zero is an invalid version, and is used to indicate that a `TeleporterMessenger` contract has not been registered yet.
- Once a version number is registered in the registry, it cannot be changed, but a previous registered protocol address can be added to the registry with a new version. This is especially important in the case of a rollback to a previous `TeleporterMessenger` version, in which case the previous `TeleporterMessenger` contract address would need to be registered with a new version to the registry.

## Integrating `TeleporterRegistryApp` into a dApp

<div align="center">
  <img src="https://raw.githubusercontent.com/luxfi/teleporter/main/contracts/teleporter/registry/upgrade-uml.png" /> alt="Upgrade UML diagram"/>
</div>

[TeleporterRegistryApp](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/registry/TeleporterRegistryApp.sol) is an abstract contract that helps integrate the `TeleporterRegistry` into ICM contracts. To support upgradeable contracts, there is also a corresponding `TeleporterRegistryAppUpgradeable` contract that is upgrade compatible. By inheriting from `TeleporterRegistryApp`, dApps get:

- Ability to send ICM messages through the latest version of the `TeleporterMessenger` contract registered in the Teleporter registry. (The dApp can also override this to use a specific version of the `TeleporterMessenger` contract.)
- `minTeleporterVersion` management that allows the dApp to specify the minimum `TeleporterMessenger` version that can send messages to the dApp.
- Access controlled utility to update the `minTeleporterVersion`
- Access controlled utility to pause/unpause interaction with specific `TeleporterMessenger` addresses.

To integrate `TeleporterRegistryApp` with a dApp, pass in the Teleporter registry address inside the constructor. For upgradeable contracts `TeleporterRegistryAppUpgradeable` can be inherited, and the derived contract's `initializer` function should call either `__TeleporterRegistryApp_init` or `__TeleporterRegistryApp_init_unchained` An example dApp looks like:

```solidity
// An example dApp that integrates with the Teleporter registry
// to send/receive ICM messages.
contract ExampleApp is
    TeleporterRegistryApp
{
    ...
    // Constructor passes in the Teleporter registry address
    // to the TeleporterRegistryApp contract.
    constructor(
        address teleporterRegistryAddress,
        uint256 minTeleporterVersion
    ) TeleporterRegistryApp(teleporterRegistryAddress, minTeleporterVersion) {
        currentBlockchainID = IWarpMessenger(WARP_PRECOMPILE_ADDRESS)
            .getBlockchainID();
    }
    ...
    // Handles receiving ICM messages,
    // and also checks that the sender is a valid TeleporterMessenger contract.
    function _receiveTeleporterMessage(
        bytes32 sourceBlockchainID,
        address originSenderAddress,
        bytes memory message
    ) internal override {
        // implementation
    }

    // Implements the access control checks for the dApp's interaction with TeleporterMessenger versions.
    function _checkTeleporterRegistryAppAccess() internal view virtual override {
        //implementation
    }

}
```

### Checking TeleporterRegistryApp access

To prevent anyone from calling the dApp's `updateMinTeleporterVersion`, which would disallow messages from old `TeleporterMessenger` versions from being received, this function should be safeguarded with access controls. All contracts deriving from `TeleporterRegistryApp` will need to implement `TeleporterRegistryApp._checkTeleporterRegistryAppAccess`. For example, [TeleporterRegistryOwnableApp](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/registry/TeleporterRegistryOwnableApp.sol) is an abstract contract that inherits `TeleporterRegistryApp`, and implements `_checkTeleporterRegistryAppAccess` to check whether the caller is the owner. There is also a corresponding `TeleporterRegistryOwnableAppUpgradeable` contract that is upgrade compatible.

```solidity
    function _checkTeleporterRegistryAppAccess() internal view virtual override {
        _checkOwner();
    }
```

Another example would be a dApp that has different roles and priveleges. `_checkTeleporterRegistryAppAccess` can be implemented to check whether the caller is a specific role.

```solidity
    function _checkTeleporterRegistryAppAccess() internal view virtual override {
        require(
            hasRole(TELEPORTER_REGISTRY_APP_ADMIN, _msgSender()),
            "TeleporterRegistryApp: caller does not have access"
        );
    }
```

### Sending with specific TeleporterMessenger version

For sending messages with the Teleporter registry, dApps should use `TeleporterRegistryApp._getTeleporterMessenger`. This function by default extends `TeleporterRegistry.getLatestTeleporter`, using the latest version, and adds an extra check on whether the latest `TeleporterMessenger` address is paused. If the dApp wants to send a message through a specific `TeleporterMessenger` version, it can override `_getTeleporterMessenger()` to use the specific `TeleporterMessenger` version with `TeleporterRegistry.getTeleporterFromVersion`.

The `TeleporterRegistryApp._sendTeleporterMessage` function makes sending ICM messages easier. The function uses `_getTeleporterMessenger` to get the sending `TeleporterMessenger` version, pays for `TeleporterMessenger` fees from the dApp's balance, and sends the cross chain message.

Using latest version:

```solidity
        ITeleporterMessenger teleporterMessenger = _getTeleporterMessenger();
```

Using specific version:

```solidity
        // Override _getTeleporterMessenger to use specific version.
        function _getTeleporterMessenger() internal view override returns (ITeleporterMessenger) {
            ITeleporterMessenger teleporter = teleporterRegistry
                .getTeleporterFromVersion($VERSION);
            require(
                !pausedTeleporterAddresses[address(teleporter)],
                "TeleporterRegistryApp: Teleporter sending version paused"
            );

            return teleporter;
        }

        ITeleporterMessenger teleporterMessenger = _getTeleporterMessenger();
```

### Receiving from specific TeleporterMessenger versions

`TeleporterRegistryApp` also provides an initial implementation of [ITeleporterReceiver.receiveTeleporterMessage](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/ITeleporterReceiver.sol) that ensures `_msgSender` is a `TeleporterMessenger` contract with a version greater than or equal to `minTeleporterVersion`. This supports the case where a dApp wants to use a new version of the `TeleporterMessenger` contract, but still wants to be able to receive messages from the old `TeleporterMessenger` contract.The dApp can override `_receiveTeleporterMessage` to implement its own logic for receiving messages from `TeleporterMessenger` contracts.

## Managing a TeleporterRegistryApp dApp

dApps that implement `TeleporterRegistryApp` automatically use the latest `TeleporterMessenger` version registered with the `TeleporterRegistry`. Interaction with underlying `TeleporterMessenger` versions can be managed by setting the minimum `TeleporterMessenger` version, and pausing and unpausing specific versions.

The following sections include example `cast send` commands for issuing transactions that call contract functions. See the [Foundry Book](https://book.getfoundry.sh/reference/cast/cast-send) for details on how to issue transactions using common wallet options.

### Managing the Minimum TeleporterMessenger version

The `TeleporterRegistryApp` contract constructor saves the Teleporter registry in a state variable used by the inheriting dApp contract, and initializes a `minTeleporterVersion` to the highest `TeleporterMessenger` version registered in `TeleporterRegistry`. `minTeleporterVersion` is used to allow dApp's to specify the `TeleporterMessenger` versions allowed to interact with it.

#### Updating `minTeleporterVersion`

The `TeleporterRegistryApp.updateMinTeleporterVersion` function updates the `minTeleporterVersion` used to check which `TeleporterMessenger` versions can be used for sending and receiving messages. **Once the `minTeleporterVersion` is increased, any undelivered messages sent by other chains using older versions of `TeleporterMessenger` will never be able to be received**. The `updateMinTeleporterVersion` function can only be called with a version greater than the current `minTeleporterVersion` and less than `latestVersion` in the Teleporter registry.

> Example: Update the minimum TeleporterMessenger version to 2
>
> ```bash
> cast send <DAPP_ADDRESS> "updateMinTeleporterVersion(uint256)" 2
> ```

### Pausing TeleporterMessenger version interactions

dApps that inherit from `TeleporterRegistryApp` can pause `TeleporterMessenger` interactions by calling `TeleporterRegistryApp.pauseTeleporterAddress`. This function prevents the dApp contract from interacting with the paused `TeleporterMessenger` address when sending or receiving ICM messages.

`pauseTeleporterAddress` can only be called by addresses that passes the dApp's `TeleporterRegistryApp._checkTeleporterRegistryAppAccess` check.

The `TeleporterMessenger` address corresponding to a `TeleporterMessenger` version can be fetched from the registry with `TeleporterRegistry.getAddressFromVersion`

> Example: Pause TeleporterMessenger version 3
>
> ```bash
> versionThreeAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" 3)
> cast send <DAPP_ADDRESS> "pauseTeleporterAddress(address)" $versionThreeAddress
> ```

#### Pause all TeleporterMessenger interactions

To pause all `TeleporterMessenger` interactions, `TeleporterRegistryApp.pauseTeleporterAddress` must be called for every `TeleporterMessenger` version from the `minTeleporterVersion` to the latest `TeleporterMessenger` version registered in `TeleporterRegistry`. Note that there may be gaps in `TeleporterMessenger` versions registered with `TeleporterRegistry`, but they will always be in increasing order. The latest `TeleporterMessenger` version can be obtained by inspecting the public variable `TeleporterRegistry.latestVersion`. The `minTeleporterVersion` can be obtained by calling `TeleporterRegistryApp.getMinTeleporterVersion`.

> Example: Pause all registered TeleporterMessenger versions
>
> ```bash
> # Fetch the minimum TeleporterMessenger version
> minVersion=$(cast call <DAPP_ADDRESS> "getMinTeleporterVersion()(uint256)")
>
> # Fetch the latest registered version
> latestVersion=$(cast call <REGISTRY_ADDRESS> "latestVersion()(uint256)")
>
> # Pause all registered versions
> for ((version=minVersion; version<=latestVersion; version++))
> do
>  # Fetch the version address if it's registered
>  versionAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" $version)
>
>  if [ $? -eq 0 ]; then
>    # If cast call is successful, proceed to cast send
>    cast send <DAPP_ADDRESS> "pauseTeleporterAddress(address)" $versionAddress
>  else
>    # If cast call fails, print an error message and skip to the next iteration
>    echo "Version $version not registered. Skipping."
>  fi
> done
> ```

#### Unpausing TeleporterMessenger version interactions

As with pausing, dApps can unpause `TeleporterMessenger` interactions by calling `TeleporterRegistryApp.unpauseTeleporterAddress`. This unpause function allows receiving `TeleporterMessenger` message from the unpaused `TeleporterMessenger` address, and also enables the sending of messages through the unpaused `TeleporterMessenger` address in `_getTeleporterMessenger()`. Unpausing is also only allowed by addresses passing the dApp's `_checkTeleporterRegistryAppAccess` check.

Note that receiving `TeleporterMessenger` messages is still governed by the `minTeleporterVersion` check, so even if a `TeleporterMessenger` address is unpaused, the dApp will not receive messages from the unpaused `TeleporterMessenger` address if the `TeleporterMessenger` version is less than `minTeleporterVersion`.

> Example: Unpause TeleporterMessenger version 3
>
> ```bash
> versionThreeAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" 3)
> cast send <DAPP_ADDRESS> "unpauseTeleporterAddress(address)" $versionThreeAddress
> ```

# What is ICM? (/docs/cross-chain/avalanche-warp-messaging/overview)

---
title: What is ICM?
description: Learn about Lux Interchain Messaging, a protocol for cross-chain communication.
---

Lux Interchain Messaging (ICM) enables native cross-Lux L1 communication and allows [Virtual Machine (VM)](/docs/primary-network/virtual-machines) developers to implement arbitrary communication protocols between any two Lux L1s.

## Use Cases

Use cases for ICM may include but is not limited to:

- Oracle Networks: Connecting an Lux L1 to an oracle network is a costly process. ICM makes it easy for oracle networks to broadcast their data from their origin chain to other Lux L1s.
- Token transfers between Lux L1s
- State Sharding between multiple Lux L1s

Elements of Cross-Lux L1 Communication[​](#elements-of-cross-lux-l1-communication "Direct link to heading")
-----------------------------------------------------------------------------------------------------------

The communication consists of the following four steps:

![image showing four steps of cross-Lux L1 communication: Signing, aggregation, Delivery and Verification](/images/warp1.png)

### Signing Messages on the Origin Lux L1[​](#signing-messages-on-the-origin-lux-l1 "Direct link to heading")

ICM is a low-level messaging protocol. Any type of data encoded in an array of bytes can be included in the message sent to another Lux L1. ICM uses the [BLS signature scheme](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html), which allows message recipients to verify the authenticity of these messages. Therefore, every validator on the Lux network holds a BLS key pair, consisting of a private key for signing messages and a public key that others can use to verify the signature.

### Signature Aggregation on the Origin Lux L1[​](#signature-aggregation-on-the-origin-lux-l1 "Direct link to heading")

If the validator set of an Lux L1 is very large, this would result in the Lux L1's validators sending many signatures between them. One of the powerful features of BLS is the ability to aggregate many signatures of different signers in a single multi-signature. Therefore, validators of one Lux L1 can now individually sign a message and these signatures are then aggregated into a short multi-signature that can be quickly verified.

### Delivery of Messages to the Destination Lux L1[​](#delivery-of-messages-to-the-destination-lux-l1 "Direct link to heading")

The messages do not pass through a central protocol or trusted entity, and there is no record of messages sent between Lux L1s on the primary network. This avoids a bottleneck in Lux L1-to-Lux L1 communication, and non-public Lux L1s can communicate privately.

It is up to the Lux L1s and their users to determine how they want to transport data from the validators of the origin Lux L1 to the validators of the destination Lux L1 and what guarantees they want to provide for the transport.

### Verification of Messages in the Destination Lux L1[​](#verification-of-messages-in-the-destination-lux-l1 "Direct link to heading")

When an Lux L1 wants to process another Lux L1's message, it will look up both BLS Public Keys and stake of the origin Lux L1. The authenticity of the message can be verified using these public keys and the signature.

The combined weight of the validators that must be part of the BLS multi-signature to be considered valid can be set according to the individual requirements of each Lux L1-to-Lux L1 communication. Lux L1 A may accept messages from Lux L1 B that are signed by at least 70% of stake. Messages from Lux L1 C are only accepted if they have been signed by validators that account for 90% of the stake.

Since both the public keys and stake weights of all validators are recorded on the primary network's P-chain, they are readily accessible to any virtual machine run by the validators. Therefore, the Lux L1s do not need to communicate with each other about changes in their respective sets of validators, but can simply rely on the latest information on the Platform-Chain. Therefore, ICM introduces no additional trust assumption other than that the validators of the origin Lux L1 are participating honestly.

Reference Implementation[​](#reference-implementation "Direct link to heading")
-------------------------------------------------------------------------------

A Proof-of-Concept VM called [XSVM](https://github.com/luxfi/xsvm) was created to demonstrate the power of ICM. XSVM enables simple ICM transfers between any two Lux L1s if run out-of-the-box.


# cli info (/docs/lux-l1s/deploy-a-lux-l1/cli_structure)

---
title: cli info
description: cli flags and stuff
---
<a id="lux-blockchain"></a>
## lux blockchain

The blockchain command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the blockchain create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the blockchain deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

**Usage:**
```bash
lux blockchain [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#lux-blockchain-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the Platform-Chain.

This command currently only works on Blockchains deployed to either the Testnet
Testnet or Mainnet.
- [`changeOwner`](#lux-blockchain-changeowner): The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.
- [`changeWeight`](#lux-blockchain-changeweight): The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.
- [`configure`](#lux-blockchain-configure): LuxGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the LuxGo node 
configuration itself. This command allows you to set all those files.
- [`create`](#lux-blockchain-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#lux-blockchain-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#lux-blockchain-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Testnet Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Lux-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Testnet, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
lux network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Testnet or Mainnet.
- [`describe`](#lux-blockchain-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#lux-blockchain-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#lux-blockchain-import): Import blockchain configurations into lux-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#lux-blockchain-join): The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --luxgo-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Testnet Testnet and Mainnet.
- [`list`](#lux-blockchain-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#lux-blockchain-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#lux-blockchain-removevalidator): The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#lux-blockchain-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#lux-blockchain-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#lux-blockchain-validators): The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.
- [`vmid`](#lux-blockchain-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help help             for blockchain
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the Platform-Chain.

This command currently only works on Blockchains deployed to either the Testnet
Testnet or Mainnet.

**Usage:**
```bash
lux blockchain addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--balance uint                            set the LUX balance of the validator that will be used for continuous fee on Platform-Chain
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string          set the BLS proof of possession of the validator to add
--bls-public-key string                   set the BLS public key of the validator to add
--cluster string                          operate on the given cluster
--create-local-validator create           additional local validator and add it to existing running local node
--default-duration                        (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                      (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for testnet & mainnet, 30 seconds later for devnet)
--default-validator-params                (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                   (PoS only) delegation fee (in bips) (default 100)
--devnet operate                          on a devnet network
--disable-owner string                    Platform-Chain address that will able to disable the validator with a Platform-Chain transaction
--endpoint string                         use the given endpoint for network operations
-e, --ewoq use                            ewoq key [testnet/devnet only]
-f, --testnet testnet                        operate on testnet (alias to testnet
-h, --help help                           for addValidator
-k, --key string                          select the key to use [testnet/devnet only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    gather node id/bls from publicly available luxgo apis on the given endpoint
--node-id string                          node-id of the validator to add
--output-tx-path string                   (for Subnets, not L1s) file path of the add validator tx
--partial-sync set                        primary network partial sync for new validators (default true)
--remaining-balance-owner string          Platform-Chain address that will receive any leftover LUX from the validator when it is removed from Subnet
--rpc string                              connect to validator manager at the given rpc endpoint
--stake-amount uint                       (PoS only) amount of tokens to stake
--staking-period duration                 how long this validator will be staking
--start-time string                       (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings                (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet testnet                        operate on testnet (alias to testnet)
--wait-for-tx-acceptance                  (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                             set the staking weight of the validator to add (default 20)
--config string                           config file (default is $HOME/.lux-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="lux-blockchain-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.

**Usage:**
```bash
lux blockchain changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--cluster string              operate on the given cluster
--control-keys strings        addresses that may make subnet changes
--devnet operate              on a devnet network
--endpoint string             use the given endpoint for network operations
-e, --ewoq use                ewoq key [testnet/devnet]
-f, --testnet testnet            operate on testnet (alias to testnet
-h, --help help               for changeOwner
-k, --key string              select the key to use [testnet/devnet]
-g, --ledger use              ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings        use the given ledger addresses
-l, --local operate           on a local network
-m, --mainnet operate         on mainnet
--output-tx-path string       file path of the transfer subnet ownership tx
-s, --same-control-key use    the fee-paying key as control key
--subnet-auth-keys strings    control keys that will be used to authenticate transfer subnet ownership tx
-t, --testnet testnet            operate on testnet (alias to testnet)
--threshold uint32            required number of control key signatures to make subnet changes
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="lux-blockchain-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.

**Usage:**
```bash
lux blockchain changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-e, --ewoq use              ewoq key [testnet/devnet only]
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for changeWeight
-k, --key string            select the key to use [testnet/devnet only]
-g, --ledger use            ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings      use the given ledger addresses
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node-id of the validator
-t, --testnet testnet          operate on testnet (alias to testnet)
--weight uint               set the new staking weight of the validator (default 20)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-configure"></a>
### configure

LuxGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the LuxGo node 
configuration itself. This command allows you to set all those files.

**Usage:**
```bash
lux blockchain configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help help                   for configure
--node-config string              path to luxgo node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.lux-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="lux-blockchain-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
lux blockchain create [subcommand] [flags]
```

**Flags:**

```bash
--custom use                        a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug enable                      blockchain debugging (default true)
--evm use                           the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults deprecation          notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token use            a gas token from another blockchain
-f, --force overwrite               the existing configuration if one exists
--from-github-repo generate         custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help help                     for create
--icm interoperate                  with other blockchains using ICM
--icm-registry-at-genesis setup     ICM registry smart contract on genesis [experimental]
--latest use                        latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release use                   latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults use           default production settings for your blockchain
--proof-of-authority use            proof of authority(PoA) for validator management
--proof-of-stake use                proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign set                     to false if creating non-sovereign blockchain (default true)
--teleporter interoperate           with other blockchains using ICM
--test-defaults use                 default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp generate                     a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check skip            check for new versions
```

<a id="lux-blockchain-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
lux blockchain delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for delete
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration locally, to Testnet Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Lux-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Testnet, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
lux network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Testnet or Mainnet.

**Usage:**
```bash
lux blockchain deploy [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow                 the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings                   endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string                          log level to use with signature aggregator (default "Off")
--luxgo-path string                              use this luxgo binary path
--luxgo-version string                           use this version of luxgo (ex: v1.17.12) (default "latest-prerelease")
--balance float                                        set the LUX balance of each bootstrap validator that will be used for continuous fee on Platform-Chain (default 0.1)
--blockchain-genesis-key use                           genesis allocated key to fund validator manager initialization
--blockchain-key string                                CLI stored key to use to fund validator manager initialization
--blockchain-private-key string                        private key to use to fund validator manager initialization
--bootstrap-endpoints strings                          take validator node info from the given endpoints
--bootstrap-filepath string                            JSON file path that provides details about bootstrap validators, leave Node-ID and BLS values empty if using --generate-node-id=true
--cchain-funding-key string                            key to be used to fund relayer account on cchain
--cchain-icm-key string                                key to be used to pay for ICM deploys on LUExchange-Chain
--change-owner-address string                          address that will receive change if node is no longer L1 validator
--cluster string                                       operate on the given cluster
--control-keys strings                                 addresses that may make subnet changes
--convert-only avoid                                   node track, restart and poa manager setup
--devnet operate                                       on a devnet network
--endpoint string                                      use the given endpoint for network operations
-e, --ewoq use                                         ewoq key [testnet/devnet deploy only]
-f, --testnet testnet                                     operate on testnet (alias to testnet
--generate-node-id whether                             to create new node id for bootstrap validators (Node-ID and BLS values in bootstrap JSON file will be overridden if --bootstrap-filepath flag is used)
-h, --help help                                        for deploy
--icm-key string                                       key to be used to pay for ICM deploys (default "cli-teleporter-deployer")
--icm-version string                                   ICM version to deploy (default "latest")
-k, --key string                                       select the key to use [testnet/devnet deploy only]
-g, --ledger use                                       ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings                                 use the given ledger addresses
-l, --local operate                                    on a local network
-m, --mainnet operate                                  on mainnet
--mainnet-chain-id uint32                              use different ChainID for mainnet deployment
--noicm skip                                           automatic ICM deploy
--num-bootstrap-validators int                         (only if --generate-node-id is true) number of bootstrap validators to set up in sovereign L1 validator)
--num-local-nodes int                                  number of nodes to be created on local machine
--num-nodes uint32                                     number of nodes to be created on local network deploy (default 2)
--output-tx-path string                                file path of the blockchain creation tx
--partial-sync set                                     primary network partial sync for new validators (default true)
--pos-maximum-stake-amount uint                        maximum stake amount (default 1000)
--pos-maximum-stake-multiplier uint8                   maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16                    minimum delegation fee (default 1)
--pos-minimum-stake-amount uint                        minimum stake amount (default 1)
--pos-minimum-stake-duration uint                      minimum stake duration (default 100)
--pos-weight-to-value-factor uint                      weight to value factor (default 1)
--relay-cchain relay                                   LUExchange-Chain as source and destination (default true)
--relayer-allow-private-ips allow                      relayer to connec to private ips (default true)
--relayer-amount float                                 automatically fund relayer fee payments with the given amount
--relayer-key string                                   key to be used by default both for rewards and to pay fees
--relayer-log-level string                             log level to be used for relayer logs (default "info")
--relayer-path string                                  relayer binary to use
--relayer-version string                               relayer version to deploy (default "latest-prerelease")
-s, --same-control-key use                             the fee-paying key as control key
--skip-icm-deploy skip                                 automatic ICM deploy
--skip-local-teleporter skip                           automatic ICM deploy on local networks [to be deprecated]
--skip-relayer skip                                    relayer deploy
--skip-teleporter-deploy skip                          automatic ICM deploy
--subnet-auth-keys strings                             control keys that will be used to authenticate chain creation
-u, --subnet-id string                                 do not create a subnet, deploy the blockchain into the given subnet id
--subnet-only only                                     create a subnet
--teleporter-messenger-contract-address-path string    path to an ICM Messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an ICM Messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an ICM Messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an ICM Registry bytecode file
--teleporter-version string                            ICM version to deploy (default "latest")
-t, --testnet testnet                                     operate on testnet (alias to testnet)
--threshold uint32                                     required number of control key signatures to make subnet changes
--use-local-machine use                                local machine as a blockchain validator
--config string                                        config file (default is $HOME/.lux-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check skip                               check for new versions
```

<a id="lux-blockchain-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
lux blockchain describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis Print         the genesis to the console directly instead of the summary
-h, --help help             for describe
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
lux blockchain export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help help                    for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.lux-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check skip           check for new versions
```

<a id="lux-blockchain-import"></a>
### import

Import blockchain configurations into lux-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
lux blockchain import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#lux-blockchain-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#lux-blockchain-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help help             for import
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
lux blockchain import file [subcommand] [flags]
```

**Flags:**

```bash
--branch string             the repo branch to use if downloading a new repo
-f, --force overwrite       the existing configuration if one exists
-h, --help help             for file
--repo string               the repo to import (ex: luxfi/lux-plugins-core) or url to download the repo from
--subnet string             the subnet configuration to import from the provided repo
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
lux blockchain import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string      the blockchain ID
--cluster string            operate on the given cluster
--custom use                a custom VM template
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
--evm import                a subnet-evm
--force overwrite           the existing configuration if one exists
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for public
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-url string           [optional] URL of an already running subnet validator
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-join"></a>
### join

The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --luxgo-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Testnet Testnet and Mainnet.

**Usage:**
```bash
lux blockchain join [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-config string    file path of the luxgo config file
--cluster string               operate on the given cluster
--data-dir string              path of luxgo's data dir directory
--devnet operate               on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write if               true, skip to prompt to overwrite the config file
-f, --testnet testnet             operate on testnet (alias to testnet
-h, --help help                for join
-k, --key string               select the key to use [testnet only]
-g, --ledger use               ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings         use the given ledger addresses
-l, --local operate            on a local network
-m, --mainnet operate          on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of luxgo's plugin directory
--print if                     true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet testnet             operate on testnet (alias to testnet)
--config string                config file (default is $HOME/.lux-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check skip       check for new versions
```

<a id="lux-blockchain-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
lux blockchain list [subcommand] [flags]
```

**Flags:**

```bash
--deployed show             additional deploy information
-h, --help help             for list
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
lux blockchain publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force If                   true, ignores if the subnet has been published in the past, and attempts a forced publish.
-h, --help help              for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Subnet description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-blockchain-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
lux blockchain removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                          operate on the given cluster
--devnet operate                          on a devnet network
--endpoint string                         use the given endpoint for network operations
--force force                             validator removal even if it's not getting rewarded
-f, --testnet testnet                        operate on testnet (alias to testnet
-h, --help help                           for removeValidator
-k, --key string                          select the key to use [testnet deploy only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    remove validator that responds to the given endpoint
--node-id string                          node-id of the validator
--output-tx-path string                   (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                              connect to validator manager at the given rpc endpoint
--subnet-auth-keys strings                (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
-t, --testnet testnet                        operate on testnet (alias to testnet)
--uptime uint                             validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                           config file (default is $HOME/.lux-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="lux-blockchain-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
lux blockchain stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for stats
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
lux blockchain upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#lux-blockchain-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Testnet Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --luxgo-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.lux.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#lux-blockchain-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#lux-blockchain-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#lux-blockchain-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#lux-blockchain-upgrade-print): Print the upgrade.json file content
- [`vm`](#lux-blockchain-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Testnet and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help help             for upgrade
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Testnet Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --luxgo-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.lux.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
lux blockchain upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-chain-config-dir string    luxgo's chain config file directory (default "/Users/owen.wahlgren/.luxgo/chains")
--config create                          upgrade config for future subnet deployments (same as generate)
--force If                               true, don't prompt for confirmation of timestamps in the past
--testnet testnet                              apply upgrade existing testnet deployment (alias for `testnet`)
-h, --help help                          for apply
--local local                            apply upgrade existing local deployment
--mainnet mainnet                        apply upgrade existing mainnet deployment
--print if                               true, print the manual config without prompting (for public networks only)
--testnet testnet                        apply upgrade existing testnet deployment (alias for `testnet`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check skip                 check for new versions
```

<a id="lux-blockchain-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
lux blockchain upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force If                   true, overwrite a possibly existing file without prompting
-h, --help help              for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-blockchain-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
lux blockchain upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for generate
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
lux blockchain upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help              for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-blockchain-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
lux blockchain upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for print
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Testnet and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
lux blockchain upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string             Upgrade to custom binary
--config upgrade            config for future subnet deployments
--testnet testnet                 upgrade existing testnet deployment (alias for `testnet`)
-h, --help help             for vm
--latest upgrade            to latest version
--local local               upgrade existing local deployment
--mainnet mainnet           upgrade existing mainnet deployment
--plugin-dir string         plugin directory to automatically upgrade VM
--print print               instructions for upgrading
--testnet testnet           upgrade existing testnet deployment (alias for `testnet`)
--version string            Upgrade to custom version
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.

**Usage:**
```bash
lux blockchain validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for validators
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-blockchain-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
lux blockchain vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for vmid
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-config"></a>
## lux config

Customize configuration for Lux-CLI

**Usage:**
```bash
lux config [subcommand] [flags]
```

**Subcommands:**

- [`authorize-cloud-access`](#lux-config-authorize-cloud-access): set preferences to authorize access to cloud resources
- [`metrics`](#lux-config-metrics): set user metrics collection preferences
- [`migrate`](#lux-config-migrate): migrate command migrates old ~/.lux-cli.json and ~/.lux-cli/config to /.lux-cli/config.json..
- [`snapshotsAutoSave`](#lux-config-snapshotsautosave): set user preference between auto saving local network snapshots or not
- [`update`](#lux-config-update): set user preference between update check or not

**Flags:**

```bash
-h, --help help             for config
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-config-authorize-cloud-access"></a>
### authorize-cloud-access

set preferences to authorize access to cloud resources

**Usage:**
```bash
lux config authorize-cloud-access [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for authorize-cloud-access
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-config-metrics"></a>
### metrics

set user metrics collection preferences

**Usage:**
```bash
lux config metrics [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for metrics
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-config-migrate"></a>
### migrate

migrate command migrates old ~/.lux-cli.json and ~/.lux-cli/config to /.lux-cli/config.json..

**Usage:**
```bash
lux config migrate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for migrate
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-config-snapshotsautosave"></a>
### snapshotsAutoSave

set user preference between auto saving local network snapshots or not

**Usage:**
```bash
lux config snapshotsAutoSave [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for snapshotsAutoSave
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-config-update"></a>
### update

set user preference between update check or not

**Usage:**
```bash
lux config update [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for update
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-contract"></a>
## lux contract

The contract command suite provides a collection of tools for deploying
and interacting with smart contracts.

**Usage:**
```bash
lux contract [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-contract-deploy): The contract command suite provides a collection of tools for deploying
smart contracts.
- [`initValidatorManager`](#lux-contract-initvalidatormanager): Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager

**Flags:**

```bash
-h, --help help             for contract
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-contract-deploy"></a>
### deploy

The contract command suite provides a collection of tools for deploying
smart contracts.

**Usage:**
```bash
lux contract deploy [subcommand] [flags]
```

**Subcommands:**

- [`erc20`](#lux-contract-deploy-erc20): Deploy an ERC20 token into a given Network and Blockchain

**Flags:**

```bash
-h, --help help             for deploy
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-contract-deploy-erc20"></a>
#### deploy erc20

Deploy an ERC20 token into a given Network and Blockchain

**Usage:**
```bash
lux contract deploy erc20 [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string         deploy the ERC20 contract into the given CLI blockchain
--blockchain-id string      deploy the ERC20 contract into the given blockchain ID/Alias
--c-chain deploy            the ERC20 contract into LUExchange-Chain
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
--funded string             set the funded address
--genesis-key use           genesis allocated key as contract deployer
-h, --help help             for erc20
--key string                CLI stored key to use as contract deployer
-l, --local operate         on a local network
--private-key string        private key to use as contract deployer
--rpc string                deploy the contract into the given rpc endpoint
--supply uint               set the token supply
--symbol string             set the token symbol
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-contract-initvalidatormanager"></a>
### initValidatorManager

Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager

**Usage:**
```bash
lux contract initValidatorManager [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--cluster string                          operate on the given cluster
--devnet operate                          on a devnet network
--endpoint string                         use the given endpoint for network operations
-f, --testnet testnet                        operate on testnet (alias to testnet
--genesis-key use                         genesis allocated key as contract deployer
-h, --help help                           for initValidatorManager
--key string                              CLI stored key to use as contract deployer
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--pos-maximum-stake-amount uint           (PoS only) maximum stake amount (default 1000)
--pos-maximum-stake-multiplier uint8      (PoS only )maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16       (PoS only) minimum delegation fee (default 1)
--pos-minimum-stake-amount uint           (PoS only) minimum stake amount (default 1)
--pos-minimum-stake-duration uint         (PoS only) minimum stake duration (default 100)
--pos-reward-calculator-address string    (PoS only) initialize the ValidatorManager with reward calculator address
--pos-weight-to-value-factor uint         (PoS only) weight to value factor (default 1)
--private-key string                      private key to use as contract deployer
--rpc string                              deploy the contract into the given rpc endpoint
-t, --testnet testnet                        operate on testnet (alias to testnet)
--config string                           config file (default is $HOME/.lux-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="lux-help"></a>
## lux help

Help provides help for any command in the application.
Simply type lux help [path to command] for full details.

**Usage:**
```bash
lux help [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for help
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-icm"></a>
## lux icm

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
lux icm [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-icm-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#lux-icm-sendmsg): Sends and wait reception for a ICM msg between two subnets.

**Flags:**

```bash
-h, --help help             for icm
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-icm-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

**Usage:**
```bash
lux icm deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain deploy                            ICM into LUExchange-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to LUExchange-Chain
--cluster string                            operate on the given cluster
--deploy-messenger deploy                   ICM Messenger (default true)
--deploy-registry deploy                    ICM Registry (default true)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy deploy              ICM Registry even if Messenger has already been deployed
-f, --testnet testnet                          operate on testnet (alias to testnet
--genesis-key use                           genesis allocated key to fund ICM deploy
-h, --help help                             for deploy
--include-cchain deploy                     ICM also to LUExchange-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local operate                         on a local network
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet testnet                          operate on testnet (alias to testnet)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="lux-icm-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two subnets.

**Usage:**
```bash
lux icm sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet testnet              operate on testnet (alias to testnet
--genesis-key use               genesis allocated key as message originator and to pay source blockchain fees
-h, --help help                 for sendMsg
--hex-encoded given             message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local operate             on a local network
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet testnet              operate on testnet (alias to testnet)
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="lux-ictt"></a>
## lux ictt

The ictt command suite provides tools to deploy and manage Interchain Token Transferrers.

**Usage:**
```bash
lux ictt [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-ictt-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help help             for ictt
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-ictt-deploy"></a>
### deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
lux ictt deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home set               the Transferrer's Home Chain into LUExchange-Chain
--c-chain-remote set             the Transferrer's Remote Chain into LUExchange-Chain
--cluster string                 operate on the given cluster
--deploy-erc20-home string       deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home deploy      a Transferrer Home for the Chain's Native Token
--deploy-native-remote deploy    a Transferrer Remote for the Chain's Native Token
--devnet operate                 on a devnet network
--endpoint string                use the given endpoint for network operations
-f, --testnet testnet               operate on testnet (alias to testnet
-h, --help help                  for deploy
--home-blockchain string         set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key use           genesis allocated key to deploy Transferrer Home
--home-key string                CLI stored key to use to deploy Transferrer Home
--home-private-key string        private key to use to deploy Transferrer Home
--home-rpc string                use the given RPC URL to connect to the home blockchain
-l, --local operate              on a local network
--remote-blockchain string       set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key use         genesis allocated key to deploy Transferrer Remote
--remote-key string              CLI stored key to use to deploy Transferrer Remote
--remote-private-key string      private key to use to deploy Transferrer Remote
--remote-rpc string              use the given RPC URL to connect to the remote blockchain
--remote-token-decimals uint8    use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin remove     the native minter precompile admin found on remote blockchain genesis
-t, --testnet testnet               operate on testnet (alias to testnet)
--use-home string                use the given Transferrer's Home Address
--version string                 tag/branch/commit of Lux Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                  config file (default is $HOME/.lux-cli/config.json)
--log-level string               log level for the application (default "ERROR")
--skip-update-check skip         check for new versions
```

<a id="lux-interchain"></a>
## lux interchain

The interchain command suite provides a collection of tools to
set and manage interoperability between blockchains.

**Usage:**
```bash
lux interchain [subcommand] [flags]
```

**Subcommands:**

- [`messenger`](#lux-interchain-messenger): The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.
- [`relayer`](#lux-interchain-relayer): The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.
- [`tokenTransferrer`](#lux-interchain-tokentransferrer): The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Flags:**

```bash
-h, --help help             for interchain
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-messenger"></a>
### messenger

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
lux interchain messenger [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-interchain-messenger-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#lux-interchain-messenger-sendmsg): Sends and wait reception for a ICM msg between two subnets.

**Flags:**

```bash
-h, --help help             for messenger
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-messenger-deploy"></a>
#### messenger deploy

Deploys ICM Messenger and Registry into a given L1.

**Usage:**
```bash
lux interchain messenger deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain deploy                            ICM into LUExchange-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to LUExchange-Chain
--cluster string                            operate on the given cluster
--deploy-messenger deploy                   ICM Messenger (default true)
--deploy-registry deploy                    ICM Registry (default true)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy deploy              ICM Registry even if Messenger has already been deployed
-f, --testnet testnet                          operate on testnet (alias to testnet
--genesis-key use                           genesis allocated key to fund ICM deploy
-h, --help help                             for deploy
--include-cchain deploy                     ICM also to LUExchange-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local operate                         on a local network
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet testnet                          operate on testnet (alias to testnet)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="lux-interchain-messenger-sendmsg"></a>
#### messenger sendMsg

Sends and wait reception for a ICM msg between two subnets.

**Usage:**
```bash
lux interchain messenger sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet testnet              operate on testnet (alias to testnet
--genesis-key use               genesis allocated key as message originator and to pay source blockchain fees
-h, --help help                 for sendMsg
--hex-encoded given             message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local operate             on a local network
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet testnet              operate on testnet (alias to testnet)
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="lux-interchain-relayer"></a>
### relayer

The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.

**Usage:**
```bash
lux interchain relayer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-interchain-relayer-deploy): Deploys an ICM Relayer for the given Network.
- [`logs`](#lux-interchain-relayer-logs): Shows pretty formatted AWM relayer logs
- [`start`](#lux-interchain-relayer-start): Starts AWM relayer on the specified network (Currently only for local network).
- [`stop`](#lux-interchain-relayer-stop): Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Flags:**

```bash
-h, --help help             for relayer
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-relayer-deploy"></a>
#### relayer deploy

Deploys an ICM Relayer for the given Network.

**Usage:**
```bash
lux interchain relayer deploy [subcommand] [flags]
```

**Flags:**

```bash
--allow-private-ips allow          relayer to connec to private ips (default true)
--amount float                     automatically fund l1s fee payments with the given amount
--bin-path string                  use the given relayer binary
--blockchain-funding-key string    key to be used to fund relayer account on all l1s
--blockchains strings              blockchains to relay as source and destination
--cchain relay                     LUExchange-Chain as source and destination
--cchain-amount float              automatically fund cchain fee payments with the given amount
--cchain-funding-key string        key to be used to fund relayer account on cchain
--cluster string                   operate on the given cluster
--devnet operate                   on a devnet network
--endpoint string                  use the given endpoint for network operations
-f, --testnet testnet                 operate on testnet (alias to testnet
-h, --help help                    for deploy
--key string                       key to be used by default both for rewards and to pay fees
-l, --local operate                on a local network
--log-level string                 log level to use for relayer logs
-t, --testnet testnet                 operate on testnet (alias to testnet)
--version string                   version to deploy (default "latest-prerelease")
--config string                    config file (default is $HOME/.lux-cli/config.json)
--skip-update-check skip           check for new versions
```

<a id="lux-interchain-relayer-logs"></a>
#### relayer logs

Shows pretty formatted AWM relayer logs

**Usage:**
```bash
lux interchain relayer logs [subcommand] [flags]
```

**Flags:**

```bash
--endpoint string           use the given endpoint for network operations
--first uint                output first N log lines
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for logs
--last uint                 output last N log lines
-l, --local operate         on a local network
--raw raw                   logs output
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-relayer-start"></a>
#### relayer start

Starts AWM relayer on the specified network (Currently only for local network).

**Usage:**
```bash
lux interchain relayer start [subcommand] [flags]
```

**Flags:**

```bash
--bin-path string           use the given relayer binary
--cluster string            operate on the given cluster
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for start
-l, --local operate         on a local network
-t, --testnet testnet          operate on testnet (alias to testnet)
--version string            version to use (default "latest-prerelease")
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-relayer-stop"></a>
#### relayer stop

Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Usage:**
```bash
lux interchain relayer stop [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for stop
-l, --local operate         on a local network
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-tokentransferrer"></a>
### tokenTransferrer

The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Usage:**
```bash
lux interchain tokenTransferrer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-interchain-tokentransferrer-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help help             for tokenTransferrer
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-interchain-tokentransferrer-deploy"></a>
#### tokenTransferrer deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
lux interchain tokenTransferrer deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home set               the Transferrer's Home Chain into LUExchange-Chain
--c-chain-remote set             the Transferrer's Remote Chain into LUExchange-Chain
--cluster string                 operate on the given cluster
--deploy-erc20-home string       deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home deploy      a Transferrer Home for the Chain's Native Token
--deploy-native-remote deploy    a Transferrer Remote for the Chain's Native Token
--devnet operate                 on a devnet network
--endpoint string                use the given endpoint for network operations
-f, --testnet testnet               operate on testnet (alias to testnet
-h, --help help                  for deploy
--home-blockchain string         set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key use           genesis allocated key to deploy Transferrer Home
--home-key string                CLI stored key to use to deploy Transferrer Home
--home-private-key string        private key to use to deploy Transferrer Home
--home-rpc string                use the given RPC URL to connect to the home blockchain
-l, --local operate              on a local network
--remote-blockchain string       set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key use         genesis allocated key to deploy Transferrer Remote
--remote-key string              CLI stored key to use to deploy Transferrer Remote
--remote-private-key string      private key to use to deploy Transferrer Remote
--remote-rpc string              use the given RPC URL to connect to the remote blockchain
--remote-token-decimals uint8    use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin remove     the native minter precompile admin found on remote blockchain genesis
-t, --testnet testnet               operate on testnet (alias to testnet)
--use-home string                use the given Transferrer's Home Address
--version string                 tag/branch/commit of Lux Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                  config file (default is $HOME/.lux-cli/config.json)
--log-level string               log level for the application (default "ERROR")
--skip-update-check skip         check for new versions
```

<a id="lux-key"></a>
## lux key

The key command suite provides a collection of tools for creating and managing
signing keys. You can use these keys to deploy Subnets to the Testnet Testnet,
but these keys are NOT suitable to use in production environments. DO NOT use
these keys on Mainnet.

To get started, use the key create command.

**Usage:**
```bash
lux key [subcommand] [flags]
```

**Subcommands:**

- [`create`](#lux-key-create): The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.
- [`delete`](#lux-key-delete): The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.
- [`export`](#lux-key-export): The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Lux-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.
- [`list`](#lux-key-list): The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.
- [`transfer`](#lux-key-transfer): The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Flags:**

```bash
-h, --help help             for key
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-key-create"></a>
### create

The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.

**Usage:**
```bash
lux key create [subcommand] [flags]
```

**Flags:**

```bash
--file string               import the key from an existing key file
-f, --force overwrite       an existing key with the same name
-h, --help help             for create
--skip-balances do          not query public network balances for an imported key
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-key-delete"></a>
### delete

The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.

**Usage:**
```bash
lux key delete [subcommand] [flags]
```

**Flags:**

```bash
-f, --force delete          the key without confirmation
-h, --help help             for delete
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-key-export"></a>
### export

The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Lux-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.

**Usage:**
```bash
lux key export [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for export
-o, --output string         write the key to the provided file path
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-key-list"></a>
### list

The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.

**Usage:**
```bash
lux key list [subcommand] [flags]
```

**Flags:**

```bash
-a, --all-networks list     all network addresses
--blockchains strings       blockchains to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-c, --cchain list           LUExchange-Chain addresses (default true)
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for list
--keys strings              list addresses for the given keys
-g, --ledger uints          list ledger addresses for the given indices (default [])
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--pchain list               Platform-Chain addresses (default true)
--subnets strings           subnets to show information about (p=p-chain, x=x-chain, c=c-chain, and subnet names) (default p,x,c)
-t, --testnet testnet          operate on testnet (alias to testnet)
--tokens strings            provide balance information for the given token contract addresses (Evm only) (default [Native])
--use-gwei use              gwei for EVM balances
-n, --use-nano-lux use     nano Lux for balances
--xchain list               Exchange-Chain addresses (default true)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-key-transfer"></a>
### transfer

The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Usage:**
```bash
lux key transfer [subcommand] [flags]
```

**Flags:**

```bash
-o, --amount float                          amount to send or receive (LUX or TOKEN units)
--c-chain-receiver receive                  at LUExchange-Chain
--c-chain-sender send                       from LUExchange-Chain
--cluster string                            operate on the given cluster
-a, --destination-addr string               destination address
--destination-key string                    key associated to a destination address
--destination-subnet string                 subnet where the funds will be sent (token transferrer experimental)
--destination-transferrer-address string    token transferrer address at the destination subnet (token transferrer experimental)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --testnet testnet                          operate on testnet (alias to testnet
-h, --help help                             for transfer
-k, --key string                            key associated to the sender or receiver address
-i, --ledger uint32                         ledger index associated to the sender or receiver address (default 32768)
-l, --local operate                         on a local network
-m, --mainnet operate                       on mainnet
--origin-subnet string                      subnet where the funds belong (token transferrer experimental)
--origin-transferrer-address string         token transferrer address at the origin subnet (token transferrer experimental)
--p-chain-receiver receive                  at Platform-Chain
--p-chain-sender send                       from Platform-Chain
--receiver-blockchain string                receive at the given CLI blockchain
--receiver-blockchain-id string             receive at the given blockchain ID/Alias
--sender-blockchain string                  send from the given CLI blockchain
--sender-blockchain-id string               send from the given blockchain ID/Alias
-t, --testnet testnet                          operate on testnet (alias to testnet)
--x-chain-receiver receive                  at Exchange-Chain
--x-chain-sender send                       from Exchange-Chain
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="lux-network"></a>
## lux network

The network command suite provides a collection of tools for managing local Subnet
deployments.

When you deploy a Subnet locally, it runs on a local, multi-node Lux network. The
subnet deploy command starts this network in the background. This command suite allows you
to shutdown, restart, and clear that network.

This network currently supports multiple, concurrently deployed Subnets.

**Usage:**
```bash
lux network [subcommand] [flags]
```

**Subcommands:**

- [`clean`](#lux-network-clean): The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.
- [`start`](#lux-network-start): The network start command starts a local, multi-node Lux network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.
- [`status`](#lux-network-status): The network status command prints whether or not a local Lux
network is running and some basic stats about the network.
- [`stop`](#lux-network-stop): The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Flags:**

```bash
-h, --help help             for network
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-network-clean"></a>
### clean

The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.

**Usage:**
```bash
lux network clean [subcommand] [flags]
```

**Flags:**

```bash
--hard Also                 clean downloaded luxgo and plugin binaries
-h, --help help             for clean
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-network-start"></a>
### start

The network start command starts a local, multi-node Lux network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.

**Usage:**
```bash
lux network start [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-path string       use this luxgo binary path
--luxgo-version string    use this version of luxgo (ex: v1.17.12) (default "latest-prerelease")
-h, --help help                 for start
--num-nodes uint32              number of nodes to be created on local network (default 2)
--relayer-path string           use this relayer binary path
--relayer-version string        use this relayer version (default "latest-prerelease")
--snapshot-name string          name of snapshot to use to start the network from (default "default-1654102509")
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="lux-network-status"></a>
### status

The network status command prints whether or not a local Lux
network is running and some basic stats about the network.

**Usage:**
```bash
lux network status [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for status
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-network-stop"></a>
### stop

The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Usage:**
```bash
lux network stop [subcommand] [flags]
```

**Flags:**

```bash
--dont-save do              not save snapshot, just stop the network
-h, --help help             for stop
--snapshot-name string      name of snapshot to use to save network state into (default "default-1654102509")
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node"></a>
## lux node

The node command suite provides a collection of tools for creating and maintaining 
validators on Lux Network.

To get started, use the node create command wizard to walk through the
configuration to make your node a primary validator on Lux public network. You can use the 
rest of the commands to maintain your node and make your node a Subnet Validator.

**Usage:**
```bash
lux node [subcommand] [flags]
```

**Subcommands:**

- [`addDashboard`](#lux-node-adddashboard): (ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.
- [`create`](#lux-node-create): (ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Lux Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running lux node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster
- [`destroy`](#lux-node-destroy): (ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.
- [`devnet`](#lux-node-devnet): (ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling lux node status `clusterName`
- [`export`](#lux-node-export): (ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.
- [`import`](#lux-node-import): (ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use lux-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by lux-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.
- [`list`](#lux-node-list): (ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.
- [`loadtest`](#lux-node-loadtest): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.
- [`local`](#lux-node-local): (ALPHA Warning) This command is currently in experimental mode.

The node local command suite provides a collection of commands related to local nodes
- [`refresh-ips`](#lux-node-refresh-ips): (ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.
- [`resize`](#lux-node-resize): (ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.
- [`scp`](#lux-node-scp): (ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ lux node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ lux node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ lux node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt
- [`ssh`](#lux-node-ssh): (ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.
- [`status`](#lux-node-status): (ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag
- [`sync`](#lux-node-sync): (ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling lux node status `clusterName` --blockchain `blockchainName`
- [`update`](#lux-node-update): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM config.

You can check the status after update by calling lux node status
- [`upgrade`](#lux-node-upgrade): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM version.

You can check the status after upgrade by calling lux node status
- [`validate`](#lux-node-validate): (ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling lux node status `clusterName`
- [`whitelist`](#lux-node-whitelist): (ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Flags:**

```bash
-h, --help help             for node
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-adddashboard"></a>
### addDashboard

(ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.

**Usage:**
```bash
lux node addDashboard [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string    path to additional grafana dashboard json file
-h, --help help                   for addDashboard
--subnet string                   subnet that the dasbhoard is intended for (if any)
--config string                   config file (default is $HOME/.lux-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="lux-node-create"></a>
### create

(ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Lux Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running lux node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster

**Usage:**
```bash
lux node create [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                      path to additional grafana dashboard json file
--alternative-key-pair-name string                  key pair name to use if default one generates conflicts
--authorize-access authorize                        CLI to create cloud resources
--auto-replace-keypair automatically                replaces key pair to access node if previous key pair is not found
--luxgo-version-from-subnet string            install latest luxgo version, that is compatible with the given subnet, on node/s
--aws create                                        node/s in AWS cloud
--aws-profile string                                aws profile to use (default "default")
--aws-volume-iops int                               AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                               AWS volume size in GB (default 1000)
--aws-volume-throughput int                         AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                            AWS volume type (default "gp3")
--bootstrap-ids stringArray                         nodeIDs of bootstrap nodes
--bootstrap-ips stringArray                         IP:port pairs of bootstrap nodes
--cluster string                                    operate on the given cluster
--custom-luxgo-version string                 install given luxgo version on node/s
--devnet operate                                    on a devnet network
--enable-monitoring set                             up Prometheus monitoring for created nodes. This option creates a separate monitoring cloud instance and incures additional cost
--endpoint string                                   use the given endpoint for network operations
-f, --testnet testnet                                  operate on testnet (alias to testnet
--gcp create                                        node/s in GCP cloud
--gcp-credentials string                            use given GCP credentials
--gcp-project string                                use given GCP project
--genesis string                                    path to genesis file
--grafana-pkg string                                use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help help                                     for create
--latest-luxgo-pre-release-version install    latest luxgo pre-release version on node/s
--latest-luxgo-version install                latest luxgo release version on node/s
-m, --mainnet operate                               on mainnet
--node-type string                                  cloud instance type. Use 'default' to use recommended default instance type
--num-apis ints                                     number of API nodes(nodes without stake) to create in the new Devnet
--num-validators ints                               number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--partial-sync primary                              network partial sync (default true)
--public-http-port allow                            public access to luxgo HTTP port
--region strings                                    create node(s) in given region(s). Use comma to separate multiple regions
--ssh-agent-identity string                         use given ssh identity(only for ssh agent). If not set, default will be used
-t, --testnet testnet                                  operate on testnet (alias to testnet)
--upgrade string                                    path to upgrade file
--use-ssh-agent use                                 ssh agent(ex: Yubikey) for ssh auth
--use-static-ip attach                              static Public IP on cloud servers (default true)
--config string                                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                                  log level for the application (default "ERROR")
--skip-update-check skip                            check for new versions
```

<a id="lux-node-destroy"></a>
### destroy

(ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.

**Usage:**
```bash
lux node destroy [subcommand] [flags]
```

**Flags:**

```bash
--all destroy                    all existing clusters created by Lux CLI
--authorize-access authorize     CLI to release cloud resources
-y, --authorize-all authorize    all CLI requests
--authorize-remove authorize     CLI to remove all local files related to cloud nodes
--aws-profile string             aws profile to use (default "default")
-h, --help help                  for destroy
--config string                  config file (default is $HOME/.lux-cli/config.json)
--log-level string               log level for the application (default "ERROR")
--skip-update-check skip         check for new versions
```

<a id="lux-node-devnet"></a>
### devnet

(ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling lux node status `clusterName`

**Usage:**
```bash
lux node devnet [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-node-devnet-deploy): (ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.
- [`wiz`](#lux-node-devnet-wiz): (ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Flags:**

```bash
-h, --help help             for devnet
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-devnet-deploy"></a>
#### devnet deploy

(ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.

**Usage:**
```bash
lux node devnet deploy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for deploy
--no-checks do              not check for healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-only only          create a subnet
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-devnet-wiz"></a>
#### devnet wiz

(ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Usage:**
```bash
lux node devnet wiz [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                         path to additional grafana dashboard json file
--alternative-key-pair-name string                     key pair name to use if default one generates conflicts
--authorize-access authorize                           CLI to create cloud resources
--auto-replace-keypair automatically                   replaces key pair to access node if previous key pair is not found
--aws create                                           node/s in AWS cloud
--aws-profile string                                   aws profile to use (default "default")
--aws-volume-iops int                                  AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                                  AWS volume size in GB (default 1000)
--aws-volume-throughput int                            AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                               AWS volume type (default "gp3")
--chain-config string                                  path to the chain configuration for subnet
--custom-luxgo-version string                    install given luxgo version on node/s
--custom-subnet use                                    a custom VM as the subnet virtual machine
--custom-vm-branch string                              custom vm branch or commit
--custom-vm-build-script string                        custom vm build-script
--custom-vm-repo-url string                            custom vm repository url
--default-validator-params use                         default weight/start/duration params for subnet validator
--deploy-icm-messenger deploy                          Interchain Messenger (default true)
--deploy-icm-registry deploy                           Interchain Registry (default true)
--deploy-teleporter-messenger deploy                   Interchain Messenger (default true)
--deploy-teleporter-registry deploy                    Interchain Registry (default true)
--enable-monitoring set                                up Prometheus monitoring for created nodes. Please note that this option creates a separate monitoring instance and incures additional cost
--evm-chain-id uint                                    chain ID to use with Subnet-EVM
--evm-defaults use                                     default production settings with Subnet-EVM
--evm-production-defaults use                          default production settings for your blockchain
--evm-subnet use                                       Subnet-EVM as the subnet virtual machine
--evm-test-defaults use                                default test settings for your blockchain
--evm-token string                                     token name to use with Subnet-EVM
--evm-version string                                   version of Subnet-EVM to use
--force-subnet-create overwrite                        the existing subnet configuration if one exists
--gcp create                                           node/s in GCP cloud
--gcp-credentials string                               use given GCP credentials
--gcp-project string                                   use given GCP project
--grafana-pkg string                                   use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help help                                        for wiz
--icm generate                                         an icm-ready vm
--icm-messenger-contract-address-path string           path to an icm messenger contract address file
--icm-messenger-deployer-address-path string           path to an icm messenger deployer address file
--icm-messenger-deployer-tx-path string                path to an icm messenger deployer tx file
--icm-registry-bytecode-path string                    path to an icm registry bytecode file
--icm-version string                                   icm version to deploy (default "latest")
--latest-luxgo-pre-release-version install       latest luxgo pre-release version on node/s
--latest-luxgo-version install                   latest luxgo release version on node/s
--latest-evm-version use                               latest Subnet-EVM released version
--latest-pre-released-evm-version use                  latest Subnet-EVM pre-released version
--node-config string                                   path to luxgo node configuration for subnet
--node-type string                                     cloud instance type. Use 'default' to use recommended default instance type
--num-apis ints                                        number of API nodes(nodes without stake) to create in the new Devnet
--num-validators ints                                  number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--public-http-port allow                               public access to luxgo HTTP port
--region strings                                       create node/s in given region(s). Use comma to separate multiple regions
--relayer run                                          AWM relayer when deploying the vm
--ssh-agent-identity string                            use given ssh identity(only for ssh agent). If not set, default will be used.
--subnet-aliases strings                               additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-config string                                 path to the subnet configuration for subnet
--subnet-genesis string                                file path of the subnet genesis
--teleporter generate                                  an icm-ready vm
--teleporter-messenger-contract-address-path string    path to an icm messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an icm messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an icm messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an icm registry bytecode file
--teleporter-version string                            icm version to deploy (default "latest")
--use-ssh-agent use                                    ssh agent for ssh
--use-static-ip attach                                 static Public IP on cloud servers (default true)
--validators strings                                   deploy subnet into given comma separated list of validators. defaults to all cluster nodes
--config string                                        config file (default is $HOME/.lux-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check skip                               check for new versions
```

<a id="lux-node-export"></a>
### export

(ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.

**Usage:**
```bash
lux node export [subcommand] [flags]
```

**Flags:**

```bash
--file string                specify the file to export the cluster configuration to
--force overwrite            the file if it exists
-h, --help help              for export
--include-secrets include    keys in the export
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-node-import"></a>
### import

(ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use lux-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by lux-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.

**Usage:**
```bash
lux node import [subcommand] [flags]
```

**Flags:**

```bash
--file string               specify the file to export the cluster configuration to
-h, --help help             for import
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-list"></a>
### list

(ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.

**Usage:**
```bash
lux node list [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for list
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-loadtest"></a>
### loadtest

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.

**Usage:**
```bash
lux node loadtest [subcommand] [flags]
```

**Subcommands:**

- [`start`](#lux-node-loadtest-start): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.
- [`stop`](#lux-node-loadtest-stop): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Flags:**

```bash
-h, --help help             for loadtest
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-loadtest-start"></a>
#### loadtest start

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.

**Usage:**
```bash
lux node loadtest start [subcommand] [flags]
```

**Flags:**

```bash
--authorize-access authorize    CLI to create cloud resources
--aws create                    loadtest node in AWS cloud
--aws-profile string            aws profile to use (default "default")
--gcp create                    loadtest in GCP cloud
-h, --help help                 for start
--load-test-branch string       load test branch or commit
--load-test-build-cmd string    command to build load test binary
--load-test-cmd string          command to run load test
--load-test-repo string         load test repo url to use
--node-type string              cloud instance type for loadtest script
--region string                 create load test node in a given region
--ssh-agent-identity string     use given ssh identity(only for ssh agent). If not set, default will be used
--use-ssh-agent use             ssh agent(ex: Yubikey) for ssh auth
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="lux-node-loadtest-stop"></a>
#### loadtest stop

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Usage:**
```bash
lux node loadtest stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for stop
--load-test strings         stop specified load test node(s). Use comma to separate multiple load test instance names
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-local"></a>
### local

(ALPHA Warning) This command is currently in experimental mode.

The node local command suite provides a collection of commands related to local nodes

**Usage:**
```bash
lux node local [subcommand] [flags]
```

**Subcommands:**

- [`destroy`](#lux-node-local-destroy): Cleanup local node.
- [`start`](#lux-node-local-start): (ALPHA Warning) This command is currently in experimental mode. 

The node local start command sets up a validator on a local server. 
The validator will be validating the Lux Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running lux node status local
- [`status`](#lux-node-local-status): Get status of local node.
- [`stop`](#lux-node-local-stop): Stop local node.
- [`track`](#lux-node-local-track): (ALPHA Warning) make the local node at the cluster to track given blockchain

**Flags:**

```bash
-h, --help help             for local
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-local-destroy"></a>
#### local destroy

Cleanup local node.

**Usage:**
```bash
lux node local destroy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for destroy
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-local-start"></a>
#### local start

(ALPHA Warning) This command is currently in experimental mode. 

The node local start command sets up a validator on a local server. 
The validator will be validating the Lux Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running lux node status local

**Usage:**
```bash
lux node local start [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-path string                           use this luxgo binary path
--bootstrap-id stringArray                          nodeIDs of bootstrap nodes
--bootstrap-ip stringArray                          IP:port pairs of bootstrap nodes
--cluster string                                    operate on the given cluster
--custom-luxgo-version string                 install given luxgo version on node/s
--devnet operate                                    on a devnet network
--endpoint string                                   use the given endpoint for network operations
-f, --testnet testnet                                  operate on testnet (alias to testnet
--genesis string                                    path to genesis file
-h, --help help                                     for start
--latest-luxgo-pre-release-version install    latest luxgo pre-release version on node/s (default true)
--latest-luxgo-version install                latest luxgo release version on node/s
-l, --local operate                                 on a local network
-m, --mainnet operate                               on mainnet
--node-config string                                path to common luxgo config settings for all nodes
--num-nodes uint32                                  number of nodes to start (default 1)
--partial-sync primary                              network partial sync (default true)
--staking-cert-key-path string                      path to provided staking cert key for node
--staking-signer-key-path string                    path to provided staking signer key for node
--staking-tls-key-path string                       path to provided staking tls key for node
-t, --testnet testnet                                  operate on testnet (alias to testnet)
--upgrade string                                    path to upgrade file
--config string                                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                                  log level for the application (default "ERROR")
--skip-update-check skip                            check for new versions
```

<a id="lux-node-local-status"></a>
#### local status

Get status of local node.

**Usage:**
```bash
lux node local status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string         specify the blockchain the node is syncing with
-h, --help help             for status
--subnet string             specify the blockchain the node is syncing with
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-local-stop"></a>
#### local stop

Stop local node.

**Usage:**
```bash
lux node local stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for stop
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-local-track"></a>
#### local track

(ALPHA Warning) make the local node at the cluster to track given blockchain

**Usage:**
```bash
lux node local track [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-path string                           use this luxgo binary path
--custom-luxgo-version string                 install given luxgo version on node/s
-h, --help help                                     for track
--latest-luxgo-pre-release-version install    latest luxgo pre-release version on node/s (default true)
--latest-luxgo-version install                latest luxgo release version on node/s
--config string                                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                                  log level for the application (default "ERROR")
--skip-update-check skip                            check for new versions
```

<a id="lux-node-refresh-ips"></a>
### refresh-ips

(ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.

**Usage:**
```bash
lux node refresh-ips [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string        aws profile to use (default "default")
-h, --help help             for refresh-ips
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-resize"></a>
### resize

(ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.

**Usage:**
```bash
lux node resize [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string        aws profile to use (default "default")
--disk-size string          Disk size to resize in Gb (e.g. 1000Gb)
-h, --help help             for resize
--node-type string          Node type to resize (e.g. t3.2xlarge)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-scp"></a>
### scp

(ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ lux node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ lux node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ lux node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt

**Usage:**
```bash
lux node scp [subcommand] [flags]
```

**Flags:**

```bash
--compress use              compression for ssh
-h, --help help             for scp
--recursive copy            directories recursively
--with-loadtest include     loadtest node for scp cluster operations
--with-monitor include      monitoring node for scp cluster operations
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-ssh"></a>
### ssh

(ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.

**Usage:**
```bash
lux node ssh [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for ssh
--parallel run              ssh command on all nodes in parallel
--with-loadtest include     loadtest node for ssh cluster operations
--with-monitor include      monitoring node for ssh cluster operations
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-status"></a>
### status

(ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag

**Usage:**
```bash
lux node status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string         specify the blockchain the node is syncing with
-h, --help help             for status
--subnet string             specify the blockchain the node is syncing with
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-sync"></a>
### sync

(ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling lux node status `clusterName` --blockchain `blockchainName`

**Usage:**
```bash
lux node sync [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for sync
--no-checks do              not check for bootstrapped/healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    subnet alias to be used for RPC calls. defaults to subnet blockchain ID
--validators strings        sync subnet into given comma separated list of validators. defaults to all cluster nodes
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-update"></a>
### update

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM config.

You can check the status after update by calling lux node status

**Usage:**
```bash
lux node update [subcommand] [flags]
```

**Subcommands:**

- [`subnet`](#lux-node-update-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling lux node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help help             for update
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-update-subnet"></a>
#### update subnet

(ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling lux node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
lux node update subnet [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for subnet
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-upgrade"></a>
### upgrade

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM version.

You can check the status after upgrade by calling lux node status

**Usage:**
```bash
lux node upgrade [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for upgrade
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-validate"></a>
### validate

(ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling lux node status `clusterName`

**Usage:**
```bash
lux node validate [subcommand] [flags]
```

**Subcommands:**

- [`primary`](#lux-node-validate-primary): (ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.
- [`subnet`](#lux-node-validate-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling lux node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling lux node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help help             for validate
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-node-validate-primary"></a>
#### validate primary

(ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.

**Usage:**
```bash
lux node validate primary [subcommand] [flags]
```

**Flags:**

```bash
-e, --ewoq use               ewoq key [testnet/devnet only]
-h, --help help              for primary
-k, --key string             select the key to use [testnet only]
-g, --ledger use             ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings       use the given ledger addresses
--stake-amount uint          how many LUX to stake in the validator
--staking-period duration    how long validator validates for after start time
--start-time string          UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-node-validate-subnet"></a>
#### validate subnet

(ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling lux node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling lux node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
lux node validate subnet [subcommand] [flags]
```

**Flags:**

```bash
--default-validator-params use    default weight/start/duration params for subnet validator
-e, --ewoq use                    ewoq key [testnet/devnet only]
-h, --help help                   for subnet
-k, --key string                  select the key to use [testnet/devnet only]
-g, --ledger use                  ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings            use the given ledger addresses
--no-checks do                    not check for bootstrapped status or healthy status
--no-validation-checks do         not check if subnet is already synced or validated (default true)
--stake-amount uint               how many LUX to stake in the validator
--staking-period duration         how long validator validates for after start time
--start-time string               UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--validators strings              validate subnet for the given comma separated list of validators. defaults to all cluster nodes
--config string                   config file (default is $HOME/.lux-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="lux-node-whitelist"></a>
### whitelist

(ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Usage:**
```bash
lux node whitelist [subcommand] [flags]
```

**Flags:**

```bash
-y, --current-ip whitelist    current host ip
-h, --help help               for whitelist
--ip string                   ip address to whitelist
--ssh string                  ssh public key to whitelist
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="lux-primary"></a>
## lux primary

The primary command suite provides a collection of tools for interacting with the
Primary Network

**Usage:**
```bash
lux primary [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#lux-primary-addvalidator): The primary addValidator command adds a node as a validator 
in the Primary Network
- [`describe`](#lux-primary-describe): The subnet describe command prints details of the primary network configuration to the console.

**Flags:**

```bash
-h, --help help             for primary
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-primary-addvalidator"></a>
### addValidator

The primary addValidator command adds a node as a validator 
in the Primary Network

**Usage:**
```bash
lux primary addValidator [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--delegation-fee uint32         set the delegation fee (20 000 is equivalent to 2%)
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet testnet              operate on testnet (alias to testnet
-h, --help help                 for addValidator
-k, --key string                select the key to use [testnet only]
-g, --ledger use                ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings          use the given ledger addresses
-m, --mainnet operate           on mainnet
--nodeID string                 set the NodeID of the validator to add
--proof-of-possession string    set the BLS proof of possession of the validator to add
--public-key string             set the BLS public key of the validator to add
--staking-period duration       how long this validator will be staking
--start-time string             UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
-t, --testnet testnet              operate on testnet (alias to testnet)
--weight uint                   set the staking weight of the validator to add
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="lux-primary-describe"></a>
### describe

The subnet describe command prints details of the primary network configuration to the console.

**Usage:**
```bash
lux primary describe [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
-h, --help help             for describe
-l, --local operate         on a local network
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet"></a>
## lux subnet

The subnet command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the subnet create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the subnet deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

Deprecation notice: use 'lux blockchain'

**Usage:**
```bash
lux subnet [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#lux-subnet-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the Platform-Chain.

This command currently only works on Blockchains deployed to either the Testnet
Testnet or Mainnet.
- [`changeOwner`](#lux-subnet-changeowner): The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.
- [`changeWeight`](#lux-subnet-changeweight): The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.
- [`configure`](#lux-subnet-configure): LuxGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the LuxGo node 
configuration itself. This command allows you to set all those files.
- [`create`](#lux-subnet-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#lux-subnet-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#lux-subnet-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Testnet Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Lux-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Testnet, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
lux network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Testnet or Mainnet.
- [`describe`](#lux-subnet-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#lux-subnet-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#lux-subnet-import): Import blockchain configurations into lux-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#lux-subnet-join): The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --luxgo-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Testnet Testnet and Mainnet.
- [`list`](#lux-subnet-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#lux-subnet-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#lux-subnet-removevalidator): The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#lux-subnet-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#lux-subnet-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#lux-subnet-validators): The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.
- [`vmid`](#lux-subnet-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help help             for subnet
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the Platform-Chain.

This command currently only works on Blockchains deployed to either the Testnet
Testnet or Mainnet.

**Usage:**
```bash
lux subnet addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--balance uint                            set the LUX balance of the validator that will be used for continuous fee on Platform-Chain
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string          set the BLS proof of possession of the validator to add
--bls-public-key string                   set the BLS public key of the validator to add
--cluster string                          operate on the given cluster
--create-local-validator create           additional local validator and add it to existing running local node
--default-duration                        (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                      (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for testnet & mainnet, 30 seconds later for devnet)
--default-validator-params                (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                   (PoS only) delegation fee (in bips) (default 100)
--devnet operate                          on a devnet network
--disable-owner string                    Platform-Chain address that will able to disable the validator with a Platform-Chain transaction
--endpoint string                         use the given endpoint for network operations
-e, --ewoq use                            ewoq key [testnet/devnet only]
-f, --testnet testnet                        operate on testnet (alias to testnet
-h, --help help                           for addValidator
-k, --key string                          select the key to use [testnet/devnet only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    gather node id/bls from publicly available luxgo apis on the given endpoint
--node-id string                          node-id of the validator to add
--output-tx-path string                   (for Subnets, not L1s) file path of the add validator tx
--partial-sync set                        primary network partial sync for new validators (default true)
--remaining-balance-owner string          Platform-Chain address that will receive any leftover LUX from the validator when it is removed from Subnet
--rpc string                              connect to validator manager at the given rpc endpoint
--stake-amount uint                       (PoS only) amount of tokens to stake
--staking-period duration                 how long this validator will be staking
--start-time string                       (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings                (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet testnet                        operate on testnet (alias to testnet)
--wait-for-tx-acceptance                  (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                             set the staking weight of the validator to add (default 20)
--config string                           config file (default is $HOME/.lux-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="lux-subnet-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.

**Usage:**
```bash
lux subnet changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--cluster string              operate on the given cluster
--control-keys strings        addresses that may make subnet changes
--devnet operate              on a devnet network
--endpoint string             use the given endpoint for network operations
-e, --ewoq use                ewoq key [testnet/devnet]
-f, --testnet testnet            operate on testnet (alias to testnet
-h, --help help               for changeOwner
-k, --key string              select the key to use [testnet/devnet]
-g, --ledger use              ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings        use the given ledger addresses
-l, --local operate           on a local network
-m, --mainnet operate         on mainnet
--output-tx-path string       file path of the transfer subnet ownership tx
-s, --same-control-key use    the fee-paying key as control key
--subnet-auth-keys strings    control keys that will be used to authenticate transfer subnet ownership tx
-t, --testnet testnet            operate on testnet (alias to testnet)
--threshold uint32            required number of control key signatures to make subnet changes
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="lux-subnet-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.

**Usage:**
```bash
lux subnet changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-e, --ewoq use              ewoq key [testnet/devnet only]
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for changeWeight
-k, --key string            select the key to use [testnet/devnet only]
-g, --ledger use            ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings      use the given ledger addresses
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node-id of the validator
-t, --testnet testnet          operate on testnet (alias to testnet)
--weight uint               set the new staking weight of the validator (default 20)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-configure"></a>
### configure

LuxGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the LuxGo node 
configuration itself. This command allows you to set all those files.

**Usage:**
```bash
lux subnet configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help help                   for configure
--node-config string              path to luxgo node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.lux-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="lux-subnet-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
lux subnet create [subcommand] [flags]
```

**Flags:**

```bash
--custom use                        a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug enable                      blockchain debugging (default true)
--evm use                           the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults deprecation          notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token use            a gas token from another blockchain
-f, --force overwrite               the existing configuration if one exists
--from-github-repo generate         custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help help                     for create
--icm interoperate                  with other blockchains using ICM
--icm-registry-at-genesis setup     ICM registry smart contract on genesis [experimental]
--latest use                        latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release use                   latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults use           default production settings for your blockchain
--proof-of-authority use            proof of authority(PoA) for validator management
--proof-of-stake use                proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign set                     to false if creating non-sovereign blockchain (default true)
--teleporter interoperate           with other blockchains using ICM
--test-defaults use                 default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp generate                     a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check skip            check for new versions
```

<a id="lux-subnet-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
lux subnet delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for delete
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration locally, to Testnet Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Lux-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Testnet, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
lux network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Testnet or Mainnet.

**Usage:**
```bash
lux subnet deploy [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow                 the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings                   endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string                          log level to use with signature aggregator (default "Off")
--luxgo-path string                              use this luxgo binary path
--luxgo-version string                           use this version of luxgo (ex: v1.17.12) (default "latest-prerelease")
--balance float                                        set the LUX balance of each bootstrap validator that will be used for continuous fee on Platform-Chain (default 0.1)
--blockchain-genesis-key use                           genesis allocated key to fund validator manager initialization
--blockchain-key string                                CLI stored key to use to fund validator manager initialization
--blockchain-private-key string                        private key to use to fund validator manager initialization
--bootstrap-endpoints strings                          take validator node info from the given endpoints
--bootstrap-filepath string                            JSON file path that provides details about bootstrap validators, leave Node-ID and BLS values empty if using --generate-node-id=true
--cchain-funding-key string                            key to be used to fund relayer account on cchain
--cchain-icm-key string                                key to be used to pay for ICM deploys on LUExchange-Chain
--change-owner-address string                          address that will receive change if node is no longer L1 validator
--cluster string                                       operate on the given cluster
--control-keys strings                                 addresses that may make subnet changes
--convert-only avoid                                   node track, restart and poa manager setup
--devnet operate                                       on a devnet network
--endpoint string                                      use the given endpoint for network operations
-e, --ewoq use                                         ewoq key [testnet/devnet deploy only]
-f, --testnet testnet                                     operate on testnet (alias to testnet
--generate-node-id whether                             to create new node id for bootstrap validators (Node-ID and BLS values in bootstrap JSON file will be overridden if --bootstrap-filepath flag is used)
-h, --help help                                        for deploy
--icm-key string                                       key to be used to pay for ICM deploys (default "cli-teleporter-deployer")
--icm-version string                                   ICM version to deploy (default "latest")
-k, --key string                                       select the key to use [testnet/devnet deploy only]
-g, --ledger use                                       ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings                                 use the given ledger addresses
-l, --local operate                                    on a local network
-m, --mainnet operate                                  on mainnet
--mainnet-chain-id uint32                              use different ChainID for mainnet deployment
--noicm skip                                           automatic ICM deploy
--num-bootstrap-validators int                         (only if --generate-node-id is true) number of bootstrap validators to set up in sovereign L1 validator)
--num-local-nodes int                                  number of nodes to be created on local machine
--num-nodes uint32                                     number of nodes to be created on local network deploy (default 2)
--output-tx-path string                                file path of the blockchain creation tx
--partial-sync set                                     primary network partial sync for new validators (default true)
--pos-maximum-stake-amount uint                        maximum stake amount (default 1000)
--pos-maximum-stake-multiplier uint8                   maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16                    minimum delegation fee (default 1)
--pos-minimum-stake-amount uint                        minimum stake amount (default 1)
--pos-minimum-stake-duration uint                      minimum stake duration (default 100)
--pos-weight-to-value-factor uint                      weight to value factor (default 1)
--relay-cchain relay                                   LUExchange-Chain as source and destination (default true)
--relayer-allow-private-ips allow                      relayer to connec to private ips (default true)
--relayer-amount float                                 automatically fund relayer fee payments with the given amount
--relayer-key string                                   key to be used by default both for rewards and to pay fees
--relayer-log-level string                             log level to be used for relayer logs (default "info")
--relayer-path string                                  relayer binary to use
--relayer-version string                               relayer version to deploy (default "latest-prerelease")
-s, --same-control-key use                             the fee-paying key as control key
--skip-icm-deploy skip                                 automatic ICM deploy
--skip-local-teleporter skip                           automatic ICM deploy on local networks [to be deprecated]
--skip-relayer skip                                    relayer deploy
--skip-teleporter-deploy skip                          automatic ICM deploy
--subnet-auth-keys strings                             control keys that will be used to authenticate chain creation
-u, --subnet-id string                                 do not create a subnet, deploy the blockchain into the given subnet id
--subnet-only only                                     create a subnet
--teleporter-messenger-contract-address-path string    path to an ICM Messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an ICM Messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an ICM Messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an ICM Registry bytecode file
--teleporter-version string                            ICM version to deploy (default "latest")
-t, --testnet testnet                                     operate on testnet (alias to testnet)
--threshold uint32                                     required number of control key signatures to make subnet changes
--use-local-machine use                                local machine as a blockchain validator
--config string                                        config file (default is $HOME/.lux-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check skip                               check for new versions
```

<a id="lux-subnet-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
lux subnet describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis Print         the genesis to the console directly instead of the summary
-h, --help help             for describe
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
lux subnet export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help help                    for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.lux-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check skip           check for new versions
```

<a id="lux-subnet-import"></a>
### import

Import blockchain configurations into lux-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
lux subnet import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#lux-subnet-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#lux-subnet-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help help             for import
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
lux subnet import file [subcommand] [flags]
```

**Flags:**

```bash
--branch string             the repo branch to use if downloading a new repo
-f, --force overwrite       the existing configuration if one exists
-h, --help help             for file
--repo string               the repo to import (ex: luxfi/lux-plugins-core) or url to download the repo from
--subnet string             the subnet configuration to import from the provided repo
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
lux subnet import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string      the blockchain ID
--cluster string            operate on the given cluster
--custom use                a custom VM template
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
--evm import                a subnet-evm
--force overwrite           the existing configuration if one exists
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for public
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-url string           [optional] URL of an already running subnet validator
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-join"></a>
### join

The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --luxgo-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Testnet Testnet and Mainnet.

**Usage:**
```bash
lux subnet join [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-config string    file path of the luxgo config file
--cluster string               operate on the given cluster
--data-dir string              path of luxgo's data dir directory
--devnet operate               on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write if               true, skip to prompt to overwrite the config file
-f, --testnet testnet             operate on testnet (alias to testnet
-h, --help help                for join
-k, --key string               select the key to use [testnet only]
-g, --ledger use               ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings         use the given ledger addresses
-l, --local operate            on a local network
-m, --mainnet operate          on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of luxgo's plugin directory
--print if                     true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet testnet             operate on testnet (alias to testnet)
--config string                config file (default is $HOME/.lux-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check skip       check for new versions
```

<a id="lux-subnet-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
lux subnet list [subcommand] [flags]
```

**Flags:**

```bash
--deployed show             additional deploy information
-h, --help help             for list
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
lux subnet publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force If                   true, ignores if the subnet has been published in the past, and attempts a forced publish.
-h, --help help              for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Subnet description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-subnet-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
lux subnet removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                          operate on the given cluster
--devnet operate                          on a devnet network
--endpoint string                         use the given endpoint for network operations
--force force                             validator removal even if it's not getting rewarded
-f, --testnet testnet                        operate on testnet (alias to testnet
-h, --help help                           for removeValidator
-k, --key string                          select the key to use [testnet deploy only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    remove validator that responds to the given endpoint
--node-id string                          node-id of the validator
--output-tx-path string                   (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                              connect to validator manager at the given rpc endpoint
--subnet-auth-keys strings                (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
-t, --testnet testnet                        operate on testnet (alias to testnet)
--uptime uint                             validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                           config file (default is $HOME/.lux-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="lux-subnet-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
lux subnet stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for stats
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
lux subnet upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#lux-subnet-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Testnet Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --luxgo-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.lux.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#lux-subnet-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#lux-subnet-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#lux-subnet-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#lux-subnet-upgrade-print): Print the upgrade.json file content
- [`vm`](#lux-subnet-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Testnet and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help help             for upgrade
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Testnet Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --luxgo-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.lux.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
lux subnet upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-chain-config-dir string    luxgo's chain config file directory (default "/Users/owen.wahlgren/.luxgo/chains")
--config create                          upgrade config for future subnet deployments (same as generate)
--force If                               true, don't prompt for confirmation of timestamps in the past
--testnet testnet                              apply upgrade existing testnet deployment (alias for `testnet`)
-h, --help help                          for apply
--local local                            apply upgrade existing local deployment
--mainnet mainnet                        apply upgrade existing mainnet deployment
--print if                               true, print the manual config without prompting (for public networks only)
--testnet testnet                        apply upgrade existing testnet deployment (alias for `testnet`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check skip                 check for new versions
```

<a id="lux-subnet-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
lux subnet upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force If                   true, overwrite a possibly existing file without prompting
-h, --help help              for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-subnet-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
lux subnet upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for generate
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
lux subnet upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help              for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="lux-subnet-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
lux subnet upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for print
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Testnet and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
lux subnet upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string             Upgrade to custom binary
--config upgrade            config for future subnet deployments
--testnet testnet                 upgrade existing testnet deployment (alias for `testnet`)
-h, --help help             for vm
--latest upgrade            to latest version
--local local               upgrade existing local deployment
--mainnet mainnet           upgrade existing mainnet deployment
--plugin-dir string         plugin directory to automatically upgrade VM
--print print               instructions for upgrading
--testnet testnet           upgrade existing testnet deployment (alias for `testnet`)
--version string            Upgrade to custom version
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.

**Usage:**
```bash
lux subnet validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for validators
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-subnet-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
lux subnet vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for vmid
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-teleporter"></a>
## lux teleporter

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
lux teleporter [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-teleporter-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#lux-teleporter-sendmsg): Sends and wait reception for a ICM msg between two subnets.

**Flags:**

```bash
-h, --help help             for teleporter
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-teleporter-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

**Usage:**
```bash
lux teleporter deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain deploy                            ICM into LUExchange-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to LUExchange-Chain
--cluster string                            operate on the given cluster
--deploy-messenger deploy                   ICM Messenger (default true)
--deploy-registry deploy                    ICM Registry (default true)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy deploy              ICM Registry even if Messenger has already been deployed
-f, --testnet testnet                          operate on testnet (alias to testnet
--genesis-key use                           genesis allocated key to fund ICM deploy
-h, --help help                             for deploy
--include-cchain deploy                     ICM also to LUExchange-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local operate                         on a local network
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet testnet                          operate on testnet (alias to testnet)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="lux-teleporter-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two subnets.

**Usage:**
```bash
lux teleporter sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet testnet              operate on testnet (alias to testnet
--genesis-key use               genesis allocated key as message originator and to pay source blockchain fees
-h, --help help                 for sendMsg
--hex-encoded given             message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local operate             on a local network
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet testnet              operate on testnet (alias to testnet)
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="lux-transaction"></a>
## lux transaction

The transaction command suite provides all of the utilities required to sign multisig transactions.

**Usage:**
```bash
lux transaction [subcommand] [flags]
```

**Subcommands:**

- [`commit`](#lux-transaction-commit): The transaction commit command commits a transaction by submitting it to the Platform-Chain.
- [`sign`](#lux-transaction-sign): The transaction sign command signs a multisig transaction.

**Flags:**

```bash
-h, --help help             for transaction
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-transaction-commit"></a>
### commit

The transaction commit command commits a transaction by submitting it to the Platform-Chain.

**Usage:**
```bash
lux transaction commit [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help               for commit
--input-tx-filepath string    Path to the transaction signed by all signatories
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="lux-transaction-sign"></a>
### sign

The transaction sign command signs a multisig transaction.

**Usage:**
```bash
lux transaction sign [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help               for sign
--input-tx-filepath string    Path to the transaction file for signing
-k, --key string              select the key to use [testnet only]
-g, --ledger use              ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings        use the given ledger addresses
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="lux-update"></a>
## lux update

Check if an update is available, and prompt the user to install it

**Usage:**
```bash
lux update [subcommand] [flags]
```

**Flags:**

```bash
-c, --confirm Assume        yes for installation
-h, --help help             for update
-v, --version version       for update
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-validator"></a>
## lux validator

The validator command suite provides a collection of tools for managing validator
balance on Platform-Chain.

Validator's balance is used to pay for continuous fee to the Platform-Chain. When this Balance reaches 0, 
the validator will be considered inactive and will no longer participate in validating the L1

**Usage:**
```bash
lux validator [subcommand] [flags]
```

**Subcommands:**

- [`getBalance`](#lux-validator-getbalance): This command gets the remaining validator Platform-Chain balance that is available to pay
Platform-Chain continuous fee
- [`increaseBalance`](#lux-validator-increasebalance): This command increases the validator Platform-Chain balance
- [`list`](#lux-validator-list): This command gets a list of the validators of the L1

**Flags:**

```bash
-h, --help help             for validator
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-validator-getbalance"></a>
### getBalance

This command gets the remaining validator Platform-Chain balance that is available to pay
Platform-Chain continuous fee

**Usage:**
```bash
lux validator getBalance [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for getBalance
--l1 string                 name of L1
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node ID of the validator
-t, --testnet testnet          operate on testnet (alias to testnet)
--validation-id string      validation ID of the validator
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-validator-increasebalance"></a>
### increaseBalance

This command increases the validator Platform-Chain balance

**Usage:**
```bash
lux validator increaseBalance [subcommand] [flags]
```

**Flags:**

```bash
--balance float             amount of LUX to increase validator's balance by
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for increaseBalance
-k, --key string            select the key to use [testnet/devnet deploy only]
--l1 string                 name of L1 (to increase balance of bootstrap validators only)
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node ID of the validator
-t, --testnet testnet          operate on testnet (alias to testnet)
--validation-id string      validationIDStr of the validator
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="lux-validator-list"></a>
### list

This command gets a list of the validators of the L1

**Usage:**
```bash
lux validator list [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --testnet testnet          operate on testnet (alias to testnet
-h, --help help             for list
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet testnet          operate on testnet (alias to testnet)
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```



# Deploy a Smart Contract (/docs/lux-l1s/add-utility/deploy-smart-contract)

---
title: Deploy a Smart Contract
description: Deploy a smart contract on your Lux L1.
---

{/*
  EVM Version Warning - TEMPORARY
  Remove this section when Lux adds Pectra support (after SAE implementation)
  Last reviewed: December 2025
*/}

<Callout type="warn" title="Solidity Compiler EVM Version">
Lux LUExchange-Chain and Subnet-EVM currently support the **Cancun** EVM version and do not yet support newer hardforks like **Pectra**. Since Solidity v0.8.30 changed its default target to Pectra, you must explicitly configure your compiler to target `cancun`.

**In Remix:** Open the Solidity Compiler panel → expand Advanced Configurations → set EVM Version to **cancun**.

For **Hardhat** or **Foundry** configurations, see the [contract verification guide](/docs/primary-network/verify-contract/hardhat).
</Callout>

This tutorial assumes that:

- [an Lux L1 and EVM blockchain](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet) has been created
- Your Node is currently validating your target Lux L1
- Your wallet has a balance of the Lux L1 Native Token(Specified under _alloc_ in your [Genesis File](/docs/lux-l1s/evm-configuration/customize-lux-l1#genesis)).

Step 1: Setting up Core[​](#step-1-setting-up-core "Direct link to heading")
----------------------------------------------------------------------------

### **EVM Lux L1 Settings**: [(EVM Core Tutorial)](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet#connect-with-core)[​](#evm-lux-l1-settings-evm-core-tutorial "Direct link to heading")

- **`Network Name`**: Custom Subnet-EVM
- **`New RPC URL`**: http://NodeIPAddress:9650/ext/bc/BlockchainID/rpc (Note: the port number should match your local setting which can be different from 9650.)
- **`ChainID`**: Subnet-EVM ChainID
- **`Symbol`**: Subnet-EVM Token Symbol
- **`Explorer`**: N/A

You should see a balance of your Lux L1's Native Token in Core.

![balance](/images/smart-contract1.png)

Step 2: Connect Core and Deploy a Smart Contract[​](#step-2-connect-core-and-deploy-a-smart-contract "Direct link to heading")
------------------------------------------------------------------------------------------------------------------------------

### Using Remix[​](#using-remix "Direct link to heading")

Open [Remix](https://remix.ethereum.org/) -> Select Solidity.

![remix Lux L1 evm sc home](/images/smart-contract2.png)

Create the smart contracts that we want to compile and deploy using Remix file explorer

### Using GitHub[​](#using-github "Direct link to heading")

In Remix Home _Click_ the GitHub button.

![remix Lux L1 evm sc load panel](/images/smart-contract3.png)

Paste the [link to the Smart Contract](https://github.com/luxfi/lux-smart-contract-quickstart/blob/main/contracts/NFT.sol) into the popup and _Click_ import.

![remix Lux L1 evm sc import](/images/smart-contract4.png)

For this example, we will deploy an ERC721 contract from the [Lux Smart Contract Quickstart Repository](https://github.com/luxfi/lux-smart-contract-quickstart).

![remix Lux L1 evm sc file explorer](/images/smart-contract5.png)

Navigate to Deploy Tab -> Open the "ENVIRONMENT" drop-down and select Injected Web3 (make sure Core is loaded).

![remix Lux L1 evm sc web3](/images/smart-contract6.png)

Once we injected the web3-> Go back to the compiler, and compile the selected contract -> Navigate to Deploy Tab.

![remix Lux L1 evm sc compile](/images/smart-contract7.png)

Now, the smart contract is compiled, Core is injected, and we are ready to deploy our ERC721. Click "Deploy."

![remix Lux L1 evm sc deploy](/images/smart-contract8.png)

Confirm the transaction on the Core pop up.

![balance](/images/smart-contract9.png)

Our contract is successfully deployed!

![remix Lux L1 evm sc deployed](/images/smart-contract10.png)

Now, we can expand it by selecting it from the "Deployed Contracts" tab and test it out.

![remix Lux L1 evm sc end](/images/smart-contract11.png)

The contract ABI and Bytecode are available on the compiler tab.

![remix Lux L1 evm sc ABI](/images/smart-contract12.png)

If you had any difficulties following this tutorial or simply want to discuss Lux with us, you can join our community at [Discord](https://chat.avalabs.org/)!

You can use Subnet-EVM just like you use LUExchange-Chain and EVM tools. Only differences are `chainID` and RPC URL. For example you can deploy your contracts with [Hardhat](https://hardhat.org/getting-started) by changing `url` and `chainId` in the `hardhat.config.ts`.


# Add a Testnet Faucet (/docs/lux-l1s/add-utility/testnet-faucet)

---
title: Add a Testnet Faucet
description: This guide will help you add a testnet faucet to your Lux L1.
---
There are thousands of networks and chains in the blockchain space, each with its capabilities and use-cases. Each network requires native coins to do any transaction on them, which can have a monetary value as well. These coins can be collected through centralized exchanges, token sales, etc in exchange for some monetary assets like USD.

But we cannot risk our funds on the network or on any applications hosted on that network, without testing them first. So, these networks often have test networks or testnets, where the native coins do not have any monetary value, and thus can be obtained freely through faucets.

These testnets are often the testbeds for any new native feature of the network itself, or any dapp or [Lux L1](/docs/lux-l1s) that is going live on the main network (Mainnet). For example, [Testnet](/docs/primary-network) network is the Testnet for Lux's Mainnet.

Besides Testnet Testnet, the [Lux Faucet](https://core.app/tools/testnet-faucet/?lux-l1=c&token=c) can be used to get free test tokens on testnet Lux L1s like:

- [WAGMI Testnet](https://core.app/tools/testnet-faucet/?lux-l1=wagmi)
- [DeFI Kingdoms Testnet](https://core.app/tools/testnet-faucet/?lux-l1=dfk)
- [Beam Testnet](https://core.app/tools/testnet-faucet/?lux-l1=beam&token=beam) and many more.

You can use this [repository](https://github.com/luxfi/lux-faucet) to deploy your faucet or just make a PR with the [configurations](https://github.com/luxfi/lux-faucet/blob/main/config.json) of the Lux L1. This faucet comes with many features like multiple chain support, custom rate-limiting per Lux L1, CAPTCHA verification, and concurrent transaction handling.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

A [Faucet](https://core.app/tools/testnet-faucet/) powered by Lux for Testnet Network and other Lux L1s. You can -

- Request test coins for the supported Lux L1s
- Integrate your EVM Lux L1 with the faucet by making a PR with the [chain configurations](https://github.com/luxfi/lux-faucet/blob/main/config.json)
- Fork the [repository](https://github.com/luxfi/lux-faucet) to deploy your faucet for any EVM chain

Adding a New Lux L1[​](#adding-a-new-lux-l1 "Direct link to heading")
---------------------------------------------------------------------

You can also integrate a new Lux L1 on the live [faucet](https://core.app/tools/testnet-faucet/) with just a few lines of configuration parameters. All you have to do is make a PR on the [Lux Faucet](https://github.com/luxfi/lux-faucet) git repository with the Lux L1's information. The following parameters are required.

```json
{
    "ID": string,
    "NAME": string,
    "TOKEN": string,
    "RPC": string,
    "CHAINID": number,
    "EXPLORER": string,
    "IMAGE": string,
    "MAX_PRIORITY_FEE": string,
    "MAX_FEE": string,
    "DRIP_AMOUNT": number,
    "RATELIMIT": {
        "MAX_LIMIT": number,
        "WINDOW_SIZE": number
    }
}
```

- `ID` - Each Lux L1 chain should have a unique and relatable ID.
- `NAME` - Name of the Lux L1 chain that will appear on the site.
- `RPC` - A valid RPC URL for accessing the chain.
- `CHAINID` - ChainID of the chain
- `EXPLORER` - Base URL of standard explorer's site.
- `IMAGE` - URL of the icon of the chain that will be shown in the dropdown.
- `MAX_PRIORITY_FEE` - Maximum tip per faucet drop in **wei** or **10\-18** unit (for EIP1559 supported chains)
- `MAX_FEE` - Maximum fee that can be paid for a faucet drop in **wei** or **10\-18** unit
- `DRIP_AMOUNT` - Amount of coins to send per request in **gwei** or **10\-9** unit
- `RECALIBRATE` _(optional)_ - Number of seconds after which the nonce and balance will recalibrate
- `RATELIMIT` - Number of times (MAX\_LIMIT) to allow per user within the WINDOW\_SIZE (in minutes)

Add the configuration in the array of `evmchains` inside the [config.json](https://github.com/luxfi/lux-faucet/blob/main/config.json) file and make a PR.

Building and Deploying a Faucet[​](#building-and-deploying-a-faucet "Direct link to heading")
---------------------------------------------------------------------------------------------

You can also deploy and build your faucet by using the [Lux Faucet](https://github.com/luxfi/lux-faucet) repository.

### Requirements[​](#requirements "Direct link to heading")

- [Node](https://nodejs.org/en) >= 17.0 and [npm](https://www.npmjs.com/) >= 8.0
- [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html) v3 keys
- [Docker](https://www.docker.com/get-started/)

### Installation[​](#installation "Direct link to heading")

Clone this repository at your preferred location.

```bash
git clone https://github.com/luxfi/lux-faucet
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:luxfi/lux-faucet.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

### Client-Side Configurations[​](#client-side-configurations "Direct link to heading")

We need to configure our application with the server API endpoints and CAPTCHA site keys. All the client-side configurations are there in the `client/src/config.json` file. Since there are no secrets on the client-side, we do not need any environment variables. Update the config files according to your need.

```json
{
  "banner": "/banner.png",
  "apiBaseEndpointProduction": "/api/",
  "apiBaseEndpointDevelopment": "http://localhost:8000/api/",
  "apiTimeout": 10000,
  "CAPTCHA": {
    "siteKey": "6LcNScYfAAAAAJH8fauA-okTZrmAxYqfF9gOmujf",
    "action": "faucetdrip"
  }
}
```

Put the Google's reCAPTCHA site-key without which the faucet client can't send the necessary CAPTCHA response to the server. This key is not a secret and could be public.

In the above file, there are 2 base endpoints for the faucet server `apiBaseEndpointProduction` and `apiBaseEndpointDevelopment`.

In production mode, the client-side will be served as static content over the server's endpoint, and hence we do not have to provide the server's IP address or domain.

The URL path should be valid, where the server's APIs are hosted. If the endpoints for API have a leading `/v1/api` and the server is running on localhost at port 3000, then you should use `http://localhost:3000/v1/api` or `/v1/api/` depending on whether it is production or development.

### Server-Side Configurations[​](#server-side-configurations "Direct link to heading")

On the server-side, we need to configure 2 files - `.env` for secret keys and `config.json` for chain and API rate limiting configurations.

#### Setup Environment Variables[​](#setup-environment-variables "Direct link to heading")

Setup the environment variable with your private key and reCAPTCHA secret. Make a `.env` file in your preferred location with the following credentials, as this file will not be committed to the repository. The faucet server can handle multiple EVM chains, and therefore requires private keys for addresses with funds on each of the chains.

If you have funds on the same address on every chain, then you can specify them with the single variable`PK`. But if you have funds on different addresses on different chains, then you can provide each of the private keys against the ID of the chain, as shown below.

```bash
C="C chain private key"
WAGMI="Wagmi chain private key"
PK="Sender Private Key with Funds in it"
CAPTCHA_SECRET="Google reCAPTCHA Secret"
```

`PK` will act as a fallback private key, in case, the key for any chain is not provided.

#### Setup EVM Chain Configurations[​](#setup-evm-chain-configurations "Direct link to heading")

You can create a faucet server for any EVM chain by making changes in the `config.json` file. Add your chain configuration as shown below in the `evmchains` object. Configuration for Testnet's LUExchange-Chain and WAGMI chain is shown below for example.

```json
"evmchains": [
    {
        "ID": "C",
        "NAME": "Testnet (LUExchange-Chain)",
        "TOKEN": "LUX",
        "RPC": "https://api.lux-test.network/ext/C/rpc",
        "CHAINID": 43113,
        "EXPLORER": "https://testnet.snowtrace.io",
        "IMAGE": "/luxred.png",
        "MAX_PRIORITY_FEE": "2000000000",
        "MAX_FEE": "100000000000",
        "DRIP_AMOUNT": 2000000000,
        "RECALIBRATE": 30,
        "RATELIMIT": {
            "MAX_LIMIT": 1,
            "WINDOW_SIZE": 1440
        }
    },
    {
        "ID": "WAGMI",
        "NAME": "WAGMI Testnet",
        "TOKEN": "WGM",
        "RPC": "https://subnets.lux.network/wagmi/wagmi-chain-testnet/rpc",
        "CHAINID": 11111,
        "EXPLORER": "https://subnets.lux.network/wagmi/wagmi-chain-testnet/explorer",
        "IMAGE": "/wagmi.png",
        "MAX_PRIORITY_FEE": "2000000000",
        "MAX_FEE": "100000000000",
        "DRIP_AMOUNT": 2000000000,
        "RATELIMIT": {
            "MAX_LIMIT": 1,
            "WINDOW_SIZE": 1440
        }
    }
]
```

In the above configuration drip amount is in `nLUX` or `gwei`, whereas fees are in `wei`. For example, with the above configurations, the faucet will send `1 LUX` with maximum fees per gas being `100 nLUX` and priority fee as `2 nLUX`.

The rate limiter for LUExchange-Chain will only accept 1 request in 60 minutes for a particular API and 2 requests in 60 minutes for the WAGMI chain. Though it will skip any failed requests so that users can request tokens again, even if there is some internal error in the application. On the other hand, the global rate limiter will allow 15 requests per minute on every API. This time failed requests will also get counted so that no one can abuse the APIs.

### API Endpoints[​](#api-endpoints "Direct link to heading")

This server will expose the following APIs

#### Health API[​](#health-api "Direct link to heading")

The `/health` API will always return a response with a `200` status code. This endpoint can be used to know the health of the server.

```bash
curl http://localhost:8000/health
```

Response

#### Get Faucet Address[​](#get-faucet-address "Direct link to heading")

This API will be used for fetching the faucet address.

```bash
curl http://localhost:8000/api/faucetAddress?chain=C
```

It will give the following response:

```bash
0x3EA53fA26b41885cB9149B62f0b7c0BAf76C78D4
```

#### Get Faucet Balance[​](#get-faucet-balance "Direct link to heading")

This API will be used for fetching the faucet address.

```bash
curl http://localhost:8000/api/getBalance?chain=C
```

#### Send Token[​](#send-token "Direct link to heading")

This API endpoint will handle token requests from users. It will return the transaction hash as a receipt of the faucet drip.

```bash
curl -d '{
    "address": "0x3EA53fA26b41885cB9149B62f0b7c0BAf76C78D4"
    "chain": "C"
}' -H 'Content-Type: application/json' http://localhost:8000/api/sendToken
```

Send token API requires a CAPTCHA response token that is generated using the CAPTCHA site key on the client-side.

Since we can't generate and pass this token while making a curl request, we have to disable the CAPTCHA verification for testing purposes. You can find the steps to disable it in the next sections. The response is shown below

```json
{
    "message": "Transaction successful on Lux C Chain!",
    "txHash": "0x3d1f1c3facf59c5cd7d6937b3b727d047a1e664f52834daf20b0555e89fc8317"
}
```

### Rate Limiters[​](#rate-limiters-important "Direct link to heading")

The rate limiters are applied on the global (all endpoints) as well as on the `/api/sendToken` API. These can be configured from the `config.json` file. Rate limiting parameters for chains are passed in the chain configuration as shown above.

```json
"GLOBAL_RL": {
    "ID": "GLOBAL",
    "RATELIMIT": {
        "REVERSE_PROXIES": 4,
        "MAX_LIMIT": 40,
        "WINDOW_SIZE": 1,
        "PATH": "/",
        "SKIP_FAILED_REQUESTS": false
    }
}
```

There could be multiple proxies between the server and the client. The server will see the IP address of the adjacent proxy connected with the server, and this may not be the client's actual IP.

The IPs of all the proxies that the request has hopped through are stuffed inside the header **x-forwarded-for** array. But the proxies in between can easily manipulate these headers to bypass rate limiters. So, we cannot trust all the proxies and hence all the IPs inside the header.

The proxies that are set up by the owner of the server (reverse-proxies) are the trusted proxies on which we can rely and know that they have stuffed the actual IP of the callers in between. Any proxy that is not set up by the server, should be considered an untrusted proxy. So, we can jump to the IP address added by the last proxy that we trust. The number of jumps that we want can be configured in the `config.json` file inside the `GLOBAL_RL` object.

![faucet 5](/images/faucet1.png)

#### Clients Behind Same Proxy[​](#clients-behind-same-proxy "Direct link to heading")

Consider the below diagram. The server is set up with 2 reverse proxies. If the client is behind proxies, then we cannot get the client's actual IP, and instead will consider the proxy's IP as the client's IP. And if some other client is behind the same proxy, then those clients will be considered as a single entity and might get rate-limited faster.

![faucet 6](/images/faucet2.png)

Therefore it is advised to the users, to avoid using any proxy for accessing applications that have critical rate limits, like this faucet.

#### Wrong Number of Reverse Proxies[​](#wrong-number-of-reverse-proxies "Direct link to heading")

So, if you want to deploy this faucet, and have some reverse proxies in between, then you should configure this inside the `GLOBAL_RL` key of the `config.json` file. If this is not configured properly, then the users might get rate-limited very frequently, since the server-side proxy's IP addresses are being viewed as the client's IP. You can verify this in the code [here](https://github.com/luxfi/lux-faucet/blob/23eb300635b64130bc9ce10d9e894f0a0b3d81ea/middlewares/rateLimiter.ts#L25).

```json
"GLOBAL_RL": {
    "ID": "GLOBAL",
    "RATELIMIT": {
        "REVERSE_PROXIES": 4,
        ...
    }
}
```

![faucet 7](/images/faucet3.png)

It is also quite common to have Cloudflare as the last reverse proxy or the exposed server. Cloudflare provides a header **cf-connecting-ip** which is the IP of the client that requested the faucet and hence Cloudflare. We are using this as default.

### CAPTCHA Verification[​](#captcha-verification "Direct link to heading")

CAPTCHA is required to prove the user is a human and not a bot. For this purpose, we will use [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html). The server-side will require `CAPTCHA_SECRET` that should not be exposed. You can set the threshold score to pass the CAPTCHA test by the users [here](https://github.com/luxfi/lux-faucet/blob/23eb300635b64130bc9ce10d9e894f0a0b3d81ea/middlewares/verifyCaptcha.ts#L20).

You can disable these CAPTCHA verifications and rate limiters for testing the purpose, by tweaking in the `server.ts` file.

### Disabling Rate Limiters[​](#disabling-rate-limiters "Direct link to heading")

Comment or remove these two lines from the `server.ts` file

```ts title="server.ts"
new RateLimiter(app, [GLOBAL_RL]);
new RateLimiter(app, evmchains);
```

### Disabling CAPTCHA Verification[​](#disabling-captcha-verification "Direct link to heading")

Remove the `captcha.middleware` from `sendToken` API.

### Starting the Faucet[​](#starting-the-faucet "Direct link to heading")

Follow the below commands to start your local faucet.

#### Installing Dependencies[​](#installing-dependencies "Direct link to heading")

This will concurrently install dependencies for both client and server.

If ports have a default configuration, then the client will start at port 3000 and the server will start at port 8000 while in development mode.

#### Starting in Development Mode[​](#starting-in-development-mode "Direct link to heading")

This will concurrently start the server and client in development mode.

#### Building for Production[​](#building-for-production "Direct link to heading")

The following command will build server and client at `build/` and `build/client` directories.

#### Starting in Production Mode[​](#starting-in-production-mode "Direct link to heading")

This command should only be run after successfully building the client and server-side code.

### Setting up with Docker[​](#setting-up-with-docker "Direct link to heading")

Follow the steps to run this application in a Docker container.

#### Build Docker Image[​](#build-docker-image "Direct link to heading")

Docker images can be served as the built versions of our application, that can be used to deploy on Docker container.

```bash
docker build . -t faucet-image
```

#### Starting Application inside Docker Container[​](#starting-application-inside-docker-container "Direct link to heading")

Now we can create any number of containers using the above `faucet` image. We also have to supply the `.env` file or the environment variables with the secret keys to create the container. Once the container is created, these variables and configurations will be persisted and can be easily started or stopped with a single command.

```bash
docker run -p 3000:8000 --name faucet-container --env-file ../.env faucet-image
```

The server will run on port 8000, and our Docker will also expose this port for the outer world to interact. We have exposed this port in the `Dockerfile`. But we cannot directly interact with the container port, so we had to bind this container port to our host port. For the host port, we have chosen 3000. This flag `-p 3000:8000` achieves the same.

This will start our faucet application in a Docker container at port 3000 (port 8000 on the container). You can interact with the application by visiting \[http://localhost:3000\] in your browser.

#### Stopping the Container[​](#stopping-the-container "Direct link to heading")

You can easily stop the container using the following command

```bash
docker stop faucet-container
```

#### Restarting the Container[​](#restarting-the-container "Direct link to heading")

To restart the container, use the following command

```bash
docker start faucet-container
```

Using the Faucet[​](#using-the-faucet "Direct link to heading")
---------------------------------------------------------------

Using the faucet is quite straightforward, but for the sake of completeness, let's go through the steps, to collect your first test coins.

### Visit Lux Faucet Site[​](#visit-lux-faucet-site "Direct link to heading")

Go to [https://core.app/tools/testnet-faucet/](https://core.app/tools/testnet-faucet/). You will see various network parameters like network name, faucet balance, drop amount, drop limit, faucet address, etc.

![faucet 1](/images/faucet4.png)

### Select Network[​](#select-network "Direct link to heading")

You can use the dropdown to select the network of your choice and get some free coins (each network may have a different drop amount).

![faucet 2](/images/faucet5.png)

### Put Address and Request Coins[​](#put-address-and-request-coins "Direct link to heading")

If you already have an LUX balance greater than zero on Mainnet, paste your LUExchange-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/lux). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet LUX if developers are unable to obtain it from the other two options.

Within a second, you will get a **transaction hash** for the processed transaction. The hash would be a hyperlink to Lux L1's explorer. You can see the transaction status, by clicking on that hyperlink.

![faucet 3](/images/faucet6.png)

### More Interactions[​](#more-interactions "Direct link to heading")

This is not just it. Using the buttons shown below, you can go to the Lux L1 explorer or add the Lux L1 to your browser wallet extensions like Core or MetaMask with a single click.

![faucet 4](/images/faucet7.png)

### Probable Errors and Troubleshooting[​](#probable-errors-and-troubleshooting "Direct link to heading")

Errors are not expected, but if you are facing some of the errors shown, then you could try troubleshooting as shown below. If none of the troubleshooting works, reach us through [Discord](https://discord.com/channels/578992315641626624/).

1. **Too many requests. Please try again after X minutes**: This is a rate-limiting message. Every Lux L1 can set its drop limits. The above message suggests that you have reached your drop limit, that is the number of times you could request coins within the window of X minutes. You should try requesting after X minutes. If you are facing this problem, even when you are requesting for the first time in the window, you may be behind some proxy, Wi-Fi, or VPN service that is also being used by some other user.  
2. **CAPTCHA verification failed! Try refreshing**: We are using v3 of [Google's reCAPTCHA](https://developers.google.com/recaptcha/docs/v3). This version uses scores between 0 and 1 to rate the interaction of humans with the site, with 0 being the most suspicious one. You do not have to solve any puzzle or mark the **I am not a Robot** checkbox. The score will be automatically calculated. We want our users to score at least 0.3 to use the faucet. This is configurable, and we will update the threshold after having broader data. But if you are facing this issue, then you can try refreshing your page, disabling ad-blockers, or switching off any VPN. You can follow this [guide](https://2captcha.com/blog/google-doesnt-accept-recaptcha-answers) to get rid of this issue.   
3. **Internal RPC error! Please try after sometime**: This is an internal error in the Lux L1's node, on which we are making an RPC for sending transactions. A regular check will update the RPC's health status every 30 seconds (default) or whatever is set in the configuration. This may happen only in rare scenarios and you cannot do much about it, rather than waiting.  
4. **Timeout of 10000ms exceeded**: There could be many reasons for this message. It could be an internal server error, or the request didn't receive by the server, slow internet, etc. You could try again after some time, and if the problem persists, then you should raise this issue on our [Discord](https://discord.com/channels/578992315641626624/) server.
5. **Couldn't see any transaction status on explorer**: The transaction hash that you get for each drop is pre-computed using the expected nonce, amount, and receiver's address. Though transactions on Lux are near-instant, the explorer may take time to index those transactions. You should wait for a few more seconds, before raising any issue or reaching out to us.


# Background and Requirements (/docs/lux-l1s/custom-precompiles/background-requirements)

---
title: Background and Requirements
description: Learn about the background and requirements for customizing Ethereum Virtual Machine.
---

This is a brief overview of what this tutorial will cover.

- Write a Solidity interface
- Generate the precompile template
- Implement the precompile functions in Golang
- Write and run tests

<Callout type="warn">
Stateful precompiles are [alpha software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha). Build at your own risk.
</Callout>

In this tutorial, we used a branch based on Subnet-EVM version `v0.5.2`. You can find the branch [here](https://github.com/luxfi/subnet-evm/tree/helloworld-official-tutorial-v2). The code in this branch is the same as Subnet-EVM except for the `precompile/contracts/helloworld` directory. The directory contains the code for the `HelloWorld` precompile. We will be using this precompile as an example to learn how to write a stateful precompile. The code in this branch can become outdated. You should always use the latest version of Subnet-EVM when you develop your own precompile.

## Precompile-EVM

Subnet-EVM precompiles can be registered from an external repo. This allows developer to build their precompiles without maintaining a fork of Subnet-EVM. The precompiles are then registered in the Subnet-EVM at build time.

The difference between using Subnet-EVM and Precompile-EVM is that with Subnet-EVM you can change EVM internals to interact with your precompiles. Such as changing fee structure, adding new opcodes, changing how to build a block, etc. With Precompile-EVM you can only add new stateful precompiles that can interact with the StateDB. Precompiles built with Precompile-EVM are still very powerful because it can directly access to the state and modify it.

There is a template repo for how to build a precompile with this way called [Precompile-EVM](https://github.com/luxfi/precompile-evm). Both Subnet-EVM and Precompile-EVM share similar directory structures and common codes.

You can reference the Precompile-EVM PR that adds Hello World precompile [here](https://github.com/luxfi/precompile-evm/pull/12).

## Requirements

This tutorial assumes familiarity with Golang and JavaScript.

Additionally, users should be deeply familiar with the EVM in order to understand its invariants since adding a Stateful Precompile modifies the EVM itself.

Here are some recommended resources to learn the ins and outs of the EVM:

- [The Ethereum Virtual Machine](https://github.com/ethereumbook/ethereumbook/blob/develop/13evm.asciidoc)
- [Precompiles in Solidity](https://medium.com/@rbkhmrcr/precompiles-solidity-e5d29bd428c4)
- [Deconstructing a Smart Contract](https://blog.openzeppelin.com/deconstructing-a-solidity-contract-part-i-introduction-832efd2d7737/)
- [Layout of State Variables in Storage](https://docs.soliditylang.org/en/v0.8.10/internals/layout_in_storage.html)
- [Layout in Memory](https://docs.soliditylang.org/en/v0.8.10/internals/layout_in_memory.html)
- [Layout of Call Data](https://docs.soliditylang.org/en/v0.8.10/internals/layout_in_calldata.html)
- [Contract ABI Specification](https://docs.soliditylang.org/en/v0.8.10/abi-spec.html)
- [Customizing the EVM with Stateful Precompiles](https://medium.com/luxlux/customizing-the-evm-with-stateful-precompiles-f44a34f39efd)

Please install the following before getting started.

First, install the latest version of Go. Follow the instructions [here](https://go.dev/doc/install). You can verify by running `go version`.

Set the `$GOPATH` environment variable properly for Go to look for Go Workspaces. Please read [this](https://go.dev/doc/gopath_code) for details. You can verify by running `echo $GOPATH`.

<Callout title="Note">
See [here](https://github.com/golang/go/wiki/SettingGOPATH) for instructions on setting the GOPATH based on system configurations.
</Callout>

As a few things will be installed into `$GOPATH/bin`, please make sure that `$GOPATH/bin` is in your `$PATH`, otherwise, you may get an error running the commands below. To do that, run the command: `export PATH=$PATH:$GOROOT/bin:$GOPATH/bin`

Download the following prerequisites into your `$GOPATH`:

- Git Clone the repository (Subnet-EVM or Precompile-EVM)
- Git Clone [LuxGo](https://github.com/luxfi/luxgo) repository
- Install [Lux Network Runner](/docs/tooling/lux-cli)
- Install [solc](https://github.com/ethereum/solc-js#usage-on-the-command-line)
- Install [Node.js and NPM](https://nodejs.org/en/download) For easy copy paste, use the below commands:

```bash
cd $GOPATH
mkdir -p src/github.com/luxfi
cd src/github.com/luxfi
```

Clone the repository:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
git clone git@github.com:luxfi/subnet-evm.git
```

Then run the following commands:

```bash
git clone git@github.com:luxfi/luxgo.git
curl -sSfL https://raw.githubusercontent.com/luxfi/lux-network-runner/main/scripts/install.sh | sh -s
npm install -g solc
```
</Tab>
<Tab value="Precompile-EVM">
```bash
git clone git@github.com:luxfi/precompile-evm.git
```

Alternatively you can use it as a template repo from github.

Then run the following commands:

```bash
git clone git@github.com:luxfi/luxgo.git
curl -sSfL https://raw.githubusercontent.com/luxfi/lux-network-runner/main/scripts/install.sh | sh -s
npm install -g solc
```
</Tab>
</Tabs>

## Complete Code

You can inspect example pull request for the complete code.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
  <Tab value="Subnet-EVM">
    [Subnet-EVM Hello World Pull Request](https://github.com/luxfi/subnet-evm/pull/565/)
  </Tab>
  <Tab value="Precompile-EVM">
    [Precompile-EVM Hello World Pull Request](https://github.com/luxfi/precompile-evm/pull/12/)
  </Tab>
</Tabs>

For a full-fledged example, you can also check out the [Reward Manager Precompile](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/rewardmanager/).

# Generating Your Precompile (/docs/lux-l1s/custom-precompiles/create-precompile)

---
title: Generating Your Precompile
description: In this section, we will go over the process for automatically generating the template code which you can configure accordingly for your stateful precompile.
---

First, we must create the Solidity interface that we want our precompile to implement. This will be the HelloWorld Interface. It will have two simple functions, `sayHello()`, `setGreeting()` and an event `GreetingChanged`. These two functions will demonstrate the getting and setting respectively of a value stored in the precompile's state space.

The `sayHello()` function is a `view` function, meaning it does not modify the state of the precompile and returns a string result. The `setGreeting()` function is a state changer function, meaning it modifies the state of the precompile. The `HelloWorld` interface inherits `IAllowList` interface to use the allow list functionality.

For this tutorial, we will be working in a new branch in Subnet-EVM/Precompile-EVM repo.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/subnet-evm
```

We will start off in this directory `./contracts/`:

```bash
cd contracts/
```

Create a new file called `IHelloWorld.sol` and copy and paste the below code:

```solidity title="contracts/IHelloWorld.sol"
// (c) 2022-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;
import "./IAllowList.sol";

interface IHelloWorld is IAllowList {
  event GreetingChanged(
    address indexed sender,
    string oldGreeting,
    string newGreeting
  );

  // sayHello returns the stored greeting string
  function sayHello() external view returns (string calldata result);

  // setGreeting  stores the greeting string
  function setGreeting(string calldata response) external;
}
```

Now we have an interface that our precompile can implement! Let's create an [ABI](https://docs.soliditylang.org/en/v0.8.13/abi-spec.html#contract-abi-specification) of our Solidity interface.

In the same directory, let's run:

```bash
solc --abi ./contracts/interfaces/IHelloWorld.sol -o ./abis
```

This generates the ABI code under `./abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi`.

```
[
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "oldGreeting",
        "type": "string"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "newGreeting",
        "type": "string"
      }
    ],
    "name": "GreetingChanged",
    "type": "event"
  },
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "uint256",
        "name": "role",
        "type": "uint256"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "account",
        "type": "address"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "uint256",
        "name": "oldRole",
        "type": "uint256"
      }
    ],
    "name": "RoleSet",
    "type": "event"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "readAllowList",
    "outputs": [
      { "internalType": "uint256", "name": "role", "type": "uint256" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [],
    "name": "sayHello",
    "outputs": [
      { "internalType": "string", "name": "result", "type": "string" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setAdmin",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setEnabled",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "string", "name": "response", "type": "string" }
    ],
    "name": "setGreeting",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setManager",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setNone",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  }
]
```

As you can see the ABI also contains the `IAllowList` interface functions. This is because the `IHelloWorld` interface inherits from the `IAllowList` interface.

Note: The ABI must have named outputs in order to generate the precompile template.

Now that we have an ABI for the precompile gen tool to interact with, we can run the following command to generate our HelloWorld precompile files!

Let's go back to the root of the repository and run the PrecompileGen script helper:

```bash
cd ..
```

Both of these Subnet-EVM and Precompile-EVM have the same `generate_precompile.sh` script. The one in Precompile-EVM installs the script from Subnet-EVM and runs it.

```bash
./scripts/generate_precompile.sh --help

# output
Using branch: precompile-tutorial
NAME:
precompilegen - subnet-evm precompile generator tool

USAGE:
main [global options] command [command options] [arguments...]

VERSION:
1.10.26-stable

COMMANDS:
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:

    --abi value
          Path to the contract ABI json to generate, - for STDIN

    --out value
          Output folder for the generated precompile files, - for STDOUT (default =
          ./precompile/contracts/{pkg}). Test files won't be generated if STDOUT is used
    --pkg value
          Go package name to generate the precompile into (default = {type})
    --type value
          Struct name for the precompile (default = {abi file name})
MISC
    --help, -h                     (default: false)
          show help
    --version, -v                  (default: false)
          print the version
COPYRIGHT:
Copyright 2013-2022 The go-ethereum Authors
```

Now let's generate the precompile template files!
</Tab>

<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
```

We will start off in this directory `./contracts/`:

```bash
cd contracts/
```

For Precompile-EVM interfaces and other contracts in Subnet-EVM can be accessible through `@luxfi/subnet-evm-contracts` package. This is already added to the `package.json` file. You can install it by running `npm install`. In order to import `IAllowList` interface, you can use the following import statement:

```solidity
import "@luxfi/subnet-evm-contracts/contracts/interfaces/IAllowList.sol";
```

The full file looks like this:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0;
import "@luxfi/subnet-evm-contracts/contracts/interfaces/IAllowList.sol";

interface IHelloWorld is IAllowList {
  event GreetingChanged(
    address indexed sender,
    string oldGreeting,
    string newGreeting
  );

  // sayHello returns the stored greeting string
  function sayHello() external view returns (string calldata result);

  // setGreeting stores the greeting string
  function setGreeting(string calldata response) external;
}
```

Now we have an interface that our precompile can implement! Let's create an ABI of our Solidity interface.

In Precompile-EVM we import contracts from `@luxfi/subnet-evm-contracts` package. In order to generate the ABI in Precompile-EVM we need to include the `node_modules` folder to find imported contracts with following flags:

- `--abi`: ABI specification of the contracts.
- `--base-path path`: Use the given path as the root of the source tree instead of the root of the filesystem.
- `--include-path path`: Make an additional source directory available to the default import callback. Use this option if you want to import contracts whose location is not fixed in relation to your main source tree; for example third-party libraries installed using a package manager. Can be used multiple times. Can only be used if base path has a non-empty value.
- `--output-dir path`: If given, creates one file per output component and contract/file at the specified directory.
- `--overwrite`: Overwrite existing files (used together with` --output-dir`).

```bash
solc --abi ./contracts/interfaces/IHelloWorld.sol -o ./abis --base-path . --include-path ./node_modules
```

This generates the ABI code under `./abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi`.

```
[
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "oldGreeting",
        "type": "string"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "newGreeting",
        "type": "string"
      }
    ],
    "name": "GreetingChanged",
    "type": "event"
  },
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "uint256",
        "name": "role",
        "type": "uint256"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "account",
        "type": "address"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "uint256",
        "name": "oldRole",
        "type": "uint256"
      }
    ],
    "name": "RoleSet",
    "type": "event"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "readAllowList",
    "outputs": [
      { "internalType": "uint256", "name": "role", "type": "uint256" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [],
    "name": "sayHello",
    "outputs": [
      { "internalType": "string", "name": "result", "type": "string" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setAdmin",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setEnabled",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "string", "name": "response", "type": "string" }
    ],
    "name": "setGreeting",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setManager",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setNone",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  }
]
```

As you can see the ABI also contains the `IAllowList` interface functions. This is because the `IHelloWorld` interface inherits from the `IAllowList` interface.

Note: The ABI must have named outputs in order to generate the precompile template.

Now that we have an ABI for the precompile gen tool to interact with, we can run the following command to generate our HelloWorld precompile files!

Let's go back to the root of the repository and run the PrecompileGen script helper:

```bash
cd ..
```

Both of these Subnet-EVM and Precompile-EVM have the same generate_precompile.sh script. The one in Precompile-EVM installs the script from Subnet-EVM and runs it.

```bash
./scripts/generate_precompile.sh --help

# output
Using branch: precompile-tutorial
NAME:
precompilegen - subnet-evm precompile generator tool

USAGE:
main [global options] command [command options] [arguments...]

VERSION:
1.10.26-stable

COMMANDS:
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:

    --abi value
          Path to the contract ABI json to generate, - for STDIN

    --out value
          Output folder for the generated precompile files, - for STDOUT (default =
          ./precompile/contracts/{pkg}). Test files won't be generated if STDOUT is used
    --pkg value
          Go package name to generate the precompile into (default = {type})
    --type value
          Struct name for the precompile (default = {abi file name})
MISC
    --help, -h                     (default: false)
          show help
    --version, -v                  (default: false)
          print the version
COPYRIGHT:
Copyright 2013-2022 The go-ethereum Authors
```
Now let's generate the precompile template files!
</Tab>
</Tabs>

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
In Subnet-EVM precompile implementations reside under the `./precompile/contracts` directory. Let's generate our precompile template in the `./precompile/contracts/helloworld` directory, where `helloworld` is the name of the Go package we want to generate the precompile into.

```bash
./scripts/generate_precompile.sh --abi ./contracts/abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi --type HelloWorld --pkg helloworld
```

This generates a precompile template files `contract.go`, `contract.abi`, `config.go`, `module.go`, `event.go` and `README.md` files. `README.md` explains general guidelines for precompile development. You should carefully read this file before modifying the precompile template.

```
There are some must-be-done changes waiting in the generated file. Each area requiring you to add your code is marked with CUSTOM CODE to make them easy to find and modify.
Additionally there are other files you need to edit to activate your precompile.
These areas are highlighted with comments "ADD YOUR PRECOMPILE HERE".
For testing take a look at other precompile tests in contract_test.go and config_test.go in other precompile folders.
General guidelines for precompile development:

1- Set a suitable config key in generated module.go. E.g: "yourPrecompileConfig"
2- Read the comment and set a suitable contract address in generated module.go. E.g:
ContractAddress = common.HexToAddress("ASUITABLEHEXADDRESS")
3- It is recommended to only modify code in the highlighted areas marked with "CUSTOM CODE STARTS HERE". Typically, custom codes are required in only those areas.
Modifying code outside of these areas should be done with caution and with a deep understanding of how these changes may impact the EVM.
4- If you have any event defined in your precompile, review the generated event.go file and set your event gas costs. You should also emit your event in your function in the contract.go file.
5- Set gas costs in generated contract.go
6- Force import your precompile package in precompile/registry/registry.go
7- Add your config unit tests under generated package config_test.go
8- Add your contract unit tests under generated package contract_test.go
9- Additionally you can add a full-fledged VM test for your precompile under plugin/vm/vm_test.go. See existing precompile tests for examples.
10- Add your solidity interface and test contract to contracts/contracts
11- Write solidity contract tests for your precompile in contracts/contracts/test
12- Write TypeScript DS-Test counterparts for your solidity tests in contracts/test
13- Create your genesis with your precompile enabled in tests/precompile/genesis/
14- Create e2e test for your solidity test in tests/precompile/solidity/suites.go
15- Run your e2e precompile Solidity tests with './scripts/run_ginkgo.sh`
```

Let's follow these steps and create our HelloWorld precompile.
</Tab>
<Tab value="Precompile-EVM">
For Precompile-EVM we don't need to put files under a deep directory structure. We can just generate the precompile template under its own directory via `--out ./helloworld` flag.

```bash
./scripts/generate_precompile.sh --abi ./contracts/abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi --type HelloWorld --pkg helloworld --out ./helloworld
```

This generates a precompile template files `contract.go`, `contract.abi`, `config.go`, `module.go`, `event.go` and `README.md` files. `README.md` explains general guidelines for precompile development. You should carefully read this file before modifying the precompile template.

```
There are some must-be-done changes waiting in the generated file. Each area requiring you to add your code is marked with CUSTOM CODE to make them easy to find and modify.
Additionally there are other files you need to edit to activate your precompile.
These areas are highlighted with comments "ADD YOUR PRECOMPILE HERE".
For testing take a look at other precompile tests in contract_test.go and config_test.go in other precompile folders.
General guidelines for precompile development:

1- Set a suitable config key in generated module.go. E.g: "yourPrecompileConfig"
2- Read the comment and set a suitable contract address in generated module.go. E.g:
ContractAddress = common.HexToAddress("ASUITABLEHEXADDRESS")
3- It is recommended to only modify code in the highlighted areas marked with "CUSTOM CODE STARTS HERE". Typically, custom codes are required in only those areas.
Modifying code outside of these areas should be done with caution and with a deep understanding of how these changes may impact the EVM.
4- If you have any event defined in your precompile, review the generated event.go file and set your event gas costs. You should also emit your event in your function in the contract.go file.
5- Set gas costs in generated contract.go
6- Force import your precompile package in precompile/registry/registry.go
7- Add your config unit tests under generated package config_test.go
8- Add your contract unit tests under generated package contract_test.go
9- Additionally you can add a full-fledged VM test for your precompile under plugin/vm/vm_test.go. See existing precompile tests for examples.
10- Add your solidity interface and test contract to contracts/contracts
11- Write solidity contract tests for your precompile in contracts/contracts/test
12- Write TypeScript DS-Test counterparts for your solidity tests in contracts/test
13- Create your genesis with your precompile enabled in tests/precompile/genesis/
14- Create e2e test for your solidity test in tests/precompile/solidity/suites.go
15- Run your e2e precompile Solidity tests with './scripts/run_ginkgo.sh`
```

Let's follow these steps and create our HelloWorld precompile!
</Tab>
</Tabs>

# Defining Your Precompile (/docs/lux-l1s/custom-precompiles/defining-precompile)

---
title: Defining Your Precompile
description: Now that we have autogenerated the template code required for our precompile, let's actually write the logic for the precompile itself.
---

## Setting Config Key

Let's jump to `helloworld/module.go` file first. This file contains the module definition for our precompile. You can see the `ConfigKey` is set to some default value of `helloWorldConfig`. This key should be unique to the precompile.

This config key determines which JSON key to use when reading the precompile's config from the JSON upgrade/genesis file. In this case, the config key is `helloWorldConfig` and the JSON config should look like this:

```json
{
  "helloWorldConfig": {
    "blockTimestamp": 0
		...
  }
}
```

## Setting Contract Address

In the `helloworld/module.go` you can see the `ContractAddress` is set to some default value. This should be changed to a suitable address for your precompile. The address should be unique to the precompile. There is a registry of precompile addresses under [`precompile/registry/registry.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/registry/registry.go).

A list of addresses is specified in the comments under this file. Modify the default value to be the next user available stateful precompile address. For forks of Subnet-EVM or Precompile-EVM, users should start at `0x0300000000000000000000000000000000000000` to ensure that their own modifications do not conflict with stateful precompiles that may be added to Subnet-EVM in the future. You should pick an address that is not already taken.

```go title="helloworld/module.go"
// This list is kept just for reference. The actual addresses defined in respective packages of precompiles.
// Note: it is important that none of these addresses conflict with each other or any other precompiles
// in core/vm/contracts.go.
// The first stateful precompiles were added in coreth to support nativeAssetCall and nativeAssetBalance. New stateful precompiles
// originating in coreth will continue at this prefix, so we reserve this range in subnet-evm so that they can be migrated into
// subnet-evm without issue.
// These start at the address: 0x0100000000000000000000000000000000000000 and will increment by 1.
// Optional precompiles implemented in subnet-evm start at 0x0200000000000000000000000000000000000000 and will increment by 1
// from here to reduce the risk of conflicts.
// For forks of subnet-evm, users should start at 0x0300000000000000000000000000000000000000 to ensure
// that their own modifications do not conflict with stateful precompiles that may be added to subnet-evm
// in the future.
// ContractDeployerAllowListAddress = common.HexToAddress("0x0200000000000000000000000000000000000000")
// ContractNativeMinterAddress      = common.HexToAddress("0x0200000000000000000000000000000000000001")
// TxAllowListAddress               = common.HexToAddress("0x0200000000000000000000000000000000000002")
// FeeManagerAddress                = common.HexToAddress("0x0200000000000000000000000000000000000003")
// RewardManagerAddress             = common.HexToAddress("0x0200000000000000000000000000000000000004")
// HelloWorldAddress                = common.HexToAddress("0x0300000000000000000000000000000000000000")
// ADD YOUR PRECOMPILE HERE
// {YourPrecompile}Address          = common.HexToAddress("0x03000000000000000000000000000000000000??")
```

Don't forget to update the actual variable `ContractAddress` in `module.go` to the address you chose. It should look like this:

```go title="helloworld/module.go"
// ContractAddress is the defined address of the precompile contract.
// This should be unique across all precompile contracts.
// See params/precompile_modules.go for registered precompile contracts and more information.
var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000000")
```

Now when Subnet-EVM sees the `helloworld.ContractAddress` as input when executing [`CALL`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L251), [`CALLCODE`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L341), [`DELEGATECALL`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L392), [`STATICCALL`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L435), it can run the precompile if the precompile is enabled.

## Adding Custom Code

Search (`CTRL F`) throughout the file with `CUSTOM CODE STARTS HERE` to find the areas in the precompile package that you need to modify. You should start with the reference imports code block.

### Module File

The module file contains fundamental information about the precompile. This includes the key for the precompile, the address of the precompile, and a configurator. This file is located at [`./precompile/helloworld/module.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/module.go) for Subnet-EVM and [./helloworld/module.go](https://github.com/luxfi/precompile-evm/blob/hello-world-example/helloworld/module.go) for Precompile-EVM.

This file defines the module for the precompile. The module is used to register the precompile to the precompile registry. The precompile registry is used to read configs and enable the precompile. Registration is done in the `init()` function of the module file. `MakeConfig()` is used to create a new instance for the precompile config. This will be used in custom Unmarshal/Marshal logic. You don't need to override these functions.

#### Configure()

Module file contains a `configurator` which implements the `contract.Configurator` interface. This interface includes a `Configure()` function used to configure the precompile and set the initial state of the precompile. This function is called when the precompile is enabled. This is typically used to read from a given config in upgrade/genesis JSON and sets the initial state of the precompile accordingly. This function also calls `AllowListConfig.Configure()` to invoke AllowList configuration as the last step. You should keep it as it is if you want to use AllowList. You can modify this function for your custom logic. You can circle back to this function later after you have finalized the implementation of the precompile config.

### Config File

The config file contains the config for the precompile. This file is located at [`./precompile/helloworld/config.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/config.go) for Subnet-EVM and [./helloworld/config.go](https://github.com/luxfi/precompile-evm/blob/hello-world-example/helloworld/config.go) for Precompile-EVM. This file contains the `Config` struct, which implements `precompileconfig.Config` interface. It has some embedded structs like `precompileconfig.Upgrade`. `Upgrade` is used to enable upgrades for the precompile. It contains the `BlockTimestamp` and `Disable` to enable/disable upgrades. `BlockTimestamp` is the timestamp of the block when the upgrade will be activated. `Disable` is used to disable the upgrade. If you use `AllowList` for the precompile, there is also `allowlist.AllowListConfig` embedded in the `Config` struct. `AllowListConfig` is used to specify initial roles for specified addresses. If you have any custom fields in your precompile config, you can add them here. These custom fields will be read from upgrade/genesis JSON and set in the precompile config.

```go title="precompile/helloworld/config.go"
// Config implements the precompileconfig.Config interface and
// adds specific configuration for HelloWorld.
type Config struct {
	allowlist.AllowListConfig
	precompileconfig.Upgrade
}
```

#### Verify()

`Verify()` is called on startup and an error is treated as fatal. Generated code contains a call to `AllowListConfig.Verify()` to verify the `AllowListConfig`. You can leave that as is and start adding your own custom verify code after that.

We can leave this function as is right now because there is no invalid custom configuration for the `Config`.

```go title="precompile/helloworld/config.go"
// Verify tries to verify Config and returns an error accordingly.
func (c *Config) Verify() error {
	// Verify AllowList first
	if err := c.AllowListConfig.Verify(); err != nil {
		return err
	}

	// CUSTOM CODE STARTS HERE
	// Add your own custom verify code for Config here
	// and return an error accordingly
	return nil
}
```

#### Equal()

Next, we see is `Equal()`. This function determines if two precompile configs are equal. This is used to determine if the precompile needs to be upgraded. There is some default code that is generated for checking `Upgrade` and `AllowListConfig` equality.

```go title="precompile/helloworld/config.go"
// Equal returns true if [s] is a [*Config] and it has been configured identical to [c].
func (c *Config) Equal(s precompileconfig.Config) bool {
	// typecast before comparison
	other, ok := (s).(*Config)
	if !ok {
		return false
	}
	// CUSTOM CODE STARTS HERE
	// modify this boolean accordingly with your custom Config, to check if [other] and the current [c] are equal
	// if Config contains only Upgrade  and AllowListConfig  you can skip modifying it.
	equals := c.Upgrade.Equal(&other.Upgrade) && c.AllowListConfig.Equal(&other.AllowListConfig)
	return equals
}
```

We can leave this function as is since we check `Upgrade` and `AllowListConfig` for equality which are the only fields that `Config` struct has.

### Modify Configure()

We can now circle back to `Configure()` in `module.go` as we finished implementing `Config` struct. This function configures the `state` with the initial configuration at`blockTimestamp` when the precompile is enabled.

In the HelloWorld example, we want to set up a default key-value mapping in the state where the key is `storageKey` and the value is `Hello World!`. The `StateDB` allows us to store a key-value mapping of 32-byte hashes. The below code snippet can be copied and pasted to overwrite the default `Configure()` code.

```go title="precompile/helloworld/module.go"
const defaultGreeting = "Hello World!"

// Configure configures [state] with the given [cfg] precompileconfig.
// This function is called by the EVM once per precompile contract activation.
// You can use this function to set up your precompile contract's initial state,
// by using the [cfg] config and [state] stateDB.
func (*configurator) Configure(chainConfig contract.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, _ contract.BlockContext) error {
	config, ok := cfg.(*Config)
	if !ok {
		return fmt.Errorf("incorrect config %T: %v", config, config)
	}
	// CUSTOM CODE STARTS HERE

	// This will be called in the first block where HelloWorld stateful precompile is enabled.
	// 1) If BlockTimestamp is nil, this will not be called
	// 2) If BlockTimestamp is 0, this will be called while setting up the genesis block
	// 3) If BlockTimestamp is 1000, this will be called while processing the first block
	// whose timestamp is >= 1000
	//
	// Set the initial value under [common.BytesToHash([]byte("storageKey")] to "Hello World!"
	StoreGreeting(state, defaultGreeting)
	// AllowList is activated for this precompile. Configuring allowlist addresses here.
	return config.AllowListConfig.Configure(state, ContractAddress)
}
```

### Event File

The event file contains the events that the precompile can emit. This file is located at [`./precompile/helloworld/event.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/event.go) for Subnet-EVM and [./helloworld/event.go](https://github.com/luxfi/precompile-evm/blob/hello-world-example/helloworld/event.go) for Precompile-EVM. The file begins with a comment about events and how they can be emitted:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```go title="precompile/helloworld/event.go"
/* NOTE: Events can only be emitted in state-changing functions. So you cannot use events in read-only (view) functions.
Events are generally emitted at the end of a state-changing function with AddLog method of the StateDB. The AddLog method takes 4 arguments:
	1. Address of the contract that emitted the event.
	2. Topic hashes of the event.
	3. Encoded non-indexed data of the event.
	4. Block number at which the event was emitted.
The first argument is the address of the contract that emitted the event.
Topics can be at most 4 elements, the first topic is the hash of the event signature and the rest are the indexed event arguments. There can be at most 3 indexed arguments.
Topics cannot be fully unpacked into their original values since they're 32-bytes hashes.
The non-indexed arguments are encoded using the ABI encoding scheme. The non-indexed arguments can be unpacked into their original values.
Before packing the event, you need to calculate the gas cost of the event. The gas cost of an event is the base gas cost + the gas cost of the topics + the gas cost of the non-indexed data.
See Get{EvetName}EventGasCost functions for more details.
You can use the following code to emit an event in your state-changing precompile functions (generated packer might be different):*/

topics, data, err := PackMyEvent(
	topic1,
	topic2,
	data1,
	data2,
)
if err != nil {
	return nil, remainingGas, err
}
accessibleState.GetStateDB().AddLog(&types.Log{
	Address:     ContractAddress,
	Topics:      topics,
	Data:        data,
	BlockNumber: accessibleState.GetBlockContext().Number().Uint64(),
})
```
</Tab>
<Tab value="Precompile-EVM">
```go title="precompile/helloworld/event.go"
/* NOTE: Events can only be emitted in state-changing functions. So you cannot use events in read-only (view) functions.
Events are generally emitted at the end of a state-changing function with AddLog method of the StateDB. The AddLog method takes 4 arguments:
	1. Address of the contract that emitted the event.
	2. Topic hashes of the event.
	3. Encoded non-indexed data of the event.
	4. Block number at which the event was emitted.
The first argument is the address of the contract that emitted the event.
Topics can be at most 4 elements, the first topic is the hash of the event signature and the rest are the indexed event arguments. There can be at most 3 indexed arguments.
Topics cannot be fully unpacked into their original values since they're 32-bytes hashes.
The non-indexed arguments are encoded using the ABI encoding scheme. The non-indexed arguments can be unpacked into their original values.
Before packing the event, you need to calculate the gas cost of the event. The gas cost of an event is the base gas cost + the gas cost of the topics + the gas cost of the non-indexed data.
See Get{EvetName}EventGasCost functions for more details.
You can use the following code to emit an event in your state-changing precompile functions (generated packer might be different):*/

topics, data, err := PackMyEvent(
	topic1,
	topic2,
	data1,
	data2,
)
if err != nil {
	return nil, remainingGas, err
}
accessibleState.GetStateDB().AddLog(
	ContractAddress,
	topics,
	data,
	accessibleState.GetBlockContext().Number().Uint64(),
)
```
</Tab>
</Tabs>

In this file you should set your event's gas cost and implement the `Get{EventName}EventGasCost` function. This function should take the data you want to emit and calculate the gas cost. In this example we defined our event as follow, and plan to emit it in the `setGreeting` function:

```go
event GreetingChanged(address indexed sender, string oldGreeting, string newGreeting);
```

We used arbitrary strings as non-indexed event data, remind that each emitted event is stored on chain, thus charging right amount is critical. We calculated gas cost according to the length of the string to make sure we're charging right amount of gas. If you're sure that you're dealing with a fixed length data, you can use a fixed gas cost for your event. We will show how events can be emitted under the Contract File section.

### Contract File

The contract file contains the functions of the precompile contract that will be called by the EVM. The file is located at [`./precompile/helloworld/contract.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract.go) for Subnet-EVM and [./helloworld/contract.go](https://github.com/luxfi/precompile-evm/blob/hello-world-example/helloworld/contract.go) for Precompile-EVM. Since we use `IAllowList` interface there will be auto-generated code for `AllowList` functions like below:

```go title="precompile/helloworld/contract.go"
// GetHelloWorldAllowListStatus returns the role of [address] for the HelloWorld list.
func GetHelloWorldAllowListStatus(stateDB contract.StateDB, address common.Address) allowlist.Role {
	return allowlist.GetAllowListStatus(stateDB, ContractAddress, address)
}

// SetHelloWorldAllowListStatus sets the permissions of [address] to [role] for the
// HelloWorld list. Assumes [role] has already been verified as valid.
// This stores the [role] in the contract storage with address [ContractAddress]
// and [address] hash. It means that any reusage of the [address] key for different value
// conflicts with the same slot [role] is stored.
// Precompile implementations must use a different key than [address] for their storage.
func SetHelloWorldAllowListStatus(stateDB contract.StateDB, address common.Address, role allowlist.Role) {
	allowlist.SetAllowListRole(stateDB, ContractAddress, address, role)
}
```

These will be helpful to use AllowList precompile helper in our functions.

#### Packers and Unpackers

There are also auto-generated Packers and Unpackers for the ABI. These will be used in `sayHello` and `setGreeting` functions to comfort the ABI. These functions are auto-generated and will be used in necessary places accordingly. You don't need to worry about how to deal with them, but it's good to know what they are.

Note: There were few changes to precompile packers with Durango. In this example we assumed that the HelloWorld precompile contract has been deployed before Durango. We need to activate this condition only after Durango. If this is a new precompile and never deployed before Durango, you can activate it immediately by removing the if condition.

Each input to a precompile contract function has it's own `Unpacker` function as follows (if deployed before Durango):

```go title="precompile/helloworld/contract.go"
// UnpackSetGreetingInput attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
// if [useStrictMode] is true, it will return an error if the length of [input] is not [common.HashLength]
func UnpackSetGreetingInput(input []byte, useStrictMode bool) (string, error) {
	// Initially we had this check to ensure that the input was the correct length.
	// However solidity does not always pack the input to the correct length, and allows
	// for extra padding bytes to be added to the end of the input. Therefore, we have removed
	// this check with the Durango. We still need to keep this check for backwards compatibility.
	if useStrictMode && len(input) > common.HashLength {
		return "", ErrInputExceedsLimit
	}
	res, err := HelloWorldABI.UnpackInput("setGreeting", input, useStrictMode)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}
```

If this is a new precompile that will be deployed after Durango, you can skip strict mode handling and use false:

```go title="precompile/helloworld/contract.go"
func UnpackSetGreetingInput(input []byte) (string, error) {
	res, err := HelloWorldABI.UnpackInput("setGreeting", input, false)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}
```

The ABI is a binary format and the input to the precompile contract function is a byte array. The `Unpacker` function converts this input to a more easy-to-use format so that we can use it in our function.

Similarly, there is a `Packer` function for each output of a precompile contract function as follows:

```go title="precompile/helloworld/contract.go"
// PackSayHelloOutput attempts to pack given result of type string
// to conform the ABI outputs.
func PackSayHelloOutput(result string) ([]byte, error) {
	return HelloWorldABI.PackOutput("sayHello", result)
}
```

This function converts the output of the function to a byte array that conforms to the ABI and can be returned to the EVM as a result.

#### Modify sayHello()

The next place to modify is in our `sayHello()` function. In a previous step, we created the `IHelloWorld.sol` interface with two functions `sayHello()` and `setGreeting()`. We finally get to implement them here. If any contract calls these functions from the interface, the below function gets executed. This function is a simple getter function.

In `Configure()` we set up a mapping with the key as `storageKey` and the value as `Hello World!`. In this function, we will be returning whatever value is at `storageKey`. The below code snippet can be copied and pasted to overwrite the default `setGreeting` code.

First, we add a helper function to get the greeting value from the stateDB, this will be helpful when we test our contract. We will use the `storageKeyHash` to store the value in the Contract's reserved storage in the stateDB.

```go title="precompile/helloworld/contract.go"
var (
  // storageKeyHash is the hash of the storage key "storageKey" in the contract storage.
	// This is used to store the value of the greeting in the contract storage.
	// It is important to use a unique key here to avoid conflicts with other storage keys
	// like addresses, AllowList, etc.
	storageKeyHash = common.BytesToHash([]byte("storageKey"))
)
// GetGreeting returns the value of the storage key "storageKey" in the contract storage,
// with leading zeroes trimmed.
// This function is mostly used for tests.
func GetGreeting(stateDB contract.StateDB) string {
	// Get the value set at recipient
	value := stateDB.GetState(ContractAddress, storageKeyHash)
	return string(common.TrimLeftZeroes(value.Bytes()))
}
```

Now we can modify the `sayHello` function to return the stored value.

```go title="precompile/helloworld/contract.go"
func sayHello(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SayHelloGasCost); err != nil {
		return nil, 0, err
	}
	// CUSTOM CODE STARTS HERE

	// Get the current state
	currentState := accessibleState.GetStateDB()
	// Get the value set at recipient
	value := GetGreeting(currentState)
	packedOutput, err := PackSayHelloOutput(value)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

#### Modify setGreeting()

`setGreeting()` function is a simple setter function. It takes in `input` and we will set that as the value in the state mapping with the key as `storageKey`. It also checks if the VM running the precompile is in read-only mode. If it is, it returns an error. At the end of a successful execution, it will emit `GreetingChanged` event.

There is also a generated `AllowList` code in that function. This generated code checks if the caller address is eligible to perform this state-changing operation. If not, it returns an error.

Let's add the helper function to set the greeting value in the stateDB, this will be helpful when we test our contract.

```go title="precompile/helloworld/contract.go"
// StoreGreeting sets the value of the storage key "storageKey" in the contract storage.
func StoreGreeting(stateDB contract.StateDB, input string) {
	inputPadded := common.LeftPadBytes([]byte(input), common.HashLength)
	inputHash := common.BytesToHash(inputPadded)

	stateDB.SetState(ContractAddress, storageKeyHash, inputHash)
}
```

The below code snippet can be copied and pasted to overwrite the default `setGreeting()` code.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```go title="precompile/helloworld/contract.go"
func setGreeting(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SetGreetingGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// do not use strict mode after Durango
	useStrictMode := !contract.IsDurangoActivated(accessibleState)
	// attempts to unpack [input] into the arguments to the SetGreetingInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSetGreetingInput(input, useStrictMode)
	if err != nil {
		return nil, remainingGas, err
	}
	// Allow list is enabled and SetGreeting is a state-changer function.
	// This part of the code restricts the function to be called only by enabled/admin addresses in the allow list.
	// You can modify/delete this code if you don't want this function to be restricted by the allow list.
	stateDB := accessibleState.GetStateDB()
	// Verify that the caller is in the allow list and therefore has the right to call this function.
	callerStatus := allowlist.GetAllowListStatus(stateDB, ContractAddress, caller)
	if !callerStatus.IsEnabled() {
		return nil, remainingGas, fmt.Errorf("%w: %s", ErrCannotSetGreeting, caller)
	}
	// allow list code ends here.

	// CUSTOM CODE STARTS HERE
	// With Durango, you can emit an event in your state-changing precompile functions.
	// Note: If you have been using the precompile before Durango, you should activate it only after Durango.
	// Activating this code before Durango will result in a consensus failure.
	// If this is a new precompile and never deployed before Durango, you can activate it immediately by removing
	// the if condition.
	// We will first read the old greeting. So we should charge the gas for reading the storage.
	if remainingGas, err = contract.DeductGas(remainingGas, contract.ReadGasCostPerSlot); err != nil {
		return nil, 0, err
	}
	oldGreeting := GetGreeting(stateDB)

	eventData := GreetingChangedEventData{
		OldGreeting: oldGreeting,
		NewGreeting: inputStruct,
	}
	topics, data, err := PackGreetingChangedEvent(caller, eventData)
	if err != nil {
		return nil, remainingGas, err
	}
	// Charge the gas for emitting the event.
	eventGasCost := GetGreetingChangedEventGasCost(eventData)
	if remainingGas, err = contract.DeductGas(remainingGas, eventGasCost); err != nil {
		return nil, 0, err
	}

	// Emit the event
	stateDB.AddLog(&types.Log{
		Address:     ContractAddress,
		Topics:      topics,
		Data:        data,
		BlockNumber: accessibleState.GetBlockContext().Number().Uint64(),
	})

	// setGreeting is the execution function
	// "SetGreeting(name string)" and sets the storageKey
	// in the string returned by hello world
	StoreGreeting(stateDB, inputStruct)

	// This function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```
</Tab>
<Tab value="Precompile-EVM">
```go title="precompile/helloworld/contract.go"
func setGreeting(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SetGreetingGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// do not use strict mode after Durango
	useStrictMode := !contract.IsDurangoActivated(accessibleState)
	// attempts to unpack [input] into the arguments to the SetGreetingInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSetGreetingInput(input, useStrictMode)
	if err != nil {
		return nil, remainingGas, err
	}
	// Allow list is enabled and SetGreeting is a state-changer function.
	// This part of the code restricts the function to be called only by enabled/admin addresses in the allow list.
	// You can modify/delete this code if you don't want this function to be restricted by the allow list.
	stateDB := accessibleState.GetStateDB()
	// Verify that the caller is in the allow list and therefore has the right to call this function.
	callerStatus := allowlist.GetAllowListStatus(stateDB, ContractAddress, caller)
	if !callerStatus.IsEnabled() {
		return nil, remainingGas, fmt.Errorf("%w: %s", ErrCannotSetGreeting, caller)
	}
	// allow list code ends here.

	// CUSTOM CODE STARTS HERE
	// With Durango, you can emit an event in your state-changing precompile functions.
	// Note: If you have been using the precompile before Durango, you should activate it only after Durango.
	// Activating this code before Durango will result in a consensus failure.
	// If this is a new precompile and never deployed before Durango, you can activate it immediately by removing
	// the if condition.
	// We will first read the old greeting. So we should charge the gas for reading the storage.
	if remainingGas, err = contract.DeductGas(remainingGas, contract.ReadGasCostPerSlot); err != nil {
		return nil, 0, err
	}
	oldGreeting := GetGreeting(stateDB)

	eventData := GreetingChangedEventData{
		OldGreeting: oldGreeting,
		NewGreeting: inputStruct,
	}
	topics, data, err := PackGreetingChangedEvent(caller, eventData)
	if err != nil {
		return nil, remainingGas, err
	}
	// Charge the gas for emitting the event.
	eventGasCost := GetGreetingChangedEventGasCost(eventData)
	if remainingGas, err = contract.DeductGas(remainingGas, eventGasCost); err != nil {
		return nil, 0, err
	}

	// Emit the event
	stateDB.AddLog(&types.Log{
		Address:     ContractAddress,
		Topics:      topics,
		Data:        data,
		BlockNumber: accessibleState.GetBlockContext().Number().Uint64(),
	})

	// setGreeting is the execution function
	// "SetGreeting(name string)" and sets the storageKey
	// in the string returned by hello world
	StoreGreeting(stateDB, inputStruct)

	// This function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```
</Tab>
</Tabs>

<Callout title="Note">
Precompile events introduced with Durango. In this example we assumed that the `HelloWorld` precompile contract has been deployed before Durango.

If this is a new precompile and it will be deployed after Durango, you can activate it immediately by removing the Durango if condition (`contract.IsDurangoActivated(accessibleState)`).
</Callout>

### Setting Gas Costs

Setting gas costs for functions is very important and should be done carefully. If the gas costs are set too low, then functions can be abused and can cause DoS attacks. If the gas costs are set too high, then the contract will be too expensive to run.

Subnet-EVM has some predefined gas costs for write and read operations in [`precompile/contract/utils.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contract/utils.go#L19-L20). In order to provide a baseline for gas costs, we have set the following gas costs.

```go title="precompile/contract/utils.go"
// Gas costs for stateful precompiles
const (
	WriteGasCostPerSlot = 20_000
	ReadGasCostPerSlot  = 5_000
)
```

- `WriteGasCostPerSlot` is the cost of one write such as modifying a state storage slot.
- `ReadGasCostPerSlot` is the cost of reading a state storage slot.

This should be in your gas cost estimations based on how many times the precompile function does a read or a write. For example, if the precompile modifies the state slot of its precompile address twice then the gas cost for that function would be `40_000`. However, if the precompile does additional operations and requires more computational power, then you should increase the gas costs accordingly.

On top of these gas costs, we also have to account for the gas costs of AllowList gas costs. These are the gas costs of reading and writing permissions for addresses in AllowList. These are defined under Subnet-EVM's [`precompile/allowlist/allowlist.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/allowlist/allowlist.go#L28-L29).

By default, these are added to the default gas costs of the state-change functions (SetGreeting) of the precompile. Meaning that these functions will cost an additional `ReadAllowListGasCost` in order to read permissions from the storage. If you don't plan to read permissions from the storage then you can omit these.

Now going back to our `/helloworld/contract.go`, we can modify our precompile function gas costs. Please search (`CTRL F`) `SET A GAS COST HERE` to locate the default gas cost code.

```go title="helloworld/contract.go"
SayHelloGasCost    uint64 = 0                                  // SET A GAS COST HERE
SetGreetingGasCost uint64 = 0 + allowlist.ReadAllowListGasCost // SET A GAS COST HERE
```

We get and set our greeting with `sayHello()` and `setGreeting()` in one slot respectively so we can define the gas costs as follows. We also read permissions from the AllowList in `setGreeting()` so we keep `allowlist.ReadAllowListGasCost`.

```go title="helloworld/contract.go"
SayHelloGasCost    uint64 = contract.ReadGasCostPerSlot
SetGreetingGasCost uint64 = contract.WriteGasCostPerSlot + allowlist.ReadAllowListGasCost
```

## Registering Your Precompile

We should register our precompile package to the Subnet-EVM to be discovered by other packages. Our `Module` file contains an `init()` function that registers our precompile. `init()` is called when the package is imported. We should register our precompile in a common package so that it can be imported by other packages.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
For Subnet-EVM we have a precompile registry under [`/precompile/registry/registry.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/registry/registry.go). This registry force-imports precompiles from other packages, for example:

```go title="precompile/registry/registry.go"
// Force imports of each precompile to ensure each precompile's init function runs and registers itself
// with the registry.
import (
	_ "github.com/luxfi/subnet-evm/precompile/contracts/deployerallowlist"

	_ "github.com/luxfi/subnet-evm/precompile/contracts/nativeminter"

	_ "github.com/luxfi/subnet-evm/precompile/contracts/txallowlist"

	_ "github.com/luxfi/subnet-evm/precompile/contracts/feemanager"

	_ "github.com/luxfi/subnet-evm/precompile/contracts/rewardmanager"

	_ "github.com/luxfi/subnet-evm/precompile/contracts/helloworld"
	// ADD YOUR PRECOMPILE HERE
	// _ "github.com/luxfi/subnet-evm/precompile/contracts/yourprecompile"
)
```

The registry itself also force-imported by the [\`/plugin/evm/vm.go](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/plugin/evm/vm.go#L50). This ensures that the registry is imported and the precompiles are registered.
</Tab>

<Tab value="Precompile-EVM">
For Precompile-EVM there is a `plugin/main.go` file in Precompile-EVM that orchestrates this precompile registration.

```go title="plugin/main.go"
// (c) 2019-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package main

import (
	"fmt"

	"github.com/luxfi/luxgo/version"
	"github.com/luxfi/subnet-evm/plugin/evm"
	"github.com/luxfi/subnet-evm/plugin/runner"

	// Each precompile generated by the precompilegen tool has a self-registering init function
	// that registers the precompile with the subnet-evm. Importing the precompile package here
	// will cause the precompile to be registered with the subnet-evm.
	_ "github.com/luxfi/precompile-evm/helloworld"
	// ADD YOUR PRECOMPILE HERE
	//_ "github.com/luxfi/precompile-evm/{yourprecompilepkg}"
)
```
</Tab>
</Tabs>


# Writing Test Cases (/docs/lux-l1s/custom-precompiles/defining-test-cases)

---
title: Writing Test Cases
description: In this section, we will go over the different ways we can write test cases for our stateful precompile.
---

## Adding Config Tests

Precompile generation tool generates skeletons for unit tests as well. Generated config tests will be under [`./precompile/contracts/helloworld/config_test.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/config_test.go) for Subnet-EVM and [`./helloworld/config_test.go`](https://github.com/luxfi/precompile-evm/blob/hello-world-example/helloworld/config_test.go) for Precompile-EVM. There are mainly two functions we need to test: `Verify` and `Equal`. `Verify` checks if the precompile is configured correctly. `Equal` checks if the precompile is equal to another precompile. Generated `Verify` tests contain a valid case.

You can add more invalid cases depending on your implementation. `Equal` tests generate some invalid cases to test different timestamps, types, and AllowList cases. You can check each `config_test.go` files for other precompiles under the Subnet-EVM's [`./precompile/contracts`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/) directory for more examples.

## Adding Contract Tests

The tool also generates contract tests to make sure our precompile is working correctly. Generated tests include cases to test allow list capabilities, gas costs, and calling functions in read-only mode. You can check other `contract_test.go` files in the `/precompile/contracts`. Hello World contract tests will be under [`./precompile/contracts/helloworld/contract_test.go`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract_test.go) for Subnet-EVM and [`./helloworld/contract_test.go`](https://github.com/luxfi/precompile-evm/blob/hello-world-example/helloworld/contract_test.go) for Precompile-EVM.

We will also add more test to cover functionalities of `sayHello()` and `setGreeting()`. Contract tests are defined in a standard structure that each test can customize to their needs. The test structure is as follows:

```go
// PrecompileTest is a test case for a precompile
type PrecompileTest struct {
	// Caller is the address of the precompile caller
	Caller common.Address
	// Input the raw input bytes to the precompile
	Input []byte
	// InputFn is a function that returns the raw input bytes to the precompile
	// If specified, Input will be ignored.
	InputFn func(t *testing.T) []byte
	// SuppliedGas is the amount of gas supplied to the precompile
	SuppliedGas uint64
	// ReadOnly is whether the precompile should be called in read only
	// mode. If true, the precompile should not modify the state.
	ReadOnly bool
	// Config is the config to use for the precompile
	// It should be the same precompile config that is used in the
	// precompile's configurator.
	// If nil, Configure will not be called.
	Config precompileconfig.Config
	// BeforeHook is called before the precompile is called.
	BeforeHook func(t *testing.T, state contract.StateDB)
	// AfterHook is called after the precompile is called.
	AfterHook func(t *testing.T, state contract.StateDB)
	// ExpectedRes is the expected raw byte result returned by the precompile
	ExpectedRes []byte
	// ExpectedErr is the expected error returned by the precompile
	ExpectedErr string
	// BlockNumber is the block number to use for the precompile's block context
	BlockNumber int64
}
```

Each test can populate the fields of the `PrecompileTest` struct to customize the test. This test uses an AllowList helper function `allowlist.RunPrecompileWithAllowListTests(t, Module, state.NewTestStateDB, tests)` which can run all specified tests plus AllowList test suites. If you don't plan to use AllowList, you can directly run them as follows:

```go
	for name, test := range tests {
		t.Run(name, func(t *testing.T) {
			test.Run(t, module, newStateDB(t))
		})
	}
```

## Adding VM Tests (Optional)

This is only applicable for direct Subnet-EVM forks as test files are not directly exported in Golang. If you use Precompile-EVM you can skip this step.

VM tests are tests that run the precompile by calling it through the Subnet-EVM. These are the most comprehensive tests that we can run. If your precompile modifies how the Subnet-EVM works, for example changing blockchain rules, you should add a VM test. For example, you can take a look at the `TestRewardManagerPrecompileSetRewardAddress` function in [here](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/plugin/evm/vm_test.go#L2772).

For this Hello World example, we don't modify any Subnet-EVM rules, so we don't need to add any VM tests.

## Adding Solidity Test Contracts

Let's add our test contract to `./contracts/contracts`. This smart contract lets us interact with our precompile! We cast the `HelloWorld` precompile address to the `IHelloWorld` interface. In doing so, `helloWorld` is now a contract of type `IHelloWorld` and when we call any functions on that contract, we will be redirected to the HelloWorld precompile address.

The below code snippet can be copied and pasted into a new file called `ExampleHelloWorld.sol`:

```go
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "./IHelloWorld.sol";

// ExampleHelloWorld shows how the HelloWorld precompile can be used in a smart contract.
contract ExampleHelloWorld {
  address constant HELLO_WORLD_ADDRESS =
    0x0300000000000000000000000000000000000000;
  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);

  function sayHello() public view returns (string memory) {
    return helloWorld.sayHello();
  }

  function setGreeting(string calldata greeting) public {
    helloWorld.setGreeting(greeting);
  }
}
```

<Callout type="warn">
Hello World Precompile is a different contract than ExampleHelloWorld and has a different address. Since the precompile uses AllowList for a permissioned access, any call to the precompile including from ExampleHelloWorld will be denied unless the caller is added to the AllowList.
</Callout>

Please note that this contract is simply a wrapper and is calling the precompile functions. The reason why we add another example smart contract is to have a simpler stateless tests.

For the test contract we write our test in `./contracts/test/ExampleHelloWorldTest.sol`.
<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "../ExampleHelloWorld.sol";
import "../interfaces/IHelloWorld.sol";
import "./AllowListTest.sol";

contract ExampleHelloWorldTest is AllowListTest {
  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);

  function step_getDefaultHelloWorld() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    assertEq(example.sayHello(), "Hello World!");
  }

  function step_doesNotSetGreetingBeforeEnabled() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    try example.setGreeting("testing") {
      assertTrue(false, "setGreeting should fail");
    } catch {}
  }

  function step_setAndGetGreeting() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    helloWorld.setEnabled(exampleAddress);
    assertRole(
      helloWorld.readAllowList(exampleAddress),
      AllowList.Role.Enabled
    );
    string memory greeting = "testgreeting";
    example.setGreeting(greeting);
    assertEq(example.sayHello(), greeting);
  }
}
```
</Tab>
<Tab value="Precompile-EVM">
For Precompile-EVM, you should import AllowListTest with `@luxfi/subnet-evm-contracts` NPM package:

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "../ExampleHelloWorld.sol";
import "../interfaces/IHelloWorld.sol";
import "@luxfi/subnet-evm-contracts/contracts/test/AllowListTest.sol";

contract ExampleHelloWorldTest is AllowListTest {
  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);

  function step_getDefaultHelloWorld() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    assertEq(example.sayHello(), "Hello World!");
  }

  function step_doesNotSetGreetingBeforeEnabled() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    try example.setGreeting("testing") {
      assertTrue(false, "setGreeting should fail");
    } catch {}
  }

  function step_setAndGetGreeting() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    helloWorld.setEnabled(exampleAddress);
    assertRole(
      helloWorld.readAllowList(exampleAddress),
      AllowList.Role.Enabled
    );
    string memory greeting = "testgreeting";
    example.setGreeting(greeting);
    assertEq(example.sayHello(), greeting);
  }
}
```

</Tab>
</Tabs>

## Adding DS-Test Case

We can now trigger this test contract via `hardhat` tests. The test script uses Subnet-EVM's `test` framework test in `./contracts/test`. You can find more information about the test framework [here](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/contracts/test/utils.ts). We also can test the events emitted by the precompile. The test script looks like this:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
The test script looks like this:

```go
// (c) 2019-2022, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

import { expect } from "chai";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers";
import { Contract } from "ethers";
import { ethers } from "hardhat";
import { test } from "./utils";

// make sure this is always an admin for hello world precompile
const ADMIN_ADDRESS = "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC";
const HELLO_WORLD_ADDRESS = "0x0300000000000000000000000000000000000000";

describe("ExampleHelloWorldTest", function () {
  this.timeout("30s");

  beforeEach("Setup DS-Test contract", async function () {
    const signer = await ethers.getSigner(ADMIN_ADDRESS);
    const helloWorldPromise = ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      signer
    );

    return ethers
      .getContractFactory("ExampleHelloWorldTest", { signer })
      .then((factory) => factory.deploy())
      .then((contract) => {
        this.testContract = contract;
        return contract.deployed().then(() => contract);
      })
      .then(() => Promise.all([helloWorldPromise]))
      .then(([helloWorld]) => helloWorld.setAdmin(this.testContract.address))
      .then((tx) => tx.wait());
  });

  test("should gets default hello world", ["step_getDefaultHelloWorld"]);

  test(
    "should not set greeting before enabled",
    "step_doesNotSetGreetingBeforeEnabled"
  );

  test(
    "should set and get greeting with enabled account",
    "step_setAndGetGreeting"
  );
});

describe("IHelloWorld events", function () {
  let owner: SignerWithAddress;
  let contract: Contract;
  let defaultGreeting = "Hello, World!";
  before(async function () {
    owner = await ethers.getSigner(ADMIN_ADDRESS);
    contract = await ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      owner
    );

    // reset greeting
    let tx = await contract.setGreeting(defaultGreeting);
    await tx.wait();
  });

  it("should emit GreetingChanged event", async function () {
    let newGreeting = "helloprecompile";
    await expect(contract.setGreeting(newGreeting))
      .to.emit(contract, "GreetingChanged")
      .withArgs(
        owner.address,
        // old greeting
        defaultGreeting,
        // new greeting
        newGreeting
      );
  });
});
```
</Tab>
<Tab value="Precompile-EVM">
The test script looks like this:

```go 
// (c) 2019-2022, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

import { expect } from "chai";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers";
import { Contract } from "ethers";
import { ethers } from "hardhat";
import { test } from "@luxfi/subnet-evm-contracts";

// make sure this is always an admin for hello world precompile
const ADMIN_ADDRESS = "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC";
const HELLO_WORLD_ADDRESS = "0x0300000000000000000000000000000000000000";

describe("ExampleHelloWorldTest", function () {
  this.timeout("30s");

  beforeEach("Setup DS-Test contract", async function () {
    const signer = await ethers.getSigner(ADMIN_ADDRESS);
    const helloWorldPromise = ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      signer
    );

    return ethers
      .getContractFactory("ExampleHelloWorldTest", { signer })
      .then((factory) => factory.deploy())
      .then((contract) => {
        this.testContract = contract;
        return contract.deployed().then(() => contract);
      })
      .then(() => Promise.all([helloWorldPromise]))
      .then(([helloWorld]) => helloWorld.setAdmin(this.testContract.address))
      .then((tx) => tx.wait());
  });

  test("should gets default hello world", ["step_getDefaultHelloWorld"]);

  test(
    "should not set greeting before enabled",
    "step_doesNotSetGreetingBeforeEnabled"
  );

  test(
    "should set and get greeting with enabled account",
    "step_setAndGetGreeting"
  );
});

describe("IHelloWorld events", function () {
  let owner: SignerWithAddress;
  let contract: Contract;
  let defaultGreeting = "Hello, World!";
  before(async function () {
    owner = await ethers.getSigner(ADMIN_ADDRESS);
    contract = await ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      owner
    );

    // reset greeting
    let tx = await contract.setGreeting(defaultGreeting);
    await tx.wait();
  });

  it("should emit GreetingChanged event", async function () {
    let newGreeting = "helloprecompile";
    await expect(contract.setGreeting(newGreeting))
      .to.emit(contract, "GreetingChanged")
      .withArgs(
        owner.address,
        // old greeting
        defaultGreeting,
        // new greeting
        newGreeting
      );
  });
});
```
</Tab>
</Tabs>


# Executing Test Cases (/docs/lux-l1s/custom-precompiles/executing-test-cases)

---
title: Executing Test Cases
description: In this section, we will go over how to be able to execute the test cases you wrote in the last section.
---

## Adding the Test Genesis File

To run our e2e contract tests, we will need to create an Lux L1 that has the `Hello World` precompile activated, so we will copy and paste the below genesis file into: `/tests/precompile/genesis/hello_world.json`.

Note: it's important that this has the same name as the HardHat test file we created previously.

```json
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "helloWorldConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    },
    "0x0Fa8EA536Be85F32724D57A37758761B86416123": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x66321C34",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

Adding this to our genesis enables our HelloWorld precompile at the genesis block (0th block), with `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` as the admin address.

```json
{
  "helloWorldConfig": {
    "blockTimestamp": 0,
    "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

## Declaring the HardHat E2E Test

Now that we have declared the HardHat test and corresponding `genesis.json` file. The last step to running the e2e test is to declare the new test in `/tests/precompile/solidity/suites.go`.

At the bottom of the file you will see the following code commented out:

```go title="suites.go"
// ADD YOUR PRECOMPILE HERE
/*
ginkgo.It("your precompile", ginkgo.Label("Precompile"), ginkgo.Label("YourPrecompile"), func() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
  defer cancel()

  // Specify the name shared by the genesis file in ./tests/precompile/genesis/{your_precompile}.json
  // and the test file in ./contracts/tests/{your_precompile}.ts
  blockchainID := subnetsSuite.GetBlockchainID("{your_precompile}")
  runDefaultHardhatTests(ctx, blockchainID, "{your_precompile}")
*/
```

`runDefaultHardhatTests` will run the default Hardhat test command and use the default genesis path. If you want to use a different test command and genesis path than the defaults, you can use the `utils.CreateSubnet` and `utils.RunTestCMD`. See how they were used with default params [here](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/tests/utils/subnet.go#L113)

You should copy and paste the ginkgo `It` node and update from `{your_precompile}` to `hello_world`. The string passed in to `utils.RunDefaultHardhatTests(ctx, "your_precompile")` will be used to find both the HardHat test file to execute and the genesis file, which is why you need to use the same name for both.

After modifying the `It` node, it should look like the following (you can copy and paste this directly if you prefer):

```go
ginkgo.It("hello world", ginkgo.Label("Precompile"), ginkgo.Label("HelloWorld"), func() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
  defer cancel()

  blockchainID := subnetsSuite.GetBlockchainID("hello_world")
  runDefaultHardhatTests(ctx, blockchainID, "hello_world")
})
```

Now that we've set up the new ginkgo test, we can run the ginkgo test that we want by using the `GINKGO_LABEL_FILTER`. This environment variable is passed as a flag to Ginkgo in `./scripts/run_ginkgo.sh` and restricts what tests will run to only the tests with a matching label.

## Running E2E Tests

Before we start testing, we will need to build the LuxGo binary and the custom Subnet-EVM binary.

Precompile-EVM bundles Subnet-EVM and runs it under the hood in the [`plugins/main.go`](https://github.com/luxfi/precompile-evm/blob/hello-world-example/plugin/main.go#L24). Meaning that Precompile-EVM binary works the same way as Subnet-EVM binary. Precompile-EVM repo has also same scripts and the build process as Subnet-EVM. Following steps also apply to Precompile-EVM.

You should have cloned [LuxGo](https://github.com/luxfi/luxgo) within your `$GOPATH` in the [Background and Requirements](/docs/lux-l1s/custom-precompiles/background-requirements) section, so you can build LuxGo with the following command:

```bash
cd $GOPATH/src/github.com/luxfi/luxgo
./scripts/build.sh
```

Once you've built LuxGo, you can confirm that it was successful by printing the version:

```bash
./build/luxgo --version
```

This should print something like the following (if you are running LuxGo v1.9.7):

```bash
luxgo/1.11.0 [database=v1.4.5, rpcchainvm=33, commit=c60f7d2dd10c87f57382885b59d6fb2c763eded7, go=1.21.7]
```

This path will be used later as the environment variable `LUXGO_EXEC_PATH` in the network runner.

Please note that the RPCChainVM version of LuxGo and Subnet-EVM must match.

Once we've built LuxGo, we can navigate back to the repo and build the binary:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/subnet-evm
./scripts/build.sh
```

This will build the Subnet-EVM binary and place it in LuxGo's `build/plugins` directory by default at the file path: `$GOPATH/src/github.com/luxfi/luxgo/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`

To confirm that the Subnet-EVM binary is compatible with LuxGo, you can run the same version command and confirm the RPCChainVM version matches:

```bash
$GOPATH/src/github.com/luxfi/luxgo/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy --version
```

This should give similar output:

```bash
Subnet-EVM/v0.6.1 [LuxGo=v1.11.1, rpcchainvm=33]
```
</Tab>
<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
./scripts/build.sh
```

This will build the Precompile-EVM binary and place it in LuxGo's `build/plugins` directory by default at the file path: `$GOPATH/src/github.com/luxfi/luxgo/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`

To confirm that the Precompile-EVM binary is compatible with LuxGo, you can run the same version command and confirm the RPCChainVM version matches:

```bash
$GOPATH/src/github.com/luxfi/luxgo/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy --version
```

This should give similar output:

```bash
Precompile-EVM/v0.2.0 Subnet-EVM/v0.6.1 [LuxGo=v1.11.1, rpcchainvm=33]
```
</Tab>
</Tabs>

If the RPCChainVM Protocol version printed out does not match the one used in LuxGo then Subnet-EVM will not be able to talk to LuxGo and the blockchain will not start. You can find the compatibility table for LuxGo and Subnet-EVM [here](https://github.com/luxfi/subnet-evm#luxgo-compatibility).

The `build/plugins` directory will later be used as the `LUXGO_PLUGIN_PATH`.

### Running Ginkgo Tests

To run ONLY the HelloWorld precompile test, run the command:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/subnet-evm
```
</Tab>
<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
```
</Tab>
</Tabs>

use `GINKGO_LABEL_FILTER` env var to filter the test:

```bash
GINKGO_LABEL_FILTER=HelloWorld ./scripts/run_ginkgo.sh
```

You will first see the node starting up in the `BeforeSuite` section of the precompile test:

```bash
GINKGO_LABEL_FILTER=HelloWorld ./scripts/run_ginkgo.sh

# output
Using branch: hello-world-tutorial-walkthrough
building precompile.test
# github.com/luxfi/subnet-evm/tests/precompile.test
ld: warning: could not create compact unwind for _blst_sha256_block_data_order: does not use RBP or RSP based frame

Compiled precompile.test
# github.com/luxfi/subnet-evm/tests/load.test
ld: warning: could not create compact unwind for _blst_sha256_block_data_order: does not use RBP or RSP based frame

Compiled load.test
Running Suite: subnet-evm precompile ginkgo test suite - /Users/avalabs/go/src/github.com/luxfi/subnet-evm
===================================================================================================================
Random Seed: 1674833631

Will run 1 of 7 specs
------------------------------
[BeforeSuite]
/Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/precompile_test.go:31
  > Enter [BeforeSuite] TOP-LEVEL - /Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/precompile_test.go:31 @ 01/27/23 10:33:51.001
INFO [01-27|10:33:51.002] Starting LuxGo node                wd=/Users/avalabs/go/src/github.com/luxfi/subnet-evm
INFO [01-27|10:33:51.002] Executing                                cmd="./scripts/run.sh "
[streaming output] Using branch: hello-world-tutorial-walkthrough
...
[BeforeSuite] PASSED [15.002 seconds]
```

After the `BeforeSuite` completes successfully, it will skip all but the `HelloWorld` labeled precompile test:

```bash
S [SKIPPED]
[Precompiles]
/Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/solidity/suites.go:26
  contract native minter [Precompile, ContractNativeMinter]
  /Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/solidity/suites.go:29
------------------------------
S [SKIPPED]
[Precompiles]
/Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/solidity/suites.go:26
  tx allow list [Precompile, TxAllowList]
  /Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/solidity/suites.go:36
------------------------------
...
Combined output:

Compiling 2 files with 0.8.0
Compilation finished successfully


  ExampleHelloWorldTest
    ✓ should gets default hello world (4057ms)
    ✓ should not set greeting before enabled (4067ms)
    ✓ should set and get greeting with enabled account (4074ms)



  3 passing (33s)


  < Exit [It] hello world - /Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/precompile/solidity/suites.go:64 @ 01/27/23 10:34:17.484 (11.48s)
• [11.480 seconds]
------------------------------
```

Finally, you will see the load test being skipped as well:

```bash
Running Suite: subnet-evm small load simulator test suite - /Users/avalabs/go/src/github.com/luxfi/subnet-evm
======================================================================================================================
Random Seed: 1674833658

Will run 0 of 1 specs
S [SKIPPED]
[Load Simulator]
/Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/load/load_test.go:49
  basic subnet load test [load]
  /Users/avalabs/go/src/github.com/luxfi/subnet-evm/tests/load/load_test.go:50
------------------------------

Ran 0 of 1 Specs in 0.000 seconds
SUCCESS! -- 0 Passed | 0 Failed | 0 Pending | 1 Skipped
PASS
```

Looks like the tests are passing!

<Callout title="Note">
If your tests failed, please retrace your steps. Most likely the error is that the precompile was not enabled and some code is missing. Try running `npm install` in the contracts directory to ensure that hardhat and other packages are installed.

You may also use the [official tutorial implementation](https://github.com/luxfi/subnet-evm/tree/helloworld-official-tutorial-v2) to double-check your work as well.
</Callout>


# Custom Precompiles (/docs/lux-l1s/custom-precompiles)

---
title: Custom Precompiles
description: In this tutorial, we are going to walk through how we can generate a stateful precompile from scratch. Before we start, let's brush up on what a precompile is, what a stateful precompile is, and why this is extremely useful.
---

## Background

### Precompiled Contracts

Ethereum uses precompiles to efficiently implement cryptographic primitives within the EVM instead of re-implementing the same primitives in Solidity. The following precompiles are currently included: ecrecover, sha256, blake2f, ripemd-160, Bn256Add, Bn256Mul, Bn256Pairing, the identity function, and modular exponentiation.

We can see these [precompile](https://github.com/ethereum/go-ethereum/blob/v1.11.1/core/vm/contracts.go#L82) mappings from address to function here in the Ethereum VM:

```go
// PrecompiledContractsBerlin contains the default set of pre-compiled Ethereum
// contracts used in the Berlin release.
var PrecompiledContractsBerlin = map[common.Address]PrecompiledContract{
	common.BytesToAddress([]byte{1}): &ecrecover{},
	common.BytesToAddress([]byte{2}): &sha256hash{},
	common.BytesToAddress([]byte{3}): &ripemd160hash{},
	common.BytesToAddress([]byte{4}): &dataCopy{},
	common.BytesToAddress([]byte{5}): &bigModExp{eip2565: true},
	common.BytesToAddress([]byte{6}): &bn256AddIstanbul{},
	common.BytesToAddress([]byte{7}): &bn256ScalarMulIstanbul{},
	common.BytesToAddress([]byte{8}): &bn256PairingIstanbul{},
	common.BytesToAddress([]byte{9}): &blake2F{},
}
```

These precompile addresses start from `0x0000000000000000000000000000000000000001` and increment by 1.

A [precompile](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/contracts.go#L54-L57) follows this interface:

```go
// PrecompiledContract is the basic interface for native Go contracts. The implementation
// requires a deterministic gas count based on the input size of the Run method of the
// contract.
type PrecompiledContract interface {
	RequiredGas(input []byte) uint64  // RequiredPrice calculates the contract gas use
	Run(input []byte) ([]byte, error) // Run runs the precompiled contract
}
```

Here is an example of the [sha256 precompile](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/contracts.go#L237-L250) function.

```go
type sha256hash struct{}

// RequiredGas returns the gas required to execute the pre-compiled contract.
//
// This method does not require any overflow checking as the input size gas costs
// required for anything significant is so high it's impossible to pay for.
func (c *sha256hash) RequiredGas(input []byte) uint64 {
	return uint64(len(input)+31)/32*params.Sha256PerWordGas + params.Sha256BaseGas
}

func (c *sha256hash) Run(input []byte) ([]byte, error) {
	h := sha256.Sum256(input)
	return h[:], nil
}
```

The CALL opcode (CALL, STATICCALL, DELEGATECALL, and CALLCODE) allows us to invoke this precompile.

The function signature of CALL in the EVM is as follows:

```go
 Call(
 	caller ContractRef,
 	addr common.Address,
 	input []byte,
 	gas uint64,
 	value *big.Int,
)(ret []byte, leftOverGas uint64, err error)
```

Precompiles are a shortcut to execute a function implemented by the EVM itself, rather than an actual contract. A precompile is associated with a fixed address defined in the EVM. There is no byte code associated with that address.

When a precompile is called, the EVM checks if the input address is a precompile address, and if so it executes the precompile. Otherwise, it loads the smart contract at the input address and runs it on the EVM interpreter with the specified input data.

### Stateful Precompiled Contracts

A stateful precompile builds on a precompile in that it adds state access. Stateful precompiles are not available in the default EVM, and are specific to Lux EVMs such as [Coreth](https://github.com/luxfi/luxgo/tree/master/graft/coreth) and [Subnet-EVM](https://github.com/luxfi/subnet-evm).

A stateful precompile follows this [interface](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contract/interfaces.go#L17-L20):

```go
// StatefulPrecompiledContract is the interface for executing a precompiled contract
type StatefulPrecompiledContract interface {
	// Run executes the precompiled contract.
	Run(accessibleState PrecompileAccessibleState,
	caller common.Address,
	addr  common.Address,
	input []byte,
	suppliedGas uint64,
	readOnly bool)
	(ret []byte, remainingGas uint64, err error)
}
```

A stateful precompile injects state access through the `PrecompileAccessibleState` interface to provide access to the EVM state including the ability to modify balances and read/write storage.

This way we can provide even more customization of the EVM through Stateful Precompiles than we can with the original precompile interface!

### AllowList

The AllowList enables a precompile to enforce permissions on addresses. The AllowList is not a contract itself, but a helper structure to provide a control mechanism for wrapping contracts. It provides an `AllowListConfig` to the precompile so that it can take an initial configuration from genesis/upgrade. It also provides functions to set/read the permissions. In this tutorial, we used `IAllowList` interface to provide permission control to the `HelloWorld` precompile. `IAllowList` is defined in Subnet-EVM under [`./contracts/contracts/interfaces/IAllowList.sol`](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/contracts/contracts/interfaces/IAllowList.sol). The interface is as follows:

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

interface IAllowList {
  event RoleSet(
    uint256 indexed role,
    address indexed account,
    address indexed sender,
    uint256 oldRole
  );

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

You can find more information about the AllowList interface [here](/docs/lux-l1s/evm-configuration/customize-lux-l1#allowlist-interface).

# Deploying Your Precompile (/docs/lux-l1s/custom-precompiles/precompile-deployment)

---
title: Deploying Your Precompile
description: Now that we have defined our precompile, let's deploy it to a local network.
---

We made it! Everything works in our Ginkgo tests, and now we want to spin up a local network with the Hello World precompile activated.

Start the server in a terminal in a new tab using lux-network-runner. Please check out [this link](/docs/tooling/lux-cli) for more information on Lux Network Runner, how to download it, and how to use it. The server will be in "listening" mode waiting for API calls.

We will start the server from the Subnet-EVM directory so that we can use a relative file path to the genesis JSON file:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/subnet-evm
```
</Tab>

<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
```
</Tab>
</Tabs>

Then run ANR:

```bash
lux-network-runner server \
--log-level debug \
--port=":8080" \
--grpc-gateway-port=":8081"
```

Since we already compiled LuxGo and Subnet-EVM/Precompile-EVM in a previous step, we should have the LuxGo and Subnet-EVM binaries ready to go.

We can now set the following paths. `LUXGO_EXEC_PATH` points to the latest LuxGo binary we have just built. `LUXGO_PLUGIN_PATH` points to the plugins path which should have the Subnet-EVM binary we have just built:

```bash
export LUXGO_EXEC_PATH="${GOPATH}/src/github.com/luxfi/luxgo/build/luxgo"
export LUXGO_PLUGIN_PATH="${HOME}/.luxgo/plugins"
```

The following command will "issue requests" to the server we just spun up. We can use lux-network-runner to spin up some nodes that run the latest version of Subnet-EVM:

```bash
  lux-network-runner control start \
  --log-level debug \
  --endpoint="0.0.0.0:8080" \
  --number-of-nodes=5 \
  --luxgo-path ${LUXGO_EXEC_PATH} \
  --plugin-dir ${LUXGO_PLUGIN_PATH} \
  --blockchain-specs '[{"vm_name": "subnetevm", "genesis": "./tests/precompile/genesis/hello_world.json"}]'
```

We can look at the server terminal tab and see it booting up the local network. If the network startup is successful then you should see something like this:

```bash
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9650/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9652/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9654/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9656/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9658/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
```

This shows the extension to the API server on LuxGo that's specific to the Subnet-EVM Blockchain instance. To interact with it, you will want to append the `/rpc` extension, which will supply the standard Ethereum API calls.

For example, you can use the RPC URL: `http://127.0.0.1:9650/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU/rpc`

## Maintenance

You should always keep your fork up to date with the latest changes in the official Subnet-EVM repo. If you have forked the Subnet-EVM repo, there could be conflicts and you may need to manually resolve them.

If you used Precompile-EVM, you can update your repo by bumping Subnet-EVM versions in [`go.mod`](https://github.com/luxfi/precompile-evm/blob/hello-world-example/go.mod#L7) and [`version.sh`](https://github.com/luxfi/precompile-evm/blob/hello-world-example/scripts/versions.sh#L4)

## Conclusion

We have now created a stateful precompile from scratch with the precompile generation tool. We hope you had fun and learned a little more about the Subnet-EVM. Now that you have created a simple stateful precompile, we urge you to create one of your own.

If you have an idea for a stateful precompile that may be useful to the community, feel free to create a fork of [Subnet-EVM](https://github.com/luxfi/subnet-evm) and create a pull request.

# Post-Quantum Cryptography Precompiles (/docs/lux-l1s/pq-precompiles)

---
title: Post-Quantum Cryptography Precompiles
description: Native precompile contracts for post-quantum and threshold cryptographic operations on the Lux EVM.
---

## Overview

The Lux EVM includes native precompile contracts for post-quantum and threshold cryptographic operations. These precompiles are available on any Lux L1/L2 chain, including the Lux Mainnet, Testnet, and white-label chains.

Unlike the [AllowList-based precompiles](/docs/lux-l1s/precompiles/allowlist-interface) which manage access control for chain configuration, PQ precompiles provide cryptographic primitives that any contract or EOA can call. They do not require activation in the genesis file -- they are built into the Lux EVM itself.

## Precompile Addresses

| Precompile | Address | Purpose |
|------------|---------|---------|
| SR25519 Verify | `0x0a00000000000000000000000000000000000001` | Substrate Schnorrkel signature verification |
| Ed25519 Verify | `0x0200000000000000000000000000000000000005` | EdDSA signature verification |
| secp256r1 Verify | `0x0200000000000000000000000000000000000004` | NIST P-256 curve verification (WebAuthn/Passkeys) |
| FROST Verify | `0x0800000000000000000000000000000000000002` | Threshold Schnorr signatures (FROST protocol) |
| CGGMP21 Verify | `0x0800000000000000000000000000000000000003` | Threshold ECDSA (secp256k1, CGGMP21 protocol) |
| ML-DSA Verify | `0x0200000000000000000000000000000000000006` | FIPS 204 post-quantum digital signatures |
| SLH-DSA Verify | `0x0600000000000000000000000000000000000001` | FIPS 205 hash-based PQ signatures |
| ML-KEM Config | `0x0200000000000000000000000000000000000007` | FIPS 203 post-quantum key encapsulation |
| Ringtail Threshold | `0x020000000000000000000000000000000000000B` | Post-quantum threshold signatures (Ring-LWE) |
| Blake3 Hash | `0x0500000000000000000000000000000000000004` | Fast cryptographic hashing |
| DEX | `0x0000000000000000000000000000000000009010` | Native on-chain DEX trading |
| Router | `0x0000000000000000000000000000000000009012` | DEX routing |

## Categories

The precompiles are organized into four categories:

- [**Signature Verification**](/docs/lux-l1s/pq-precompiles/signature-verification) -- Classical and post-quantum signature schemes (SR25519, Ed25519, secp256r1, ML-DSA, SLH-DSA)
- [**Threshold Signatures**](/docs/lux-l1s/pq-precompiles/threshold-signatures) -- Multi-party computation protocols (FROST, CGGMP21, Ringtail)
- [**Key Encapsulation**](/docs/lux-l1s/pq-precompiles/key-encapsulation) -- Post-quantum key exchange (ML-KEM)
- [**Utilities**](/docs/lux-l1s/pq-precompiles/utilities) -- Hashing and on-chain DEX (Blake3, DEX, Router)

## Supported Chains

All PQ precompiles are available on:

- **Lux Mainnet** (Chain ID: 96369)
- **Lux Testnet** (Chain ID: 96368)
- **Any Lux L1/L2** -- including white-label chains (e.g., Liquidity Chain ID: 8675309)

## Quick Start

Verify an ML-DSA (FIPS 204) post-quantum signature using viem:

```ts
import { createPublicClient, http, encodePacked } from 'viem'
import { lux } from 'viem/chains'

const client = createPublicClient({
  chain: lux,
  transport: http(),
})

// ML-DSA Verify precompile
const ML_DSA_ADDRESS = '0x0200000000000000000000000000000000000006'

const result = await client.call({
  to: ML_DSA_ADDRESS,
  data: encodePacked(
    ['bytes', 'bytes', 'bytes'],
    [message, publicKey, signature]
  ),
})

const isValid = result.data === '0x01'
```

Or with ethers.js:

```ts
import { ethers } from 'ethers'

const provider = new ethers.JsonRpcProvider('https://api.lux.network/ext/bc/C/rpc')

const ML_DSA_ADDRESS = '0x0200000000000000000000000000000000000006'

const result = await provider.call({
  to: ML_DSA_ADDRESS,
  data: ethers.solidityPacked(
    ['bytes', 'bytes', 'bytes'],
    [message, publicKey, signature]
  ),
})

const isValid = result === '0x01'
```

<Callout type="info">
All verification precompiles return `0x01` for a valid signature and `0x00` for an invalid one. A revert indicates malformed input (wrong key size, truncated signature, etc.).
</Callout>

## Why On-Chain PQ Cryptography?

Post-quantum cryptography protects against attacks from quantum computers. NIST finalized three post-quantum standards in 2024:

- **FIPS 203 (ML-KEM)** -- Key encapsulation based on Module-LWE
- **FIPS 204 (ML-DSA)** -- Digital signatures based on Module-LWE (formerly Dilithium)
- **FIPS 205 (SLH-DSA)** -- Hash-based digital signatures (formerly SPHINCS+)

By providing these as EVM precompiles, Lux enables smart contracts to verify post-quantum signatures natively, without the prohibitive gas costs of implementing lattice-based or hash-based cryptography in Solidity. This is critical for:

- **Bridge security** -- Verifying PQ-signed messages from external chains
- **Account abstraction** -- Supporting PQ key pairs as wallet signers
- **Threshold custody** -- Multi-party signing with quantum-resistant keys (Ringtail)
- **WebAuthn/Passkeys** -- Native secp256r1 verification for browser-based wallets


# Key Encapsulation (/docs/lux-l1s/pq-precompiles/key-encapsulation)

---
title: Key Encapsulation
description: ML-KEM (FIPS 203) post-quantum key encapsulation precompile for the Lux EVM.
---

## Overview

ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism), standardized as FIPS 203 in August 2024, provides post-quantum secure key exchange. The Lux EVM includes a precompile for on-chain ML-KEM operations, enabling smart contracts to participate in quantum-resistant key agreement protocols.

## ML-KEM Config

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000007` |
| **Operations** | Encapsulate, Decapsulate (view) |
| **Supported Levels** | ML-KEM-512, ML-KEM-768, ML-KEM-1024 |
| **Gas Cost** | 8,000 (encapsulate), 10,000 (decapsulate) |

Unlike the signature verification precompiles which simply return valid/invalid, ML-KEM is a key encapsulation mechanism: it produces a shared secret and a ciphertext. The precompile supports both the encapsulation and decapsulation operations.

### Parameter Sets

| Parameter Set | Security Level | Public Key | Ciphertext | Shared Secret |
|---------------|---------------|------------|------------|---------------|
| ML-KEM-512 | NIST Level 1 (128-bit) | 800 bytes | 768 bytes | 32 bytes |
| ML-KEM-768 | NIST Level 3 (192-bit) | 1,184 bytes | 1,088 bytes | 32 bytes |
| ML-KEM-1024 | NIST Level 5 (256-bit) | 1,568 bytes | 1,568 bytes | 32 bytes |

## Operations

### Encapsulate

Given a public key, produce a shared secret and ciphertext. The ciphertext can be sent to the key holder, who decapsulates it to recover the same shared secret.

**Input format**: `0x01 || public_key`

**Output**: `shared_secret (32 bytes) || ciphertext`

```ts
import { createPublicClient, http, encodePacked } from 'viem'
import { lux } from 'viem/chains'

const client = createPublicClient({
  chain: lux,
  transport: http(),
})

const ML_KEM_ADDRESS = '0x0200000000000000000000000000000000000007'

// Encapsulate: produce shared secret + ciphertext
const result = await client.call({
  to: ML_KEM_ADDRESS,
  data: encodePacked(
    ['uint8', 'bytes'],
    [0x01, recipientPublicKey]  // 0x01 = encapsulate operation
  ),
})

// result.data contains: shared_secret (32 bytes) || ciphertext
const sharedSecret = result.data.slice(0, 66)  // 0x + 64 hex chars = 32 bytes
const ciphertext = result.data.slice(66)
```

### Decapsulate

Given a secret key and ciphertext, recover the shared secret.

**Input format**: `0x02 || secret_key || ciphertext`

**Output**: `shared_secret (32 bytes)`

<Callout type="warn">
Decapsulation requires the secret key, which should never be stored on-chain. The decapsulate operation is intended for use in off-chain computation (e.g., via `eth_call`) or within privacy-preserving enclaves. Submitting a secret key in an on-chain transaction exposes it publicly.
</Callout>

## Use Cases

### Encrypted On-Chain Messaging

Smart contracts can establish shared secrets between parties for encrypted communication channels, with the key exchange itself being quantum-resistant:

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

contract QuantumSafeChannel {
    address constant ML_KEM = 0x0200000000000000000000000000000000000007;

    // Recipient registers their ML-KEM public key
    mapping(address => bytes) public publicKeys;

    event CiphertextPublished(address indexed sender, address indexed recipient, bytes ciphertext);

    function registerPublicKey(bytes calldata mlKemPublicKey) external {
        publicKeys[msg.sender] = mlKemPublicKey;
    }

    function initiateChannel(address recipient) external returns (bytes memory ciphertext) {
        bytes memory recipientKey = publicKeys[recipient];
        require(recipientKey.length > 0, "Recipient not registered");

        // Encapsulate to produce shared secret + ciphertext
        (bool success, bytes memory result) = ML_KEM.staticcall(
            abi.encodePacked(uint8(0x01), recipientKey)
        );
        require(success, "Encapsulation failed");

        // Shared secret (first 32 bytes) stays in contract state or is used ephemerally
        // Ciphertext is published for the recipient to decapsulate off-chain
        ciphertext = new bytes(result.length - 32);
        for (uint i = 0; i < ciphertext.length; i++) {
            ciphertext[i] = result[i + 32];
        }

        emit CiphertextPublished(msg.sender, recipient, ciphertext);
    }
}
```

### Hybrid Key Exchange

Combine ML-KEM with classical ECDH for defense-in-depth. The final shared secret is derived from both key exchanges, so an attacker must break both to compromise the channel:

```ts
import { keccak256, encodePacked } from 'viem'

// Classical ECDH shared secret (from secp256k1)
const classicalSecret = deriveECDHSecret(myPrivateKey, theirPublicKey)

// Post-quantum ML-KEM shared secret (from precompile)
const pqResult = await client.call({
  to: ML_KEM_ADDRESS,
  data: encodePacked(['uint8', 'bytes'], [0x01, theirMLKEMPublicKey]),
})
const pqSecret = pqResult.data.slice(0, 66)

// Hybrid shared secret: hash both together
const hybridSecret = keccak256(
  encodePacked(['bytes', 'bytes'], [classicalSecret, pqSecret])
)
```

### Future-Proof Token Bridges

Bridge protocols can use ML-KEM to establish quantum-resistant encrypted channels between validator nodes, ensuring that bridge messages remain confidential even if captured traffic is later decrypted by a quantum computer ("harvest now, decrypt later" attacks).


# Signature Verification (/docs/lux-l1s/pq-precompiles/signature-verification)

---
title: Signature Verification
description: Precompiles for verifying classical and post-quantum digital signatures on the Lux EVM.
---

## Overview

The Lux EVM provides precompiles for verifying signatures from five different schemes, ranging from classical elliptic curve cryptography to NIST post-quantum standards. All verification precompiles accept a message, public key, and signature as input, and return `0x01` (valid) or `0x00` (invalid).

## SR25519 Verify

Verifies Schnorrkel/Ristretto signatures used by the Substrate ecosystem (Polkadot, Kusama).

| Property | Value |
|----------|-------|
| **Address** | `0x0a00000000000000000000000000000000000001` |
| **Input** | `message \|\| public_key (32 bytes) \|\| signature (64 bytes)` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Gas Cost** | 3,000 |

SR25519 uses Ristretto255 (a prime-order group constructed over Curve25519) with a Schnorr-like signing scheme. This precompile enables Lux contracts to verify signatures originating from Substrate-based chains, useful for cross-chain bridges and interoperability.

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

contract SR25519Verifier {
    address constant SR25519 = 0x0a00000000000000000000000000000000000001;

    function verify(
        bytes memory message,
        bytes32 publicKey,
        bytes memory signature
    ) external view returns (bool) {
        (bool success, bytes memory result) = SR25519.staticcall(
            abi.encodePacked(message, publicKey, signature)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

## Ed25519 Verify

Verifies EdDSA signatures on the Edwards25519 curve, used by Solana, Cardano, TON, and many other protocols.

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000005` |
| **Input** | `message \|\| public_key (32 bytes) \|\| signature (64 bytes)` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Gas Cost** | 3,000 |

Ed25519 is widely adopted for its performance and security properties. The precompile enables verification of signatures from Ed25519-based chains without the high gas cost of pure-Solidity implementations.

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

contract Ed25519Verifier {
    address constant ED25519 = 0x0200000000000000000000000000000000000005;

    function verify(
        bytes memory message,
        bytes32 publicKey,
        bytes memory signature
    ) external view returns (bool) {
        (bool success, bytes memory result) = ED25519.staticcall(
            abi.encodePacked(message, publicKey, signature)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

## secp256r1 Verify (P-256)

Verifies ECDSA signatures on the NIST P-256 curve, used by WebAuthn, Apple Passkeys, Android Keystore, and most TLS implementations.

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000004` |
| **Input** | `message_hash (32 bytes) \|\| r (32 bytes) \|\| s (32 bytes) \|\| x (32 bytes) \|\| y (32 bytes)` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Gas Cost** | 3,450 |

This precompile is essential for account abstraction wallets that use WebAuthn/Passkeys as signers. Users can sign transactions with their device biometrics (Face ID, fingerprint) and the contract verifies the P-256 signature natively.

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

contract PasskeyVerifier {
    address constant SECP256R1 = 0x0200000000000000000000000000000000000004;

    function verifyPasskey(
        bytes32 messageHash,
        bytes32 r,
        bytes32 s,
        bytes32 pubKeyX,
        bytes32 pubKeyY
    ) external view returns (bool) {
        (bool success, bytes memory result) = SECP256R1.staticcall(
            abi.encodePacked(messageHash, r, s, pubKeyX, pubKeyY)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

<Callout type="info">
The secp256r1 precompile is also available as [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md) on other EVM chains. The Lux implementation is ABI-compatible with RIP-7212.
</Callout>

## ML-DSA Verify (FIPS 204)

Verifies post-quantum digital signatures based on the Module Learning With Errors (Module-LWE) problem. ML-DSA (formerly known as CRYSTALS-Dilithium) was standardized by NIST as FIPS 204 in August 2024.

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000006` |
| **Input** | `message \|\| public_key \|\| signature` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Supported Levels** | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
| **Gas Cost** | 10,000 (ML-DSA-44), 15,000 (ML-DSA-65), 20,000 (ML-DSA-87) |

The security level is inferred from the public key size:

| Parameter Set | Security Level | Public Key | Signature |
|---------------|---------------|------------|-----------|
| ML-DSA-44 | NIST Level 2 (128-bit) | 1,312 bytes | 2,420 bytes |
| ML-DSA-65 | NIST Level 3 (192-bit) | 1,952 bytes | 3,293 bytes |
| ML-DSA-87 | NIST Level 5 (256-bit) | 2,592 bytes | 4,595 bytes |

```ts
import { createPublicClient, http, encodePacked, toHex } from 'viem'
import { lux } from 'viem/chains'

const client = createPublicClient({
  chain: lux,
  transport: http(),
})

const ML_DSA_ADDRESS = '0x0200000000000000000000000000000000000006'

// Verify an ML-DSA-65 signature (security level inferred from key size)
const result = await client.call({
  to: ML_DSA_ADDRESS,
  data: encodePacked(
    ['bytes', 'bytes', 'bytes'],
    [message, publicKey, signature]  // publicKey is 1952 bytes -> ML-DSA-65
  ),
})

console.log('Valid:', result.data === '0x01')
```

<Callout type="warn">
ML-DSA signatures and public keys are significantly larger than classical ECDSA. An ML-DSA-65 signature is 3,293 bytes vs 65 bytes for secp256k1. Plan calldata costs accordingly.
</Callout>

## SLH-DSA Verify (FIPS 205)

Verifies stateless hash-based post-quantum signatures. SLH-DSA (formerly known as SPHINCS+) was standardized by NIST as FIPS 205. It relies only on hash function security, making it the most conservative post-quantum choice.

| Property | Value |
|----------|-------|
| **Address** | `0x0600000000000000000000000000000000000001` |
| **Input** | `message \|\| public_key \|\| signature` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Supported Variants** | SLH-DSA-128s, SLH-DSA-128f, SLH-DSA-192s, SLH-DSA-192f, SLH-DSA-256s, SLH-DSA-256f |
| **Gas Cost** | 50,000 -- 200,000 (varies by parameter set) |

The "s" (small) variants produce smaller signatures but are slower to verify. The "f" (fast) variants are faster to verify but produce larger signatures.

| Parameter Set | Security | Public Key | Signature (small) | Signature (fast) |
|---------------|----------|------------|-------------------|------------------|
| SLH-DSA-128 | NIST Level 1 | 32 bytes | 7,856 bytes | 17,088 bytes |
| SLH-DSA-192 | NIST Level 3 | 48 bytes | 16,224 bytes | 35,664 bytes |
| SLH-DSA-256 | NIST Level 5 | 64 bytes | 29,792 bytes | 49,856 bytes |

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

contract SLHDSAVerifier {
    address constant SLH_DSA = 0x0600000000000000000000000000000000000001;

    function verify(
        bytes memory message,
        bytes memory publicKey,
        bytes memory signature
    ) external view returns (bool) {
        (bool success, bytes memory result) = SLH_DSA.staticcall(
            abi.encodePacked(message, publicKey, signature)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

<Callout type="info">
SLH-DSA is the most conservative post-quantum scheme because it relies solely on hash functions, which are well-understood and resistant to both classical and quantum attacks. Use SLH-DSA when maximum long-term security is more important than performance or signature size.
</Callout>

## Gas Cost Comparison

| Precompile | Gas Cost | Key Size | Signature Size |
|------------|----------|----------|----------------|
| ecrecover (secp256k1) | 3,000 | 64 bytes | 65 bytes |
| SR25519 | 3,000 | 32 bytes | 64 bytes |
| Ed25519 | 3,000 | 32 bytes | 64 bytes |
| secp256r1 | 3,450 | 64 bytes | 64 bytes |
| ML-DSA-44 | 10,000 | 1,312 bytes | 2,420 bytes |
| ML-DSA-65 | 15,000 | 1,952 bytes | 3,293 bytes |
| ML-DSA-87 | 20,000 | 2,592 bytes | 4,595 bytes |
| SLH-DSA-128s | 50,000 | 32 bytes | 7,856 bytes |
| SLH-DSA-256f | 200,000 | 64 bytes | 49,856 bytes |

For comparison, implementing Ed25519 verification in pure Solidity costs approximately 500,000 gas. The precompiles reduce this by 100x or more.


# Threshold Signatures (/docs/lux-l1s/pq-precompiles/threshold-signatures)

---
title: Threshold Signatures
description: Precompiles for verifying threshold signatures from FROST, CGGMP21, and Ringtail protocols on the Lux EVM.
---

## Overview

Threshold signature schemes allow a group of `n` parties to jointly produce a signature such that any `t` of them (the threshold) can sign, but fewer than `t` cannot. The Lux EVM provides precompiles for verifying three threshold signature protocols:

- **FROST** -- Threshold Schnorr signatures (Ed25519 and secp256k1)
- **CGGMP21** -- Threshold ECDSA on secp256k1
- **Ringtail** -- Post-quantum threshold signatures based on Ring-LWE

These precompiles verify the final aggregated signature. The multi-party key generation and signing ceremonies happen off-chain (e.g., via [Lux MPC](/docs/lux-l1s/pq-precompiles/threshold-signatures#use-with-lux-mpc)).

## FROST Verify

Verifies threshold Schnorr signatures produced by the FROST (Flexible Round-Optimized Schnorr Threshold) protocol.

| Property | Value |
|----------|-------|
| **Address** | `0x0800000000000000000000000000000000000002` |
| **Input** | `message \|\| group_public_key (32 bytes) \|\| signature (64 bytes)` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Gas Cost** | 3,500 |

FROST produces standard Schnorr signatures that are indistinguishable from single-signer Schnorr signatures. The verifier does not need to know the threshold parameters -- it verifies against the group public key exactly like a normal Schnorr verification.

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

contract FROSTVerifier {
    address constant FROST = 0x0800000000000000000000000000000000000002;

    /// @notice Verify a FROST threshold Schnorr signature
    /// @param message The signed message
    /// @param groupPublicKey The group public key (aggregated from key shares)
    /// @param signature The aggregated FROST signature (R || s, 64 bytes)
    function verify(
        bytes memory message,
        bytes32 groupPublicKey,
        bytes memory signature
    ) external view returns (bool) {
        (bool success, bytes memory result) = FROST.staticcall(
            abi.encodePacked(message, groupPublicKey, signature)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

### FROST Use Cases

- **Multi-sig wallets** -- 2-of-3 or 3-of-5 custody without on-chain multi-sig overhead
- **DAO treasury** -- Threshold control of funds with a single on-chain signature
- **Cross-chain bridges** -- Validator committees sign attestations using FROST, verified on-chain

## CGGMP21 Verify

Verifies threshold ECDSA signatures produced by the CGGMP21 protocol (Canetti-Gennaro-Goldfeder-Makriyannis-Peled, 2021).

| Property | Value |
|----------|-------|
| **Address** | `0x0800000000000000000000000000000000000003` |
| **Input** | `message_hash (32 bytes) \|\| public_key (64 bytes) \|\| signature (64 bytes)` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Gas Cost** | 4,000 |

CGGMP21 produces standard ECDSA signatures on secp256k1, making them compatible with existing Ethereum infrastructure. The output signature is indistinguishable from a normal `ecrecover`-compatible signature.

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

contract CGGMP21Verifier {
    address constant CGGMP21 = 0x0800000000000000000000000000000000000003;

    /// @notice Verify a CGGMP21 threshold ECDSA signature
    /// @param messageHash The keccak256 hash of the signed message
    /// @param publicKey The group public key (uncompressed, 64 bytes: x || y)
    /// @param signature The aggregated ECDSA signature (r || s, 64 bytes)
    function verify(
        bytes32 messageHash,
        bytes memory publicKey,
        bytes memory signature
    ) external view returns (bool) {
        (bool success, bytes memory result) = CGGMP21.staticcall(
            abi.encodePacked(messageHash, publicKey, signature)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

<Callout type="info">
Since CGGMP21 produces standard secp256k1 ECDSA signatures, you can also verify them using the built-in `ecrecover` precompile. The CGGMP21 precompile is provided for explicit verification against the full group public key (not just the derived address).
</Callout>

### CGGMP21 Use Cases

- **Institutional custody** -- MPC wallets where multiple parties hold key shares (e.g., customer + exchange + backup)
- **Settlement signing** -- Lux MPC uses CGGMP21 for threshold-signed settlement transactions with HSM co-signing
- **Backward compatibility** -- Produce Ethereum-compatible signatures from threshold key shares

## Ringtail Threshold Verify

Verifies post-quantum threshold signatures based on Ring Learning With Errors (Ring-LWE). Ringtail combines the quantum resistance of lattice-based cryptography with the distributed trust of threshold signatures.

| Property | Value |
|----------|-------|
| **Address** | `0x020000000000000000000000000000000000000B` |
| **Input** | `message \|\| group_public_key \|\| signature \|\| threshold_params` |
| **Output** | `0x01` (valid) or `0x00` (invalid) |
| **Gas Cost** | 25,000 |

Unlike FROST and CGGMP21 where the aggregated signature is indistinguishable from a single-signer signature, Ringtail signatures include threshold metadata that the verifier uses. The `threshold_params` field encodes `t` (threshold) and `n` (total parties).

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

contract RingtailVerifier {
    address constant RINGTAIL = 0x020000000000000000000000000000000000000B;

    /// @notice Verify a Ringtail post-quantum threshold signature
    /// @param message The signed message
    /// @param groupPublicKey The group public key
    /// @param signature The aggregated Ringtail signature
    /// @param thresholdParams Encoded threshold parameters (t, n)
    function verify(
        bytes memory message,
        bytes memory groupPublicKey,
        bytes memory signature,
        bytes memory thresholdParams
    ) external view returns (bool) {
        (bool success, bytes memory result) = RINGTAIL.staticcall(
            abi.encodePacked(message, groupPublicKey, signature, thresholdParams)
        );
        return success && result.length > 0 && uint8(result[0]) == 1;
    }
}
```

### Ringtail Use Cases

- **Quantum-safe custody** -- Post-quantum multi-party wallets for long-term asset protection
- **PQ bridge validators** -- Bridge committee signatures that remain secure against quantum computers
- **Hybrid signing** -- Use Ringtail alongside FROST/CGGMP21 for defense-in-depth

## Use with Lux MPC

[Lux MPC](https://github.com/luxfi/mpc) provides the off-chain infrastructure for threshold key generation and signing. The MPC service handles:

1. **Distributed Key Generation (DKG)** -- Generates key shares for `n` parties with threshold `t`
2. **Signing Rounds** -- Coordinates multi-party signing via secure channels (Hanzo PubSub)
3. **HSM Co-signing** -- Optional hardware security module co-signing for settlement intents

The on-chain precompiles complete the picture by enabling smart contracts to verify the resulting threshold signatures.

```
Off-chain (Lux MPC)              On-chain (Lux EVM)
┌──────────────────┐             ┌──────────────────┐
│  Key Generation  │             │                  │
│  (DKG)           │             │  Smart Contract  │
│       ↓          │             │       ↓          │
│  Signing Round   │──signature──│  FROST / CGGMP21 │
│  (t-of-n)        │             │  / Ringtail      │
│       ↓          │             │  Precompile      │
│  HSM Co-sign     │             │       ↓          │
│  (optional)      │             │  Valid / Invalid │
└──────────────────┘             └──────────────────┘
```

## Comparison

| Property | FROST | CGGMP21 | Ringtail |
|----------|-------|---------|----------|
| Curve/Primitive | Schnorr (Ed25519/secp256k1) | ECDSA (secp256k1) | Ring-LWE |
| Quantum Resistant | No | No | Yes |
| Signature Size | 64 bytes | 64 bytes | ~2,500 bytes |
| Gas Cost | 3,500 | 4,000 | 25,000 |
| EVM Compatible | Schnorr verify | ecrecover compatible | Precompile only |
| Rounds (signing) | 2 | 4-6 | 3 |
| Key Resharing | Yes | Yes | Yes |


# Utilities (/docs/lux-l1s/pq-precompiles/utilities)

---
title: Utilities
description: Blake3 hashing and native DEX precompiles on the Lux EVM.
---

## Overview

In addition to cryptographic signature and key encapsulation precompiles, the Lux EVM provides utility precompiles for high-performance hashing and native on-chain trading.

## Blake3 Hash

A precompile for the Blake3 cryptographic hash function. Blake3 is significantly faster than keccak256 and SHA-256 while providing equivalent security.

| Property | Value |
|----------|-------|
| **Address** | `0x0500000000000000000000000000000000000004` |
| **Input** | Arbitrary-length data to hash |
| **Output** | 32-byte Blake3 digest |
| **Gas Cost** | 30 + 6 per 64-byte block |

### Why Blake3?

- **Speed** -- Blake3 is ~5x faster than keccak256 in software, making it cheaper for large inputs
- **Tree hashing** -- Blake3 supports incremental and parallel hashing natively
- **Standardization** -- Used by many modern cryptographic protocols and file systems

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

contract Blake3Hasher {
    address constant BLAKE3 = 0x0500000000000000000000000000000000000004;

    function hash(bytes memory data) external view returns (bytes32) {
        (bool success, bytes memory result) = BLAKE3.staticcall(data);
        require(success, "Blake3 hash failed");
        return bytes32(result);
    }
}
```

### Gas Comparison for Hashing

| Function | Gas (32 bytes) | Gas (1 KB) | Gas (32 KB) |
|----------|---------------|------------|-------------|
| keccak256 | 36 | 294 | 9,030 |
| SHA-256 (precompile) | 72 | 420 | 12,204 |
| Blake3 (precompile) | 33 | 126 | 3,102 |

For contracts that hash large amounts of data (Merkle trees, data availability proofs), Blake3 provides significant gas savings.

```ts
import { createPublicClient, http, toHex } from 'viem'
import { lux } from 'viem/chains'

const client = createPublicClient({
  chain: lux,
  transport: http(),
})

const BLAKE3_ADDRESS = '0x0500000000000000000000000000000000000004'

const result = await client.call({
  to: BLAKE3_ADDRESS,
  data: toHex(new TextEncoder().encode('Hello, post-quantum world')),
})

console.log('Blake3 hash:', result.data)
```

## DEX Precompile

A native on-chain decentralized exchange built into the Lux EVM. The DEX precompile provides atomic token swaps without requiring external smart contract deployments.

| Property | Value |
|----------|-------|
| **Address** | `0x0000000000000000000000000000000000009010` |
| **Operations** | Create pool, add/remove liquidity, swap |
| **Gas Cost** | Varies by operation |

### Operations

The DEX precompile uses function selectors encoded in the first 4 bytes of calldata:

| Selector | Function | Description |
|----------|----------|-------------|
| `0x01` | `createPool` | Create a new trading pair |
| `0x02` | `addLiquidity` | Add liquidity to a pool |
| `0x03` | `removeLiquidity` | Remove liquidity from a pool |
| `0x04` | `swap` | Execute a token swap |
| `0x05` | `getQuote` | Get a swap quote (view) |
| `0x06` | `getPool` | Get pool info (view) |

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

interface ILuxDEX {
    function createPool(address tokenA, address tokenB, uint24 fee) external returns (address pool);
    function addLiquidity(address pool, uint256 amountA, uint256 amountB, uint256 minLP) external returns (uint256 lpTokens);
    function removeLiquidity(address pool, uint256 lpTokens, uint256 minA, uint256 minB) external returns (uint256 amountA, uint256 amountB);
    function swap(address pool, address tokenIn, uint256 amountIn, uint256 minAmountOut) external returns (uint256 amountOut);
    function getQuote(address pool, address tokenIn, uint256 amountIn) external view returns (uint256 amountOut);
    function getPool(address tokenA, address tokenB, uint24 fee) external view returns (address pool);
}

contract DEXExample {
    ILuxDEX constant DEX = ILuxDEX(0x0000000000000000000000000000000000009010);

    function swapTokens(
        address pool,
        address tokenIn,
        uint256 amountIn,
        uint256 minOut
    ) external returns (uint256) {
        return DEX.swap(pool, tokenIn, amountIn, minOut);
    }
}
```

## Router Precompile

The Router precompile provides multi-hop swap routing across DEX pools, finding optimal paths for token swaps.

| Property | Value |
|----------|-------|
| **Address** | `0x0000000000000000000000000000000000009012` |
| **Operations** | Multi-hop swap, route discovery |
| **Gas Cost** | Varies by path length |

### Operations

| Selector | Function | Description |
|----------|----------|-------------|
| `0x01` | `swapExactIn` | Swap exact input amount through a path |
| `0x02` | `swapExactOut` | Swap to get exact output amount |
| `0x03` | `findBestPath` | Find optimal swap path (view) |

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

interface ILuxRouter {
    function swapExactIn(
        address[] calldata path,
        uint24[] calldata fees,
        uint256 amountIn,
        uint256 minAmountOut,
        address recipient,
        uint256 deadline
    ) external returns (uint256 amountOut);

    function swapExactOut(
        address[] calldata path,
        uint24[] calldata fees,
        uint256 amountOut,
        uint256 maxAmountIn,
        address recipient,
        uint256 deadline
    ) external returns (uint256 amountIn);

    function findBestPath(
        address tokenIn,
        address tokenOut,
        uint256 amountIn
    ) external view returns (address[] memory path, uint24[] memory fees, uint256 amountOut);
}

contract RouterExample {
    ILuxRouter constant ROUTER = ILuxRouter(0x0000000000000000000000000000000000009012);

    function swapWithBestRoute(
        address tokenIn,
        address tokenOut,
        uint256 amountIn,
        uint256 minAmountOut
    ) external returns (uint256) {
        // Find the best path
        (address[] memory path, uint24[] memory fees, ) = ROUTER.findBestPath(
            tokenIn, tokenOut, amountIn
        );

        // Execute the swap
        return ROUTER.swapExactIn(
            path, fees, amountIn, minAmountOut, msg.sender, block.timestamp + 300
        );
    }
}
```

<Callout type="info">
The DEX and Router precompiles are distinct from external DEX deployments (like Uniswap forks). Being precompiles, they execute at native speed with lower gas costs than equivalent Solidity implementations. However, they share the same pool state, so liquidity added via the precompile is accessible via the Router and vice versa.
</Callout>


# Customize an Lux L1 (/docs/lux-l1s/evm-configuration/customize-avalanche-l1)

---
title: Customize an Lux L1
description: Learn how to customize your EVM-powered Lux L1.
---

All Lux L1s can be customized by utilizing [`L1s Configs`](#lux-l1-configs).

an Lux L1 can have one or more blockchains. For example, the Primary Network, which is an Lux L1, a special one nonetheless, has 3 blockchains. Each chain can be further customized using chain specific configuration file. See [here](/docs/nodes/configure/configs-flags) for detailed explanation.

An Lux L1 created by or forked from [Subnet-EVM](https://github.com/luxfi/subnet-evm) can be customized by utilizing one or more of the following methods:

- [Genesis](#genesis)
- [Precompile](#precompiles)
- [Upgrade Configs](#network-upgrades-enabledisable-precompiles)
- [Chain Configs](#luxgo-chain-configs)

Lux L1 Configs[​](#lux-l1-configs "Direct link to heading")
-----------------------------------------------------------

an Lux L1 can customized by setting parameters for the following:

- [Validator-only communication to create a private Lux L1](/docs/nodes/configure/lux-l1-configs#validatoronly-bool)
- [Consensus](/docs/nodes/configure/lux-l1-configs#consensus-parameters)
- [Gossip](/docs/nodes/configure/lux-l1-configs#gossip-configs)

See [here](/docs/nodes/configure/lux-l1-configs) for more info.

Genesis[​](#genesis "Direct link to heading")
---------------------------------------------

Each blockchain has some genesis state when it's created. Each Virtual Machine defines the format and semantics of its genesis data.

The default genesis Subnet-EVM provided below has some well defined parameters:

```json
{
  "config": {
    "chainId": 43214,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "feeConfig": {
      "gasLimit": 15000000,
      "minBaseFee": 25000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": false
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0xe4e1c0",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

### Chain Config[​](#chain-config "Direct link to heading")

`chainID`: Denotes the ChainID of to be created chain. Must be picked carefully since a conflict with other chains can cause issues. One suggestion is to check with [chainlist.org](https://chainlist.org/) to avoid ID collision, reserve and publish your ChainID properly.

You can use `eth_getChainConfig` RPC call to get the current chain config. See [here](/docs/rpcs/subnet-evm#eth_getchainconfig) for more info.

#### Hard Forks[​](#hard-forks "Direct link to heading")

`homesteadBlock`, `eip150Block`, `eip150Hash`, `eip155Block`, `byzantiumBlock`, `constantinopleBlock`, `petersburgBlock`, `istanbulBlock`, `muirGlacierBlock` are EVM hard fork activation times. Changing these may cause issues, so treat them carefully.

#### Fee Config[​](#fee-config "Direct link to heading")

`gasLimit`: Sets the max amount of gas consumed per block. This restriction puts a cap on the amount of computation that can be done in a single block, which in turn sets a limit on the maximum gas usage allowed for a single transaction. For reference, LUExchange-Chain value is set to `15,000,000`.

`targetBlockRate`: Sets the target rate of block production in seconds. A target of 2 will target producing a block every 2 seconds. If the network starts producing blocks at a faster rate, it indicates that more blocks than anticipated are being issued to the network, resulting in an increase in base fees. For C-chain this value is set to `2`.

`minBaseFee`: Sets a lower bound on the EIP-1559 base fee of a block. Since the block's base fee sets the minimum gas price for any transaction included in that block, this effectively sets a minimum gas price for any transaction.

`targetGas`: Specifies the targeted amount of gas (including block gas cost) to consume within a rolling 10-seconds window. When the dynamic fee algorithm observes that network activity is above/below the `targetGas`, it increases/decreases the base fee proportionally to how far above/below the target actual network activity is. If the network starts producing blocks with gas cost higher than this, base fees are increased accordingly.

`baseFeeChangeDenominator`: Divides the difference between actual and target utilization to determine how much to increase/decrease the base fee. A larger denominator indicates a slower changing, stickier base fee, while a lower denominator allows the base fee to adjust more quickly. For reference, the C-chain value is set to `36`. This value sets the base fee to increase or decrease by a factor of `1/36` of the parent block's base fee.

`minBlockGasCost`: Sets the minimum amount of gas to charge for the production of a block. This value is set to `0` in LUExchange-Chain.

`maxBlockGasCost`: Sets the maximum amount of gas to charge for the production of a block.

`blockGasCostStep`: Determines how much to increase/decrease the block gas cost depending on the amount of time elapsed since the previous block.

If the block is produced at the target rate, the block gas cost will stay the same as the block gas cost for the parent block.

If it is produced faster/slower, the block gas cost will be increased/decreased by the step value for each second faster/slower than the target block rate accordingly.

<Callout title="Note">
If the `blockGasCostStep` is set to a very large number, it effectively requires block production to go no faster than the `targetBlockRate`. For example, if a block is produced two seconds faster than the target block rate, the block gas cost will increase by `2 * blockGasCostStep`.
</Callout>

#### Custom Fee Recipients[​](#custom-fee-recipients "Direct link to heading")

See section [Setting a Custom Fee Recipient](#setting-a-custom-fee-recipient)

### Alloc[​](#alloc "Direct link to heading")

The fields `nonce`, `timestamp`, `extraData`, `gasLimit`, `difficulty`, `mixHash`, `coinbase`, `number`, `gasUsed`, `parentHash` defines the genesis block header. The field `gasLimit` should be set to match the `gasLimit` set in the `feeConfig`. You do not need to change any of the other genesis header fields.

`nonce`, `mixHash` and `difficulty` are remnant parameters from Proof of Work systems. For Lux, these don't play any relevant role, so you should just leave them as their default values:

`nonce`: The result of the mining process iteration is this value. It can be any value in the genesis block. Default value is `0x0`.

`mixHash`: The combination of `nonce` and `mixHash` allows to verify that the Block has really been cryptographically mined, thus, from this aspect, is valid. Default value is `0x0000000000000000000000000000000000000000000000000000000000000000`.

`difficulty`: The difficulty level applied during the nonce discovering process of this block. Default value is `0x0`.

`timestamp`: The timestamp of the creation of the genesis block. This is commonly set to `0x0`.

`extraData`: Optional extra data that can be included in the genesis block. This is commonly set to `0x`.

`gasLimit`: The total amount of gas that can be used in a single block. It should be set to the same value as in the [fee config](#fee-config). The value `e4e1c0` is hexadecimal and is equal to `15,000,000`.

`coinbase`: Refers to the address of the block producers. This also means it represents the recipient of the block reward. It is usually set to `0x0000000000000000000000000000000000000000` for the genesis block. To allow fee recipients in Subnet-EVM, refer to [this section.](#setting-a-custom-fee-recipient)

`parentHash`: This is the Keccak 256-bit hash of the entire parent block's header. It is usually set to `0x0000000000000000000000000000000000000000000000000000000000000000` for the genesis block.

`gasUsed`: This is the amount of gas used by the genesis block. It is usually set to `0x0`.

`number`: This is the number of the genesis block. This required to be `0x0` for the genesis. Otherwise it will error.

### Genesis Examples[​](#genesis-examples "Direct link to heading")

Another example of a genesis file can be found in the [networks folder](https://github.com/luxfi/public-chain-assets/blob/1951594346dcc91682bdd8929bcf8c1bf6a04c33/chains/11111/genesis.json). Please remove `airdropHash` and `airdropAmount` fields if you want to start with it.

Here are a few examples on how a genesis file is used: [scripts/run.sh](https://github.com/luxfi/subnet-evm/blob/master/scripts/run.sh#L99)

### Setting the Genesis Allocation[​](#setting-the-genesis-allocation "Direct link to heading")

Alloc defines addresses and their initial balances. This should be changed accordingly for each chain. If you don't provide any genesis allocation, you won't be able to interact with your new chain (all transactions require a fee to be paid from the sender's balance).

The `alloc` field expects key-value pairs. Keys of each entry must be a valid `address`. The `balance` field in the value can be either a `hexadecimal` or `number` to indicate initial balance of the address. The default value contains `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` with `50000000000000000000000000` balance in it. Default:

```json
"alloc": {
  "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
    "balance": "0x295BE96E64066972000000"
  }
}
```

To specify a different genesis allocation, populate the `alloc` field in the genesis JSON as follows:

```json
"alloc": {
  "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
    "balance": "0x52B7D2DCC80CD2E4000000"
  },
  "Ab5801a7D398351b8bE11C439e05C5B3259aeC9B": {
    "balance": "0xa796504b1cb5a7c0000"
  }
},
```

The keys in the allocation are [hex](https://en.wikipedia.org/wiki/Hexadecimal) addresses **without the canonical `0x` prefix**. The balances are denominated in Wei ([10^18 Wei = 1 Whole Unit of Native Token](https://eth-converter.com/)) and expressed as hex strings **with the canonical `0x` prefix**. You can use [this converter](https://www.rapidtables.com/convert/number/hex-to-decimal.html) to translate between decimal and hex numbers.

The above example yields the following genesis allocations (denominated in whole units of the native token, that is 1 LUX/1 WAGMI):

```bash
0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC: 100000000 (0x52B7D2DCC80CD2E4000000=100000000000000000000000000 Wei)
0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B: 49463 (0xa796504b1cb5a7c0000=49463000000000000000000 Wei)
```

### Setting a Custom Fee Recipient[​](#setting-a-custom-fee-recipient "Direct link to heading")

By default, all fees are burned (sent to the black hole address with `"allowFeeRecipients": false`). However, it is possible to enable block producers to set a fee recipient (who will get compensated for blocks they produce).

To enable this feature, you'll need to add the following to your genesis file (under the `"config"` key):

```json
{
  "config": {
    "allowFeeRecipients": true
  }
}
```

#### Fee Recipient Address[​](#fee-recipient-address "Direct link to heading")

With `allowFeeRecipients` enabled, your validators can specify their addresses to collect fees. They need to update their EVM [chain config](#luxgo-chain-configs) with the following to specify where the fee should be sent to.

```json
{
  "feeRecipient": "<YOUR 0x-ADDRESS>"
}
```

<Callout type="warn">
If `allowFeeRecipients` feature is enabled on the Lux L1, but a validator doesn't specify a "feeRecipient", the fees will be burned in blocks it produces.
</Callout>

This mechanism can be also activated as a precompile. See [Changing Fee Reward Mechanisms](#changing-fee-reward-mechanisms) section for more details.

Precompiles[​](#precompiles "Direct link to heading")
-----------------------------------------------------

Subnet-EVM can provide custom functionalities with precompiled contracts. These precompiled contracts can be activated through `ChainConfig` (in genesis or as an upgrade).

### AllowList Interface[​](#allowlist-interface "Direct link to heading")

The `AllowList` interface is used by precompiles to check if a given address is allowed to use a precompiled contract. `AllowList` consist of three roles, `Admin`, `Manager` and `Enabled`. `Admin` can add/remove other `Admin` and `Enabled` addresses. `Manager` is introduced with Durango upgrade and can add/remove `Enabled` addresses, without the ability to add/remove `Admin` or `Manager` addresses. `Enabled` addresses can use the precompiled contract, but cannot modify other roles.

`AllowList` adds `adminAddresses`, `managerAddresses`, `enabledAddresses` fields to precompile contract configurations. For instance fee manager precompile contract configuration looks like this:

```json
{
  "feeManagerConfig": {
    "blockTimestamp": 0,
    "adminAddresses": [<list of addresses>],
    "managerAddresses": [<list of addresses>],
    "enabledAddresses": [<list of addresses>],
  }
}
```

`AllowList` configuration affects only the related precompile. For instance, the admin address in `feeManagerConfig` does not affect admin addresses in other activated precompiles.

The `AllowList` solidity interface is defined as follows, and can be found in [IAllowList.sol](https://github.com/luxfi/subnet-evm/blob/helloworld-official-tutorial-v2/contracts/contracts/interfaces/IAllowList.sol):

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

interface IAllowList {
  event RoleSet(
    uint256 indexed role,
    address indexed account,
    address indexed sender,
    uint256 oldRole
  );

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

`readAllowList(addr)` will return a uint256 with a value of 0, 1, or 2, corresponding to the roles `None`, `Enabled`, and `Admin` respectively.

`RoleSet` is an event that is emitted when a role is set for an address. It includes the role, the modified address, the sender as indexed parameters and the old role as non-indexed parameter. Events in precompiles are activated after Durango upgrade.

Note: `AllowList` is not an actual contract but just an interface. It's not callable by itself. This is used by other precompiles. Check other precompile sections to see how this works.

### Restricting Smart Contract Deployers[​](#restricting-smart-contract-deployers "Direct link to heading")

If you'd like to restrict who has the ability to deploy contracts on your Lux L1, you can provide an `AllowList` configuration in your genesis or upgrade file:

```json
{
  "contractDeployerAllowListConfig": {
    "blockTimestamp": 0,
    "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

In this example, `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is named as the `Admin` of the `ContractDeployerAllowList`. This enables it to add other `Admin` or to add `Enabled` addresses. Both `Admin` and `Enabled` can deploy contracts. To provide a great UX with factory contracts, the `tx.Origin` is checked for being a valid deployer instead of the caller of `CREATE`. This means that factory contracts will still be able to create new contracts as long as the sender of the original transaction is an allow listed deployer.

The `Stateful Precompile` contract powering the `ContractDeployerAllowList` adheres to the [AllowList Solidity interface](#allowlist-interface) at `0x0200000000000000000000000000000000000000` (you can load this interface and interact directly in Remix):

- If you attempt to add a `Enabled` and you are not an `Admin`, you will see something like: ![admin fail](/images/customize1.png)   
- If you attempt to deploy a contract but you are not an `Admin` not a `Enabled`, you will see something like: ![deploy fail](/images/customize2.png)
- If you call `readAllowList(addr)` then you can read the current role of `addr`, which will return a uint256 with a value of 0, 1, or 2, corresponding to the roles `None`, `Enabled`, and `Admin` respectively.

<Callout type="warn">
If you remove all of the admins from the allow list, it will no longer be possible to update the allow list without modifying the Subnet-EVM to schedule a network upgrade.
</Callout>

#### Initial Contract Allow List Configuration[​](#initial-contract-allow-list-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to manage the deployer list. With this, you can define a list of addresses that are allowed to deploy contracts. Since there will be no admin address to manage the deployer list, it can only be modified through a network upgrade.

To use initial configuration, you need to specify addresses in `enabledAddresses` field in your genesis or upgrade file:

```json
{
  "contractDeployerAllowListConfig": {
    "blockTimestamp": 0,
    "enabledAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

This will allow only `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` to deploy contracts. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Restricting Who Can Submit Transactions[​](#restricting-who-can-submit-transactions "Direct link to heading")

Similar to restricting contract deployers, this precompile restricts which addresses may submit transactions on chain. Like the previous section, you can activate the precompile by including an `AllowList` configuration in your genesis file:

```json
{
  "config": {
    "txAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

In this example, `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is named as the `Admin` of the `TransactionAllowList`. This enables them to add other `Admins` or to add `Allowed`. `Admins`, `Manager` and `Enabled` can submit transactions to the chain.

The `Stateful Precompile` contract powering the `TxAllowList` adheres to the [AllowList Solidity interface](#allowlist-interface) at `0x0200000000000000000000000000000000000002` (you can load this interface and interact directly in Remix):

- If you attempt to add an `Enabled` and you are not an `Admin`, you will see something like: ![admin fail](/images/customize3.png)   
- If you attempt to submit a transaction but you are not an `Admin`, `Manager` or not `Enabled`, you will see something like: `cannot issue transaction from non-allow listed address` 
- If you call `readAllowList(addr)` then you can read the current role of `addr`, which will return a `uint256` with a value of 0, 1, 2 or 3 corresponding to the roles `None`, `Allowed`, `Admin` and `Manager` respectively.

<Callout type="warn">
If you remove all of the admins and managers from the allow list, it will no longer be possible to update the allow list without modifying the Subnet-EVM to schedule a network upgrade.
</Callout>

#### Initial TX Allow List Configuration[​](#initial-tx-allow-list-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to manage the TX allow list. With this, you can define a list of addresses that are allowed to submit transactions.

Since there will be no admin address to manage the TX list, it can only be modified through a network upgrade. To use initial configuration, you need to specify addresses in `enabledAddresses` field in your genesis or upgrade file:

```json
{
  "txAllowListConfig": {
    "blockTimestamp": 0,
    "enabledAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

This will allow only `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` to submit transactions. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Minting Native Coins[​](#minting-native-coins "Direct link to heading")

You can mint native(gas) coins with a precompiled contract. In order to activate this feature, you can provide `nativeMinterConfig` in genesis:

```json
{
  "config": {
    "contractNativeMinterConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

`adminAddresses` denotes admin accounts who can add other `Admin`, `Manager` or `Enabled` accounts. `Admin`, `Manager` and `Enabled` are both eligible to mint native coins for other addresses. `ContractNativeMinter` uses same methods as in `ContractDeployerAllowList`.

The `Stateful Precompile` contract powering the `ContractNativeMinter` adheres to the following Solidity interface at `0x0200000000000000000000000000000000000001` (you can load this interface and interact directly in Remix):

```solidity
// (c) 2022-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

pragma solidity ^0.8.0;
import "./IAllowList.sol";

interface INativeMinter is IAllowList {
  event NativeCoinMinted(
    address indexed sender,
    address indexed recipient,
    uint256 amount
  );

  // Mint [amount] number of native coins and send to [addr]
  function mintNativeCoin(address addr, uint256 amount) external;
}
```

`mintNativeCoin` takes an address and amount of native coins to be minted. The amount denotes the amount in minimum denomination of native coins (10^18). For example, if you want to mint 1 native coin (in LUX), you need to pass 1 \* 10^18 as the amount. A `NativeCoinMinted` event is emitted with the sender, recipient and amount when a native coin is minted.

Note that this uses `IAllowList` interface directly, meaning that it uses the same `AllowList` interface functions like `readAllowList` and `setAdmin`, `setManager`, `setEnabled`, `setNone`. For more information see [AllowList Solidity interface](#allowlist-interface).

<Callout type="warn">
EVM does not prevent overflows when storing the address balance. Overflows in balance opcodes are handled by setting the balance to maximum. However the same won't apply for API calls. If you try to mint more than the maximum balance, API calls will return the overflowed hex-balance. This can break external tooling. Make sure the total supply of native coins is always less than 2^256-1.
</Callout>

#### Initial Native Minter Configuration[​](#initial-native-minter-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to mint native coins. With this, you can define a list of addresses that will receive an initial mint of the native coin when this precompile activates. This can be useful for networks that require a one-time mint without specifying any admin addresses. To use initial configuration, you need to specify a map of addresses with their corresponding mint amounts in `initialMint` field in your genesis or upgrade file:

```json
{
  "contractNativeMinterConfig": {
    "blockTimestamp": 0,
    "initialMint": {
      "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": "1000000000000000000",
      "0x10037Fb06Ec4aB8c870a92AE3f00cD58e5D484b3": "0xde0b6b3a7640000"
    }
  }
}
```

In the amount field you can specify either decimal or hex string. This will mint 1000000000000000000 (equivalent of 1 Native Coin denominated as 10^18) to both addresses. Note that these are both in string format. "0xde0b6b3a7640000" hex is equivalent to 1000000000000000000. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Configuring Dynamic Fees[​](#configuring-dynamic-fees "Direct link to heading")


You can configure the parameters of the dynamic fee algorithm on chain using the `FeeConfigManager`. In order to activate this feature, you will need to provide the `FeeConfigManager` in the genesis:

```json
{
  "config": {
    "feeManagerConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

The precompile implements the `FeeManager` interface which includes the same `AllowList` interface used by ContractNativeMinter, TxAllowList, etc. For an example of the `AllowList` interface, see the [TxAllowList](#allowlist-interface) above.

The `Stateful Precompile` contract powering the `FeeConfigManager` adheres to the following Solidity interface at `0x0200000000000000000000000000000000000003` (you can load this interface and interact directly in Remix). It can be also found in [IFeeManager.sol](https://github.com/luxfi/subnet-evm/blob/5faabfeaa021a64c2616380ed2d6ec0a96c8f96d/contract-examples/contracts/IFeeManager.sol):

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "./IAllowList.sol";

interface IFeeManager is IAllowList {
  struct FeeConfig {
    uint256 gasLimit;
    uint256 targetBlockRate;
    uint256 minBaseFee;
    uint256 targetGas;
    uint256 baseFeeChangeDenominator;
    uint256 minBlockGasCost;
    uint256 maxBlockGasCost;
    uint256 blockGasCostStep;
  }
  event FeeConfigChanged(
    address indexed sender,
    FeeConfig oldFeeConfig,
    FeeConfig newFeeConfig
  );

  // Set fee config fields to contract storage
  function setFeeConfig(
    uint256 gasLimit,
    uint256 targetBlockRate,
    uint256 minBaseFee,
    uint256 targetGas,
    uint256 baseFeeChangeDenominator,
    uint256 minBlockGasCost,
    uint256 maxBlockGasCost,
    uint256 blockGasCostStep
  ) external;

  // Get fee config from the contract storage
  function getFeeConfig()
    external
    view
    returns (
      uint256 gasLimit,
      uint256 targetBlockRate,
      uint256 minBaseFee,
      uint256 targetGas,
      uint256 baseFeeChangeDenominator,
      uint256 minBlockGasCost,
      uint256 maxBlockGasCost,
      uint256 blockGasCostStep
    );

  // Get the last block number changed the fee config from the contract storage
  function getFeeConfigLastChangedAt()
    external
    view
    returns (uint256 blockNumber);
}
```

FeeConfigManager precompile uses `IAllowList` interface directly, meaning that it uses the same `AllowList` interface functions like `readAllowList` and `setAdmin`, `setManager`, `setEnabled`, `setNone`. For more information see [AllowList Solidity interface](#allowlist-interface).

In addition to the `AllowList` interface, the FeeConfigManager adds the following capabilities:

- `getFeeConfig`: retrieves the current dynamic fee config
- `getFeeConfigLastChangedAt`: retrieves the timestamp of the last block where the fee config was updated
- `setFeeConfig`: sets the dynamic fee config on chain (see [here](#fee-config) for details on the fee config parameters). This function can only be called by an `Admin`, `Manager` or `Enabled` address.
- `FeeConfigChanged`: an event that is emitted when the fee config is updated. Topics include the sender, the old fee config, and the new fee config.

You can also get the fee configuration at a block with the `eth_feeConfig` RPC method. For more information see [here](/docs/rpcs/subnet-evm#eth_feeconfig).

#### Initial Fee Config Configuration[​](#initial-fee-config-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to define your fee structure to take effect at the activation.

To use the initial configuration, you need to specify the fee config in `initialFeeConfig` field in your genesis or upgrade file:

```json
{
  "feeManagerConfig": {
    "blockTimestamp": 0,
    "initialFeeConfig": {
      "gasLimit": 20000000,
      "targetBlockRate": 2,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "blockGasCostStep": 500000
    }
  }
}
```

This will set the fee config to the values specified in the `initialFeeConfig` field. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Lux Warp Messaging[​](#lux-warp-messaging "Direct link to heading")

<Callout type="warn">
Currently Warp Precompile can only be activated in Mainnet after Durango occurs. Durango in Mainnet is set at 11 AM ET (4 PM UTC) on Wednesday, March 6th, 2024. If you plan to use Warp messaging in your own Subnet-EVM chain in Mainnet you should upgrade to LuxGo 1.11.11 or later and coordinate your precompile upgrade. Warp Config's "blockTimestamp" must be set after `1709740800`, Durango date (11 AM ET (4 PM UTC) on Wednesday, March 6th, 2024).
</Callout>

Contract Examples[​](#contract-examples "Direct link to heading")
-----------------------------------------------------------------

Subnet-EVM contains example contracts for precompiles under `/contracts`. It's a hardhat project with tests and tasks. For more information see [contract examples README](https://github.com/luxfi/subnet-evm/tree/master/contracts#subnet-evm-contracts).

Network Upgrades: Enable/Disable Precompiles[​](#network-upgrades-enabledisable-precompiles "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

<Callout type="warn">
Performing a network upgrade requires coordinating the upgrade network-wide. A network upgrade changes the rule set used to process and verify blocks, such that any node that upgrades incorrectly or fails to upgrade by the time that upgrade goes into effect may become out of sync with the rest of the network.

Any mistakes in configuring network upgrades or coordinating them on validators may cause the network to halt and recovering may be difficult.
</Callout>

In addition to specifying the configuration for each of the above precompiles in the genesis chain config, they can be individually enabled or disabled at a given timestamp as a network upgrade. Disabling a precompile disables calling the precompile and destructs its storage so it can be enabled at a later timestamp with a new configuration if desired.

These upgrades must be specified in a file named `upgrade.json` placed in the same directory where [`config.json`](#luxgo-chain-configs) resides: `{chain-config-dir}/{blockchainID}/upgrade.json`. For example, `WAGMI Subnet` upgrade should be placed in `~/.luxgo/configs/chains/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/upgrade.json`.

The content of the `upgrade.json` should be formatted according to the following:

```json
{
  "precompileUpgrades": [
    {
      "[PRECOMPILE_NAME]": {
        "blockTimestamp": "[ACTIVATION_TIMESTAMP]", // unix timestamp precompile should activate at
        "[PARAMETER]": "[VALUE]" // precompile specific configuration options, eg. "adminAddresses"
      }
    }
  ]
}
```

<Callout type="warn">
An invalid `blockTimestamp` in an upgrade file results the update failing. The `blockTimestamp` value should be set to a valid Unix timestamp value which is in the _future_ relative to the _head of the chain_. If the node encounters a `blockTimestamp` which is in the past, it will fail on startup.
</Callout>

To disable a precompile, the following format should be used:

```json
{
  "precompileUpgrades": [
    {
      "<precompileName>": {
        "blockTimestamp": "[DEACTIVATION_TIMESTAMP]", // unix timestamp the precompile should deactivate at
        "disable": true
      }
    }
  ]
}
```

Each item in `precompileUpgrades` must specify exactly one precompile to enable or disable and the block timestamps must be in increasing order. Once an upgrade has been activated (a block after the specified timestamp has been accepted), it must always be present in `upgrade.json` exactly as it was configured at the time of activation (otherwise the node will refuse to start).

Enabling and disabling a precompile is a network upgrade and should always be done with caution.

<Callout type="warn">
For safety, you should always treat `precompileUpgrades` as append-only.

As a last resort measure, it is possible to abort or reconfigure a precompile upgrade that has not been activated since the chain is still processing blocks using the prior rule set.
</Callout>

If aborting an upgrade becomes necessary, you can remove the precompile upgrade from `upgrade.json` from the end of the list of upgrades. As long as the blockchain has not accepted a block with a timestamp past that upgrade's timestamp, it will abort the upgrade for that node.

### Example[​](#example "Direct link to heading")

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "txAllowListConfig": {
        "blockTimestamp": 1668960000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668970000,
        "disable": true
      }
    }
  ]
}
```

This example enables the `feeManagerConfig` at the first block with timestamp >= `1668950000`, enables `txAllowListConfig` at the first block with timestamp >= `1668960000`, and disables `feeManagerConfig` at the first block with timestamp >= `1668970000`.

When a precompile disable takes effect (that is, after its `blockTimestamp` has passed), its storage will be wiped. If you want to reenable it, you will need to treat it as a new configuration.

After you have created the `upgrade.json` and placed it in the chain config directory, you need to restart the node for the upgrade file to be loaded (again, make sure you don't restart all Lux L1 validators at once!). On node restart, it will print out the configuration of the chain, where you can double-check that the upgrade has loaded correctly. In our example:

```bash
INFO [08-15|15:09:36.772] <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain>
github.com/luxfi/subnet-evm/eth/backend.go:155: Initialised chain configuration
config=“{ChainID: 11111 Homestead: 0 EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0
Constantinople: 0 Petersburg: 0 Istanbul: 0, Muir Glacier: 0, Subnet EVM: 0, FeeConfig:
{\“gasLimit\“:20000000,\“targetBlockRate\“:2,\“minBaseFee\“:1000000000,\“targetGas\
“:100000000,\“baseFeeChangeDenominator\“:48,\“minBlockGasCost\“:0,\“maxBlockGasCost\
“:10000000,\“blockGasCostStep\“:500000}, AllowFeeRecipients: false, NetworkUpgrades: {\
“subnetEVMTimestamp\“:0}, PrecompileUpgrade: {}, UpgradeConfig: {\"precompileUpgrades\":[{\"feeManagerConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668950000}},{\"txAllowListConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668960000}},{\"feeManagerConfig\":{\"adminAddresses\":null,\"enabledAddresses\":null,\"blockTimestamp\":1668970000,\"disable\":true}}]}, Engine: Dummy Consensus Engine}"
```

Notice that `precompileUpgrades` entry correctly reflects the changes. You can also check the activated precompiles at a timestamp with the [`eth_getActivePrecompilesAt`](/docs/rpcs/subnet-evm#eth_getactiveprecompilesat) RPC method. The [`eth_getChainConfig`](/docs/rpcs/subnet-evm#eth_getchainconfig) RPC method will also return the configured upgrades in the response.

That's it, your Lux L1 is all set and the desired upgrades will be activated at the indicated timestamp!

### Initial Precompile Configurations[​](#initial-precompile-configurations "Direct link to heading")

Precompiles can be managed by some privileged addresses to change their configurations and activate their effects. For example, the `feeManagerConfig` precompile can have `adminAddresses` which can change the fee structure of the network.

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    }
  ]
}
```

In this example, only the address `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is allowed to change the fee structure of the network. The admin address has to call the precompile in order to activate its effect; that is it needs to send a transaction with a new fee config to perform the update. This is a very powerful feature, but it also gives a large amount of power to the admin address. If the address `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is compromised, the network is compromised.

With the initial configurations, precompiles can immediately activate their effect on the activation timestamp. With this way admin addresses can be omitted from the precompile configuration. For example, the `feeManagerConfig` precompile can have `initialFeeConfig` to setup the fee configuration on the activation:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "initialFeeConfig": {
          "gasLimit": 20000000,
          "targetBlockRate": 2,
          "minBaseFee": 1000000000,
          "targetGas": 100000000,
          "baseFeeChangeDenominator": 48,
          "minBlockGasCost": 0,
          "maxBlockGasCost": 10000000,
          "blockGasCostStep": 500000
        }
      }
    }
  ]
}
```

Notice that there is no `adminAddresses` field in the configuration. This means that there will be no admin addresses to manage the fee structure with this precompile. The precompile will simply update the fee configuration to the specified fee config when it activates on the `blockTimestamp` `1668950000`.

<Callout title="Note">
It's still possible to add `adminAddresses` or `enabledAddresses` along with these initial configurations. In this case, the precompile will be activated with the initial configuration, and admin/enabled addresses can access to the precompiled contract normally.
</Callout>

<Callout title="Note">
If you want to change the precompile initial configuration, you will need to first disable it then activate the precompile again with the new configuration.
</Callout>

See every precompile initial configuration in their relevant `Initial Configuration` sections under [Precompiles](#precompiles).

LuxGo Chain Configs[​](#luxgo-chain-configs "Direct link to heading")
---------------------------------------------------------------------------------

As described in [this doc](/docs/nodes/configure/configs-flags#lux-l1-chain-configs), each blockchain of Lux L1s can have its own custom configuration. If an Lux L1's ChainID is `2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt`, the config file for this chain is located at `{chain-config-dir}/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/config.json`.

For blockchains created by or forked from Subnet-EVM, most [LUExchange-Chain configs](/docs/nodes/chain-configs/primary-network/c-chain) are applicable except [Lux Specific APIs](/docs/nodes/chain-configs/primary-network/c-chain#enabling-lux-specific-apis).

### Priority Regossip[​](#priority-regossip "Direct link to heading")

A transaction is "regossiped" when the node does not find the transaction in a block after `priority-regossip-frequency` (defaults to `1m`). By default, up to 16 transactions (max 1 per address) are regossiped to validators per minute.

Operators can use "priority regossip" to more aggressively "regossip" transactions for a set of important addresses (like bridge relayers). To do so, you'll need to update your [chain config](/docs/nodes/configure/configs-flags#lux-l1-chain-configs) with the following:

```json
{
  "priority-regossip-addresses": ["<YOUR 0x-ADDRESS>"]
}
```

By default, up to 32 transactions from priority addresses (max 16 per address) are regossipped to validators per second. You can override these defaults with the following config:

```json
{
  "priority-regossip-frequency": "1s",
  "priority-regossip-max-txs": 32,
  "priority-regossip-addresses": ["<YOUR 0x-ADDRESS>"],
  "priority-regossip-txs-per-address": 16
}
```

### Fee Recipient[​](#fee-recipient "Direct link to heading")

This works together with [`allowFeeRecipients`](#setting-a-custom-fee-recipient) and [RewardManager precompile](/docs/lux-l1s/precompiles/reward-manager) to specify where the fees should be sent to.

With `allowFeeRecipients` enabled, validators can specify their addresses to collect fees.

```json
{
  "feeRecipient": "<YOUR 0x-ADDRESS>"
}
```

<Callout type="warn">
If `allowFeeRecipients` or `RewardManager` precompile is enabled on the Lux L1, but a validator doesn't specify a "feeRecipient", the fees will be burned in blocks it produces.
</Callout>

### Archival Node Configuration[​](#archival-node-configuration "Direct link to heading")

Running an archival node that retains all historical state data requires specific configuration settings. Incorrect configuration can lead to historical data being pruned despite attempts to run in archival mode. Here are the key settings to configure:

#### Disabling Pruning

To retain all historical state, you must disable pruning. For EVM chains (like LUExchange-Chain or Subnet-EVM chains), add the following to your chain's `config.json`:

```json
{
  "pruning-enabled": false
}
```

#### State Sync Considerations

State sync allows nodes to quickly sync by downloading recent state without processing all historical blocks. This can lead to missing historical data. For archival nodes, either disable state sync or ensure you start from genesis:

```json
{
  "state-sync-enabled": false
}
```

#### Transaction History Settings

To maintain access to all historical transactions, you might need to configure these additional settings:

```json
{
  "transaction-history": 0
}
```

#### Database Considerations

<Callout type="warn">
Important: An already synced database cannot be fully converted to an archival node retroactively. The cleanest and most reliable way to set up an archival node is to start from scratch with the proper configuration.
</Callout>

When switching between database types (e.g., from LevelDB to PebbleDB), historical data does not carry over. If you need to change the database type for your archival node, you must start a fresh sync from genesis.

For information about all available configuration options and directory structures, see the [LuxGo Config Flags documentation](https://build.lux.network/docs/nodes/configure/configs-flags).

Network Upgrades: State Upgrades[​](#network-upgrades-state-upgrades "Direct link to heading")
----------------------------------------------------------------------------------------------

Subnet-EVM allows the network operators to specify a modification to state that will take place at the beginning of the first block with a timestamp greater than or equal to the one specified in the configuration.

This provides a last resort path to updating non-upgradeable contracts via a network upgrade (for example, to fix issues when you are running your own blockchain).

<Callout type="warn">
This should only be used as a last resort alternative to forking `subnet-evm` and specifying the network upgrade in code.

Using a network upgrade to modify state is not part of normal operations of the EVM. You should ensure the modifications do not invalidate any of the assumptions of deployed contracts or cause incompatibilities with downstream infrastructure such as block explorers.
</Callout>

The timestamps for upgrades in `stateUpgrades` must be in increasing order. `stateUpgrades` can be specified along with `precompileUpgrades` or by itself.

The following three state modifications are supported:

- `balanceChange`: adds a specified amount to the balance of a given account. This amount can be specified as hex or decimal and must be positive.
- `storage`: modifies the specified storage slots to the specified values. Keys and values must be 32 bytes specified in hex, with a `0x` prefix.
- `code`: modifies the code stored in the specified account. The code must _only_ be the runtime portion of a code. The code must start with a `0x` prefix.

<Callout type="warn">
If modifying the code, _only_ the runtime portion of the bytecode should be provided in `upgrades.json`. Do not use the bytecode that would be used for deploying a new contract, as this includes the constructor code as well. Refer to your compiler's documentation for information on how to find the runtime portion of the contract you wish to modify.
</Callout>

The `upgrades.json` file shown below describes a network upgrade that will make the following state modifications at the first block after (or at) `March 8, 2023 1:30:00 AM GMT`:

- Sets the code for the account at `0x71562b71999873DB5b286dF957af199Ec94617F7`,
- And adds `100` wei to the balance of the account at `0xb794f5ea0ba39494ce839613fffba74279579268`,
- Sets the storage slot `0x1234` to the value `0x6666` for the account at `0xb794f5ea0ba39494ce839613fffba74279579268`.

```json
{
  "stateUpgrades": [
    {
      "blockTimestamp": 1678239000,
      "accounts": {
        "0x71562b71999873DB5b286dF957af199Ec94617F7": {
          "code": "0x6080604052348015600f57600080fd5b506004361060285760003560e01c80632e64cec114602d575b600080fd5b60336047565b604051603e91906067565b60405180910390f35b60008054905090565b6000819050919050565b6061816050565b82525050565b6000602082019050607a6000830184605a565b9291505056fea26469706673582212209421042a1fdabcfa2486fb80942da62c28e61fc8362a3f348c4a96a92bccc63c64736f6c63430008120033"
        },
        "0xb794f5ea0ba39494ce839613fffba74279579268": {
          "balanceChange": "0x64",
          "storage": {
            "0x0000000000000000000000000000000000000000000000000000000000001234": "0x0000000000000000000000000000000000000000000000000000000000006666"
          }
        }
      }
    }
  ]
}
```

Network Upgrades: Rescheduling Mandatory Network Upgrades[​](#network-upgrades-rescheduling-mandatory-network-upgrades "Direct link to heading")
------------------------------------------------------------------------------------------------------------------------------------------------

A typical case when a network misses any mandatory activation would result in a network that is not able to operate. This is because validators/nodes running the old version would process transactions differently than nodes running the new version and end up different state. This would result in a fork in the network and new nodes would not be able to sync with the network. Normally this puts the chain in a halt and requires a hard fork to fix the issue. Starting with Subnet-EVM v0.6.3, you can reschedule mandatory activations like Durango via upgrade configs (upgrade.json in chain directory). This is a very advanced operation and should be done only if your network cannot operate going forward. The reschedule operation should be coordinated with your entire network nodes. Network upgrade overrides can be defined in the `upgrade.json` as follows:

```json
{
  "networkUpgradeOverrides": {
    "{networkUpgrade1}": timestamp1,
    "{networkUpgrade2}": timestamp2,
  }
}
```

The `timestamp` should be a Unix timestamp in seconds.

For instance, if you missed the Durango activation in Testnet (February 13th, 2024, 16:00 UTC) or Mainnet (March 6th, 2024, 16:00 UTC) and having issues in your network, you can reschedule the Durango activation via upgrades. In order to do this, you need to prepare a new upgrade.json including following:

```json
{
  "networkUpgradeOverrides": {
    "durangoTimestamp": 1712419200
  }
}
```

This reschedules the Durango activation to 2024-11-06 16:00:00 UTC (one month later than the actual activation). After preparing the upgrade.json, you need to update the chain directory with the new upgrade.json and restart your nodes. You should see logs similar to the following:

```bash
INFO [03-22|14:04:48.284] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/luxfi/subnet-evm/plugin/evm/vm.go:367: Applying network upgrade overrides overrides="{\"durangoTimestamp\":1712419200}"
...
INFO [03-22|14:04:48.288] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/luxfi/subnet-evm/core/blockchain.go:335: Lux Upgrades (timestamp based):
INFO [03-22|14:04:48.288] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/luxfi/subnet-evm/core/blockchain.go:335:  - SubnetEVM Timestamp:           @0          (https://github.com/luxfi/luxgo/releases/tag/v1.10.0)
INFO [03-22|14:04:48.288] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/luxfi/subnet-evm/core/blockchain.go:335:  - Durango Timestamp:            @1712419200 (https://github.com/luxfi/luxgo/releases/tag/v1.11.0)
...
```

This means your node is lock and loaded for the new Durango activation. After the new timestamp is reached, your node will activate Durango and start processing transactions with the new Durango features.

<Callout type="warn">
Nodes running non-compatible version (running pre-Durango version after Durango activation), should be updated to most recent version of Subnet-EVM (v0.6.3+) and must have the new upgrade.json to reschedule the Durango activation. Running a new version without the rescheduling upgrade.json might create a fork in the network.

All of network nodes, even ones correctly upgraded to Durango and running the correct version since Durango activation, should be restarted with the new upgrade.json to reschedule the Durango activation. This is a network-wide operation and should be coordinated with all network nodes.
</Callout>

# Introduction (/docs/lux-l1s/evm-configuration/evm-l1-customization)

---
title: Introduction
description: Learn how to customize the Ethereum Virtual Machine with EVM and Precompiles.
root: true
---

Welcome to the EVM configuration guide. This documentation explores how to extend and customize your Lux L1 using **EVM** and **precompiles**. Building upon the Validator Manager capabilities we discussed in the previous section, we'll now dive into other powerful customization features available in EVM.

## Overview of EVM

EVM is Lux's customized version of the Ethereum Virtual Machine, tailored to run on Lux L1s. It allows developers to deploy Solidity smart contracts with enhanced capabilities, benefiting from Lux's high throughput and low latency. EVM enables more flexibility and performance optimizations compared to the standard EVM.

Beyond the Validator Manager functionality we've covered, EVM provides additional configuration options through precompiles, allowing you to extend your L1's capabilities even further.

## Genesis Configuration

Each blockchain has some genesis state when it's created. Each Virtual Machine defines the format and semantics of its genesis data. The genesis configuration is crucial for setting up your Lux L1's initial state and behavior.

### Chain Configuration

The chain configuration section in your genesis file defines fundamental parameters of your blockchain:

```json
{
  "config": {
    "chainId": 43214,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0
  }
}
```

#### Chain ID
`chainID`: Denotes the ChainID of to be created chain. Must be picked carefully since a conflict with other chains can cause issues. One suggestion is to check with [chainlist.org](https://chainlist.org/) to avoid ID collision, reserve and publish your ChainID properly.

You can use `eth_getChainConfig` RPC call to get the current chain config. See [here](/docs/rpcs/subnet-evm#eth_getchainconfig) for more info.

#### Hard Forks
The following parameters define EVM hard fork activation times. These should be handled with care as changes may cause compatibility issues:
- `homesteadBlock`
- `eip150Block`
- `eip150Hash`
- `eip155Block`
- `byzantiumBlock`
- `constantinopleBlock`
- `petersburgBlock`
- `istanbulBlock`
- `muirGlacierBlock`

### Genesis Block Header

The genesis block header is defined by several parameters that set the initial state of your blockchain:

```json
{
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

These parameters have specific roles:

- `nonce`, `mixHash`, `difficulty`: These are remnants from Proof of Work systems. For Lux, they don't play any relevant role and should be left as their default values.
- `timestamp`: The creation timestamp of the genesis block (commonly set to `0x0`).
- `extraData`: Optional extra data field (commonly set to `0x`).
- `coinbase`: The address of block producers (usually set to zero address for genesis).
- `parentHash`: The hash of the parent block (set to zero hash for genesis).
- `gasUsed`: Amount of gas used by the genesis block (usually `0x0`).
- `number`: The block number (must be `0x0` for genesis).

## Precompiles

Precompiles are specialized smart contracts that execute native Go code within the EVM context. They act as a bridge between Solidity and lower-level functionalities, allowing for performance optimizations and access to features not available in Solidity alone.

### Default Precompiles in EVM

EVM comes with a set of default precompiles that extend the EVM's functionality:

- **[AllowList Interface](/docs/lux-l1s/precompiles/allowlist-interface)**: Interface that manages access control by allowing or restricting specific addresses, inherited by all precompiles.
- **[Deployer AllowList](/docs/lux-l1s/precompiles/deployer-allowlist)**: Restricts which addresses can deploy smart contracts.
- **[Transaction AllowList](/docs/lux-l1s/precompiles/transaction-allowlist)**: Controls which addresses can submit transactions.
- **[Native Minter](/docs/lux-l1s/precompiles/native-minter)**: Manages the minting and burning of native tokens.
- **[Fee Manager](/docs/lux-l1s/precompiles/fee-manager)**: Controls gas fee parameters and fee markets.
- **[Reward Manager](/docs/lux-l1s/precompiles/reward-manager)**: Handles the distribution of staking rewards to validators.
- **[Warp Messenger](/docs/lux-l1s/precompiles/warp-messenger)**: Enables cross-chain communication between Lux L1s.

### Precompile Addresses and Configuration

If a precompile is enabled within the `genesis.json` using the respective `ConfigKey`, you can interact with the precompile using Foundry or other tools such as Remix.

Below are the addresses and `ConfigKey` values of default precompiles available in EVM. The address and `ConfigKey` [are defined in the `module.go` of each precompile contract](https://github.com/luxfi/subnet-evm/tree/master/precompile/contracts).

| Precompile             | ConfigKey                         | Address                                      |
| ---------------------- | --------------------------------- | -------------------------------------------- |
| [Deployer AllowList](/docs/lux-l1s/precompiles/deployer-allowlist)     | `contractDeployerAllowListConfig` | `0x0200000000000000000000000000000000000000` |
| [Native Minter](/docs/lux-l1s/precompiles/native-minter)          | `contractNativeMinterConfig`      | `0x0200000000000000000000000000000000000001` |
| [Transaction AllowList](/docs/lux-l1s/precompiles/transaction-allowlist)  | `txAllowListConfig`               | `0x0200000000000000000000000000000000000002` |
| [Fee Manager](/docs/lux-l1s/precompiles/fee-manager)            | `feeManagerConfig`                | `0x0200000000000000000000000000000000000003` |
| [Reward Manager](/docs/lux-l1s/precompiles/reward-manager)         | `rewardManagerConfig`             | `0x0200000000000000000000000000000000000004` |
| [Warp Messenger](/docs/lux-l1s/precompiles/warp-messenger)         | `warpConfig`                      | `0x0200000000000000000000000000000000000005` |

#### Example Interaction

For example, if `contractDeployerAllowListConfig` is enabled in the `genesis.json`:

```json title="genesis.json"
 "contractDeployerAllowListConfig": {
      "adminAddresses": [ // Addresses that can manage (add/remove) enabled addresses. They are also enabled themselves for contract deployment.
        "0x4f9e12d407b18ad1e96e4f139ef1c144f4058a4e",
        "0x4b9e5977a46307dd93674762f9ddbe94fb054def"
      ],
      "blockTimestamp": 0,
      "enabledAddresses": [
        "0x09c6fa19dd5d41ec6d0f4ca6f923ec3d941cc569" // Addresses that can only deploy contracts
      ]
    },
```

We can then add an `Enabled` address to the Deployer AllowList by interacting with the `IAllowList` interface at `0x0200000000000000000000000000000000000000`:

```bash
cast send 0x0200000000000000000000000000000000000000 setEnabled(address addr) <ADDRESS_TO_ENABLE> --rpc-url $MY_L1_RPC --private-key $ADMIN_PRIVATE_KEY
```

# Complex Golang VM (/docs/lux-l1s/golang-vms/complex-golang-vm)

---
title: Complex Golang VM
description: In this tutorial, we'll walk through how to build a virtual machine by referencing the BlobVM.
---

The [BlobVM](https://github.com/luxfi/blobvm) is a virtual machine that can be used to implement a decentralized key-value store. A blob (shorthand for "binary large object") is an arbitrary piece of data.

BlobVM stores a key-value pair by breaking it apart into multiple chunks stored with their hashes as their keys in the blockchain. A root key-value pair has references to these chunks for lookups. By default, the maximum chunk size is set to 200 KiB.

## Components

A VM defines how a blockchain should be built. A block is populated with a set of transactions which mutate the state of the blockchain when executed. When a block with a set of transactions is applied to a given state, a state transition occurs by executing all of the transactions in the block in-order and applying it to the previous block of the blockchain. By executing a series of blocks chronologically, anyone can verify and reconstruct the state of the blockchain at an arbitrary point in time.

The BlobVM repository has a few components to handle the lifecycle of tasks from a transaction being issued to a block being accepted across the network:

- **Transaction**: A state transition
- **Mempool**: Stores pending transactions that haven't been finalized yet
- **Network**: Propagates transactions from the mempool other nodes in the network
- **Block**: Defines the block format, how to verify it, and how it should be accepted or rejected across the network
- **Block Builder**: Builds blocks by including transactions from the mempool
- **Virtual Machine**: Application-level logic. Implements the VM interface needed to interact with Lux consensus and defines the blueprint for the blockchain.
- **Service**: Exposes APIs so users can interact with the VM
- **Factory**: Used to initialize the VM

## Lifecycle of a Transaction

A VM will often times expose a set of APIs so users can interact with the it. In the blockchain, blocks can contain a set of transactions which mutate the blockchain's state. Let's dive into the lifecycle of a transaction from its issuance to its finalization on the blockchain.

- A user makes an API request to `service.IssueRawTx` to issue their transaction. This API will deserialize the user's transaction and forward it to the VM
- The transaction is submitted to the VM which is then added to the VM's mempool
- The VM asynchronously periodically gossips new transactions in its mempool to other nodes in the network so they can learn about them
- The VM sends the Lux consensus engine a message to indicate that it has transactions in the mempool that are ready to be built into a block
- The VM proposes the block with to consensus
- Consensus verifies that the block is valid and well-formed
- Consensus gets the network to vote on whether the block should be accepted or rejected. If a block is rejected, its transactions are reclaimed by the mempool so they can be included in a future block. If a block is accepted, it's finalized by writing it to the blockchain.

## Coding the Virtual Machine

We'll dive into a few of the packages that are in the The BlobVM repository to learn more about how they work:

1. [`vm`](https://github.com/luxfi/blobvm/tree/master/vm)
    - `block_builder.go`
    - `chain_vm.go`
    - `network.go`
    - `service.go`
    - `vm.go`
2. [`chain`](https://github.com/luxfi/blobvm/tree/master/chain)
    - `unsigned_tx.go`
    - `base_tx.go`
    - `transfer_tx.go`
    - `set_tx.go`
    - `tx.go`
    - `block.go`
    - `mempool.go`
    - `storage.go`
    - `builder.go`
3. [`mempool`](https://github.com/luxfi/blobvm/tree/master/mempool)
    - `mempool.go`

### Transactions

The state the blockchain can only be mutated by getting the network to accept a signed transaction. A signed transaction contains the transaction to be executed alongside the signature of the issuer. The signature is required to cryptographically verify the sender's identity. A VM can define an arbitrary amount of unique transactions types to support different operations on the blockchain. The BlobVM implements two different transactions types:

- [TransferTx](https://github.com/luxfi/blobvm/blob/master/chain/transfer_tx.go) - Transfers coins between accounts.
- [SetTx](https://github.com/luxfi/blobvm/blob/master/chain/set_tx.go) - Stores a key-value pair on the blockchain.

#### UnsignedTransaction

All transactions in the BlobVM implement the common [`UnsignedTransaction`](https://github.com/luxfi/blobvm/blob/master/chain/unsigned_tx.go) interface, which exposes shared functionality for all transaction types.

```go
type UnsignedTransaction interface {
	Copy() UnsignedTransaction
	GetBlockID() ids.ID
	GetMagic() uint64
	GetPrice() uint64
	SetBlockID(ids.ID)
	SetMagic(uint64)
	SetPrice(uint64)
	FeeUnits(*Genesis) uint64  // number of units to mine tx
	LoadUnits(*Genesis) uint64 // units that should impact fee rate

	ExecuteBase(*Genesis) error
	Execute(*TransactionContext) error
	TypedData() *tdata.TypedData
	Activity() *Activity
}
```

#### BaseTx

Common functionality and metadata for transaction types are implemented by [`BaseTx`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go).

- [`SetBlockID`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L26) sets the transaction's block ID.
- [`GetBlockID`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L22) returns the transaction's block ID.
- [`SetMagic`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L34) sets the magic number. The magic number is used to differentiate chains to prevent replay attacks
- [`GetMagic`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L30) returns the magic number. Magic number is defined in genesis.
- [`SetPrice`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L42) sets the price per fee unit for this transaction.
- [`GetPrice`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L38) returns the price for this transaction.
- [`FeeUnits`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L59) returns the fee units this transaction will consume.
- [`LoadUnits`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L63) identical to `FeeUnits`
- [`ExecuteBase`](https://github.com/luxfi/blobvm/blob/master/chain/base_tx.go#L46) executes common validation checks across different transaction types. This validates the transaction contains a valid block ID, magic number, and gas price as defined by genesis.

#### TransferTx

[`TransferTx`](https://github.com/luxfi/blobvm/blob/master/chain/transfer_tx.go#L16) supports the transfer of tokens from one account to another.

```go
type TransferTx struct {
	*BaseTx `serialize:"true" json:"baseTx"`

	// To is the recipient of the [Units].
	To common.Address `serialize:"true" json:"to"`

	// Units are transferred to [To].
	Units uint64 `serialize:"true" json:"units"`
}
```

`TransferTx` embeds `BaseTx` to avoid re-implementing common operations with other transactions, but implements its own [`Execute`](https://github.com/luxfi/blobvm/blob/master/chain/transfer_tx.go#L26) to support token transfers.

This performs a few checks to ensure that the transfer is valid before transferring the tokens between the two accounts.

```go
func (t *TransferTx) Execute(c *TransactionContext) error {
	// Must transfer to someone
	if bytes.Equal(t.To[:], zeroAddress[:]) {
		return ErrNonActionable
	}

	// This prevents someone from transferring to themselves.
	if bytes.Equal(t.To[:], c.Sender[:]) {
		return ErrNonActionable
	}
	if t.Units == 0 {
		return ErrNonActionable
	}
	if _, err := ModifyBalance(c.Database, c.Sender, false, t.Units); err != nil {
		return err
	}
	if _, err := ModifyBalance(c.Database, t.To, true, t.Units); err != nil {
		return err
	}
	return nil
}
```

#### SetTx

`SetTx` is used to assign a value to a key.

```go
type SetTx struct {
	*BaseTx `serialize:"true" json:"baseTx"`
	Value []byte `serialize:"true" json:"value"`
}
```

`SetTx` implements its own [`FeeUnits`](https://github.com/luxfi/blobvm/blob/master/chain/set_tx.go#L48) method to compensate the network according to the size of the blob being stored.

```go
func (s *SetTx) FeeUnits(g *Genesis) uint64 {
	// We don't subtract by 1 here because we want to charge extra for any
	// value-based interaction (even if it is small or a delete).
	return s.BaseTx.FeeUnits(g) + valueUnits(g, uint64(len(s.Value)))
}
```

`SetTx`'s [`Execute`](https://github.com/luxfi/blobvm/blob/master/chain/set_tx.go#L21) method performs a few safety checks to validate that the blob meets the size constraints enforced by genesis and doesn't overwrite an existing key before writing it to the blockchain.

```go
func (s *SetTx) Execute(t *TransactionContext) error {
	g := t.Genesis
	switch {
	case len(s.Value) == 0:
		return ErrValueEmpty
	case uint64(len(s.Value)) > g.MaxValueSize:
		return ErrValueTooBig
	}

	k := ValueHash(s.Value)

	// Do not allow duplicate value setting
	_, exists, err := GetValueMeta(t.Database, k)
	if err != nil {
		return err
	}
	if exists {
		return ErrKeyExists
	}

	return PutKey(t.Database, k, &ValueMeta{
		Size:    uint64(len(s.Value)),
		TxID:    t.TxID,
		Created: t.BlockTime,
	})
}
```

#### Signed Transaction

The unsigned transactions mentioned previously can't be issued to the network without first being signed. BlobVM implements signed transactions by embedding the unsigned transaction alongside its signature in [`Transaction`](https://github.com/luxfi/blobvm/blob/master/chain/tx.go). In BlobVM, a signature is defined as the [ECDSA signature](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) of the issuer's private key of the [KECCAK256](https://keccak.team/keccak.html) hash of the unsigned transaction's data ([digest hash](https://eips.ethereum.org/EIPS/eip-712)).

```go
type Transaction struct {
	UnsignedTransaction `serialize:"true" json:"unsignedTransaction"`
	Signature           []byte `serialize:"true" json:"signature"`

	digestHash []byte
	bytes      []byte
	id         ids.ID
	size       uint64
	sender     common.Address
}
```

The `Transaction` type wraps any unsigned transaction. When a `Transaction` is executed, it calls the `Execute` method of the underlying embedded `UnsignedTx` and performs the following sanity checks:

1.  The underlying `UnsignedTx` must meet the requirements set by genesis. This includes checks to make sure that the transaction contains the correct magic number and meets the minimum gas price as defined by genesis
2.  The transaction's block ID must be a recently accepted block
3.  The transaction must not be a recently issued transaction
4.  The issuer of the transaction must have enough gas
5.  The transaction's gas price must be meet the next expected block's minimum gas price
6.  The transaction must execute without error

If the transaction is successfully verified, it's submitted as a pending write to the blockchain.

```go
func (t *Transaction) Execute(g *Genesis, db database.Database, blk *StatelessBlock, context *Context) error {
	if err := t.UnsignedTransaction.ExecuteBase(g); err != nil {
		return err
	}
	if !context.RecentBlockIDs.Contains(t.GetBlockID()) {
		// Hash must be recent to be any good
		// Should not happen because of mempool cleanup
		return ErrInvalidBlockID
	}
	if context.RecentTxIDs.Contains(t.ID()) {
		// Tx hash must not be recently executed (otherwise could be replayed)
		//
		// NOTE: We only need to keep cached tx hashes around as long as the
		// block hash referenced in the tx is valid
		return ErrDuplicateTx
	}

	// Ensure sender has balance
	if _, err := ModifyBalance(db, t.sender, false, t.FeeUnits(g)*t.GetPrice()); err != nil {
		return err
	}
	if t.GetPrice() < context.NextPrice {
		return ErrInsufficientPrice
	}
	if err := t.UnsignedTransaction.Execute(&TransactionContext{
		Genesis:   g,
		Database:  db,
		BlockTime: uint64(blk.Tmstmp),
		TxID:      t.id,
		Sender:    t.sender,
	}); err != nil {
		return err
	}
	if err := SetTransaction(db, t); err != nil {
		return err
	}
	return nil
}
```

##### Example

Let's walk through an example on how to issue a `SetTx` transaction to the BlobVM to write a key-value pair.

1. Create the unsigned transaction for `SetTx`

	```go
	utx := &chain.SetTx{
		BaseTx: &chain.BaseTx{},
		Value:  []byte("data"),
	}

	utx.SetBlockID(lastAcceptedID)
	utx.SetMagic(genesis.Magic)
	utx.SetPrice(price + blockCost/utx.FeeUnits(genesis))
	```

2. Calculate the [digest hash](https://github.com/luxfi/blobvm/blob/master/chain/tx.go#L41) for the transaction.

	```go
	digest, err := chain.DigestHash(utx)
	```

3. [Sign](https://github.com/luxfi/blobvm/blob/master/chain/crypto.go#L17) the digest hash with the issuer's private key.

	```go
	signature, err := chain.Sign(digest, privateKey)
	```

4. Create and initialize the new signed transaction.

	```go
	tx := chain.NewTx(utx, sig)
	if err := tx.Init(g); err != nil {
		return ids.Empty, 0, err
	}
	```

5. Issue the request with the client

	```
	txID, err = cli.IssueRawTx(ctx, tx.Bytes())
	```

### Mempool

#### Overview

The [mempool](https://github.com/luxfi/blobvm/blob/master/mempool/mempool.go) is a buffer of volatile memory that stores pending transactions. Transactions are stored in the mempool whenever a node learns about a new transaction either through gossip with other nodes or through an API call issued by a user.

The mempool is implemented as a min-max [heap](https://en.wikipedia.org/wiki/Heap_data_structure) ordered by each transaction's gas price. The mempool is created during the [initialization](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L93) of VM.

```go
vm.mempool = mempool.New(vm.genesis, vm.config.MempoolSize)
```

Whenever a transaction is submitted to VM, it first gets initialized, verified, and executed locally. If the transaction looks valid, then it's added to the [mempool](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L414).

#### Add Method

When a transaction is added to the mempool, [`Add`](https://github.com/luxfi/blobvm/blob/master/mempool/mempool.go#L43) is called. This performs the following:

- Checks if the transaction being added already exists in the mempool or not
- The transaction is added to the min-max heap
- If the mempool's heap size is larger than the maximum configured value, then the lowest paying transaction is evicted
- The transaction is added to the list of transactions that are able to be gossiped to other peers
- A notification is sent through the in the `mempool.Pending` channel to indicate that the consensus engine should build a new block

### Block Builder

#### Overview

The [`TimeBuilder`](https://github.com/luxfi/blobvm/blob/master/vm/block_builder.go) implementation for `BlockBuilder` acts as an intermediary notification service between the mempool and the consensus engine. It serves the following functions:

- Periodically gossips new transactions to other nodes in the network
- Periodically notifies the consensus engine that new transactions from the mempool are ready to be built into blocks

`TimeBuilder` and can exist in 3 states:

- `dontBuild` - There are no transactions in the mempool that are ready to be included in a block
- `building` - The consensus engine has been notified that it should build a block and there are currently transactions in the mempool that are eligible to be included into a block
- `mayBuild` - There are transactions in the mempool that are eligible to be included into a block, but the consensus engine has not been notified yet

#### Gossip Method

The [`Gossip`](https://github.com/luxfi/blobvm/blob/master/vm/block_builder.go#L183) method initiates the gossip of new transactions from the mempool at periodically as defined by `vm.config.GossipInterval`.

#### Build Method

The [`Build`](https://github.com/luxfi/blobvm/blob/master/vm/block_builder.go#L166) method consumes transactions from the mempool and signals the consensus engine when it's ready to build a block.

If the mempool signals the `TimeBuilder` that it has available transactions, `TimeBuilder` will signal consensus that the VM is ready to build a block by sending the consensus engine a `common.PendingTxs` message.

When the consensus engine receives the `common.PendingTxs` message it calls the VM's `BuildBlock` method. The VM will then build a block from eligible transactions in the mempool.

If there are still remaining transactions in the mempool after a block is built, then the `TimeBuilder` is put into the `mayBuild` state to indicate that there are still transactions that are eligible to be built into block, but the consensus engine isn't aware of it yet.

### Network

[Network](https://github.com/luxfi/blobvm/blob/master/vm/network.go) handles the workflow of gossiping transactions from a node's mempool to other nodes in the network.

#### GossipNewTxs Method

`GossipNewTxs` sends a list of transactions to other nodes in the network. `TimeBuilder` calls the network's `GossipNewTxs` function to gossip new transactions in the mempool.

```go
func (n *PushNetwork) GossipNewTxs(newTxs []*chain.Transaction) error {
	txs := []*chain.Transaction{}
	// Gossip at most the target units of a block at once
	for _, tx := range newTxs {
		if _, exists := n.gossipedTxs.Get(tx.ID()); exists {
			log.Debug("already gossiped, skipping", "txId", tx.ID())
			continue
		}
		n.gossipedTxs.Put(tx.ID(), nil)
		txs = append(txs, tx)
	}

	return n.sendTxs(txs)
}
```

Recently gossiped transactions are maintained in a cache to avoid DDoSing a node from repeated gossip failures.

Other nodes in the network will receive the gossiped transactions through their `AppGossip` handler. Once a gossip message is received, it's deserialized and the new transactions are submitted to the VM.

```go
func (vm *VM) AppGossip(nodeID ids.NodeID, msg []byte) error {
	txs := make([]*chain.Transaction, 0)
	if _, err := chain.Unmarshal(msg, &txs); err != nil {
		return nil
	}

	// submit incoming gossip
	log.Debug("AppGossip transactions are being submitted", "txs", len(txs))
	if errs := vm.Submit(txs...); len(errs) > 0 {
		for _, err := range errs {

		}
	}

	return nil
}
```

### Block

Blocks go through a lifecycle of being proposed by a validator, verified, and decided by consensus. Upon acceptance, a block will be committed and will be finalized on the blockchain.

BlobVM implements two types of blocks, `StatefulBlock` and `StatelessBlock`.

#### StatefulBlock

A [`StatefulBlock`](https://github.com/luxfi/blobvm/blob/master/chain/block.go#L27) contains strictly the metadata about the block that needs to be written to the database.

```go
type StatefulBlock struct {
	Prnt        ids.ID         `serialize:"true" json:"parent"`
	Tmstmp      int64          `serialize:"true" json:"timestamp"`
	Hght        uint64         `serialize:"true" json:"height"`
	Price       uint64         `serialize:"true" json:"price"`
	Cost        uint64         `serialize:"true" json:"cost"`
	AccessProof common.Hash    `serialize:"true" json:"accessProof"`
	Txs         []*Transaction `serialize:"true" json:"txs"`
}
```

#### StatelessBlock

[StatelessBlock](https://github.com/luxfi/blobvm/blob/master/chain/block.go#L40) is a superset of `StatefulBlock` and additionally contains fields that are needed to support block-level operations like verification and acceptance throughout its lifecycle in the VM.

```go
type StatelessBlock struct {
	*StatefulBlock   `serialize:"true" json:"block"`
	id                ids.ID
	st                choices.Status
	t                 time.Time
	bytes             []byte
	vm                VM
	children          []*StatelessBlock
	onAcceptDB        *versiondb.Database
}
```

Let's have a look at the fields of StatelessBlock:

- `StatefulBlock`: The metadata about the block that will be written to the database upon acceptance
- `bytes`: The serialized form of the `StatefulBlock`.
- `id`: The Keccak256 hash of `bytes`.
- `st`: The status of the block in consensus (i.e `Processing`, `Accepted`, or `Rejected`)
- `children`: The children of this block
- `onAcceptDB`: The database this block should be written to upon acceptance.

When the consensus engine tries to build a block by calling the VM's `BuildBlock`, the VM calls the [`block.NewBlock`](https://github.com/luxfi/blobvm/blob/master/chain/block.go#L53) function to get a new block that is a child of the currently preferred block.

```go
func NewBlock(vm VM, parent block.Block, tmstp int64, context *Context) *StatelessBlock {
    return &StatelessBlock{
        StatefulBlock: &StatefulBlock{
            Tmstmp: tmstp,
            Prnt:   parent.ID(),
            Hght:   parent.Height() + 1,
            Price:  context.NextPrice,
            Cost:   context.NextCost,
        },
        vm: vm,
        st: choices.Processing,
    }
}
```

Some `StatelessBlock` fields like the block ID, byte representation, and timestamp aren't populated immediately. These are set during the `StatelessBlock`'s [`init`](https://github.com/luxfi/blobvm/blob/master/chain/block.go#L113) method, which initializes these fields once the block has been populated with transactions.

```go
func (b *StatelessBlock) init() error {
	bytes, err := Marshal(b.StatefulBlock)
	if err != nil {
		return err
	}
	b.bytes = bytes

	id, err := ids.ToID(crypto.Keccak256(b.bytes))
	if err != nil {
		return err
	}
	b.id = id
	b.t = time.Unix(b.StatefulBlock.Tmstmp, 0)
	g := b.vm.Genesis()
	for _, tx := range b.StatefulBlock.Txs {
		if err := tx.Init(g); err != nil {
			return err
		}
	}
	return nil
}
```

To build the block, the VM will try to remove as many of the highest-paying transactions from the mempool to include them in the new block until the maximum block fee set by genesis is reached.

A block once built, can exist in two states:

1. Rejected: The block was not accepted by consensus. In this case, the mempool will reclaim the rejected block's transactions so they can be included in a future block.
2. Accepted: The block was accepted by consensus. In this case, we write the block to the blockchain by committing it to the database.

When the consensus engine receives the built block, it calls the block's [`Verify`](https://github.com/luxfi/blobvm/blob/master/chain/block.go#L228) method to validate that the block is well-formed. In BlobVM, the following constraints are placed on valid blocks:

1. A block must contain at least one transaction and the block's timestamp must be within 10s into the future.

	```go
	if len(b.Txs) == 0 {
	return nil, nil, ErrNoTxs
	}
	if b.Timestamp().Unix() >= time.Now().Add(futureBound).Unix() {
	return nil, nil, ErrTimestampTooLate
	}
	```

2. The sum of the gas units consumed by the transactions in the block must not exceed the gas limit defined by genesis.

	```go
	blockSize := uint64(0)
	for _, tx := range b.Txs {
	blockSize += tx.LoadUnits(g)
	if blockSize > g.MaxBlockSize {
		return nil, nil, ErrBlockTooBig
	}
	}
	```

3. The parent block of the proposed block must exist and have an earlier timestamp.

	```go
	parent, err := b.vm.GetStatelessBlock(b.Prnt)
	if err != nil {
	log.Debug("could not get parent", "id", b.Prnt)
	return nil, nil, err
	}
	if b.Timestamp().Unix() < parent.Timestamp().Unix() {
	return nil, nil, ErrTimestampTooEarly
	}
	```

4. The target block price and minimum gas price must meet the minimum enforced by the VM.

	```go
	context, err := b.vm.ExecutionContext(b.Tmstmp, parent)
	if err != nil {
	return nil, nil, err
	}
	if b.Cost != context.NextCost {
	return nil, nil, ErrInvalidCost
	}
	if b.Price != context.NextPrice {
	return nil, nil, ErrInvalidPrice
	}
	```

After the results of consensus are complete, the block is either accepted by committing the block to the database or rejected by returning the block's transactions into the mempool.

```go
// implements "block.Block.choices.Decidable"
func (b *StatelessBlock) Accept() error {
	if err := b.onAcceptDB.Commit(); err != nil {
		return err
	}
	for _, child := range b.children {
		if err := child.onAcceptDB.SetDatabase(b.vm.State()); err != nil {
			return err
		}
	}
	b.st = choices.Accepted
	b.vm.Accepted(b)
	return nil
}

// implements "block.Block.choices.Decidable"
func (b *StatelessBlock) Reject() error {
	b.st = choices.Rejected
	b.vm.Rejected(b)
	return nil
}
```

### API

[Service](https://github.com/luxfi/blobvm/blob/master/vm/public_service.go) implements an API server so users can interact with the VM. The VM implements the interface method [`CreateHandlers`](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L267) that exposes the VM's RPC API.

```go
func (vm *VM) CreateHandlers() (map[string]*common.HTTPHandler, error) {
    apis := map[string]*common.HTTPHandler{}
    public, err := newHandler(Name, &PublicService{vm: vm})
    if err != nil {
        return nil, err
    }
    apis[PublicEndpoint] = public
    return apis, nil
}
```

One API that's exposed is [`IssueRawTx`](https://github.com/luxfi/blobvm/blob/master/vm/public_service.go#L63) to allow users to issue transactions to the BlobVM. It accepts an `IssueRawTxArgs` that contains the transaction the user wants to issue and forwards it to the VM.

```go
func (svc *PublicService) IssueRawTx(_ *http.Request, args *IssueRawTxArgs, reply *IssueRawTxReply) error {
	tx := new(chain.Transaction)
	if _, err := chain.Unmarshal(args.Tx, tx); err != nil {
		return err
	}

	// otherwise, unexported tx.id field is empty
	if err := tx.Init(svc.vm.genesis); err != nil {
		return err
	}
	reply.TxID = tx.ID()

	errs := svc.vm.Submit(tx)
	if len(errs) == 0 {
		return nil
	}
	if len(errs) == 1 {
		return errs[0]
	}
	return fmt.Errorf("%v", errs)
}
```

### Virtual Machine

We have learned about all the components used in the BlobVM. Most of these components are referenced in the `vm.go` file, which acts as the entry point for the consensus engine as well as users interacting with the blockchain.

For example, the engine calls `vm.BuildBlock()`, that in turn calls `chain.BuildBlock()`. Another example is when a user issues a raw transaction through service APIs, the `vm.Submit()` method is called.

Let's look at some of the important methods of `vm.go` that must be implemented:

#### Initialize Method

[Initialize](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L93) is invoked by `luxgo` when creating the blockchain. `luxgo` passes some parameters to the implementing VM.

- `ctx` - Metadata about the VM's execution
- `dbManager` - The database that the VM can write to
- `genesisBytes` - The serialized representation of the genesis state of this VM
- `upgradeBytes` - The serialized representation of network upgrades
- `configBytes` - The serialized VM-specific [configuration](https://github.com/luxfi/blobvm/blob/master/vm/config.go#L10)
- `toEngine` - The channel used to send messages to the consensus engine
- `fxs` - Feature extensions that attach to this VM
- `appSender` - Used to send messages to other nodes in the network

BlobVM upon initialization persists these fields in its own state to use them throughout the lifetime of its execution.

```go
// implements "block.ChainVM.common.VM"
func (vm *VM) Initialize(
	ctx *snow.Context,
	dbManager manager.Manager,
	genesisBytes []byte,
	upgradeBytes []byte,
	configBytes []byte,
	toEngine chan<- common.Message,
	_ []*common.Fx,
	appSender common.AppSender,
) error {
	log.Info("initializing blobvm", "version", version.Version)

	// Load config
	vm.config.SetDefaults()
	if len(configBytes) > 0 {
		if err := ejson.Unmarshal(configBytes, &vm.config); err != nil {
			return fmt.Errorf("failed to unmarshal config %s: %w", string(configBytes), err)
		}
	}

	vm.ctx = ctx
	vm.db = dbManager.Current().Database
	vm.activityCache = make([]*chain.Activity, vm.config.ActivityCacheSize)

	// Init channels before initializing other structs
	vm.stop = make(chan struct{})
	vm.builderStop = make(chan struct{})
	vm.doneBuild = make(chan struct{})
	vm.doneGossip = make(chan struct{})
	vm.appSender = appSender
	vm.network = vm.NewPushNetwork()

	vm.blocks = &cache.LRU{Size: blocksLRUSize}
	vm.verifiedBlocks = make(map[ids.ID]*chain.StatelessBlock)

	vm.toEngine = toEngine
	vm.builder = vm.NewTimeBuilder()

	// Try to load last accepted
	has, err := chain.HasLastAccepted(vm.db)
	if err != nil {
		log.Error("could not determine if have last accepted")
		return err
	}

	// Parse genesis data
	vm.genesis = new(chain.Genesis)
	if err := ejson.Unmarshal(genesisBytes, vm.genesis); err != nil {
		log.Error("could not unmarshal genesis bytes")
		return err
	}
	if err := vm.genesis.Verify(); err != nil {
		log.Error("genesis is invalid")
		return err
	}
	targetUnitsPerSecond := vm.genesis.TargetBlockSize / uint64(vm.genesis.TargetBlockRate)
	vm.targetRangeUnits = targetUnitsPerSecond * uint64(vm.genesis.LookbackWindow)
	log.Debug("loaded genesis", "genesis", string(genesisBytes), "target range units", vm.targetRangeUnits)

	vm.mempool = mempool.New(vm.genesis, vm.config.MempoolSize)

	if has { //nolint:nestif
		blkID, err := chain.GetLastAccepted(vm.db)
		if err != nil {
			log.Error("could not get last accepted", "err", err)
			return err
		}

		blk, err := vm.GetStatelessBlock(blkID)
		if err != nil {
			log.Error("could not load last accepted", "err", err)
			return err
		}

		vm.preferred, vm.lastAccepted = blkID, blk
		log.Info("initialized blobvm from last accepted", "block", blkID)
	} else {
		genesisBlk, err := chain.ParseStatefulBlock(
			vm.genesis.StatefulBlock(),
			nil,
			choices.Accepted,
			vm,
		)
		if err != nil {
			log.Error("unable to init genesis block", "err", err)
			return err
		}

		// Set Balances
		if err := vm.genesis.Load(vm.db, vm.AirdropData); err != nil {
			log.Error("could not set genesis allocation", "err", err)
			return err
		}

		if err := chain.SetLastAccepted(vm.db, genesisBlk); err != nil {
			log.Error("could not set genesis as last accepted", "err", err)
			return err
		}
		gBlkID := genesisBlk.ID()
		vm.preferred, vm.lastAccepted = gBlkID, genesisBlk
		log.Info("initialized blobvm from genesis", "block", gBlkID)
	}
	vm.AirdropData = nil
}
```

After initializing its own state, BlobVM also starts asynchronous workers to build blocks and gossip transactions to the rest of the network.

```
{
	go vm.builder.Build()
	go vm.builder.Gossip()
	return nil
}
```

#### GetBlock Method

[`GetBlock`](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L318) returns the block with the provided ID. GetBlock will attempt to fetch the given block from the database, and return an non-nil error if it wasn't able to get it.

```go
func (vm *VM) GetBlock(id ids.ID) (block.Block, error) {
	b, err := vm.GetStatelessBlock(id)
	if err != nil {
		log.Warn("failed to get block", "err", err)
	}
	return b, err
}
```

#### ParseBlock Method

[`ParseBlock`](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L373) deserializes a block.

```go
func (vm *VM) ParseBlock(source []byte) (block.Block, error) {
	newBlk, err := chain.ParseBlock(
		source,
		choices.Processing,
		vm,
	)
	if err != nil {
		log.Error("could not parse block", "err", err)
		return nil, err
	}
	log.Debug("parsed block", "id", newBlk.ID())

	// If we have seen this block before, return it with the most
	// up-to-date info
	if oldBlk, err := vm.GetBlock(newBlk.ID()); err == nil {
		log.Debug("returning previously parsed block", "id", oldBlk.ID())
		return oldBlk, nil
	}

	return newBlk, nil
}
```

#### BuildBlock Method

Lux consensus calls [`BuildBlock`](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L397) when it receives a notification from the VM that it has pending transactions that are ready to be issued into a block.

```go
func (vm *VM) BuildBlock() (block.Block, error) {
	log.Debug("BuildBlock triggered")
	blk, err := chain.BuildBlock(vm, vm.preferred)
	vm.builder.HandleGenerateBlock()
	if err != nil {
		log.Debug("BuildBlock failed", "error", err)
		return nil, err
	}
	sblk, ok := blk.(*chain.StatelessBlock)
	if !ok {
		return nil, fmt.Errorf("unexpected block.Block %T, expected *StatelessBlock", blk)
	}

	log.Debug("BuildBlock success", "blkID", blk.ID(), "txs", len(sblk.Txs))
	return blk, nil
}
```

#### SetPreference Method

[`SetPreference`](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L457) sets the block ID preferred by this node. A node votes to accept or reject a block based on its current preference in consensus.

```go
func (vm *VM) SetPreference(id ids.ID) error {
	log.Debug("set preference", "id", id)
	vm.preferred = id
	return nil
}
```

#### LastAccepted Method

[LastAccepted](https://github.com/luxfi/blobvm/blob/master/vm/vm.go#L465) returns the block ID of the block that was most recently accepted by this node.

```go
func (vm *VM) LastAccepted() (ids.ID, error) {
	return vm.lastAccepted.ID(), nil
}
```

### CLI

BlobVM implements a generic key-value store, but support to read and write arbitrary files into the BlobVM blockchain is implemented in the `blob-cli`

To write a file, BlobVM breaks apart an arbitrarily large file into many small chunks. Each chunk is submitted to the VM in a `SetTx`. A root key is generated which contains all of the hashes of the chunks.

```go
func Upload(
	ctx context.Context, cli client.Client, priv *ecdsa.PrivateKey,
	f io.Reader, chunkSize int,
) (common.Hash, error) {
	hashes := []common.Hash{}
	chunk := make([]byte, chunkSize)
	shouldExit := false
	opts := []client.OpOption{client.WithPollTx()}
	totalCost := uint64(0)
	uploaded := map[common.Hash]struct{}{}
	for !shouldExit {
		read, err := f.Read(chunk)
		if errors.Is(err, io.EOF) || read == 0 {
			break
		}
		if err != nil {
			return common.Hash{}, fmt.Errorf("%w: read error", err)
		}
		if read < chunkSize {
			shouldExit = true
			chunk = chunk[:read]

			// Use small file optimization
			if len(hashes) == 0 {
				break
			}
		}
		k := chain.ValueHash(chunk)
		if _, ok := uploaded[k]; ok {
			color.Yellow("already uploaded k=%s, skipping", k)
		} else if exists, _, _, err := cli.Resolve(ctx, k); err == nil && exists {
			color.Yellow("already on-chain k=%s, skipping", k)
			uploaded[k] = struct{}{}
		} else {
			tx := &chain.SetTx{
				BaseTx: &chain.BaseTx{},
				Value:  chunk,
			}
			txID, cost, err := client.SignIssueRawTx(ctx, cli, tx, priv, opts...)
			if err != nil {
				return common.Hash{}, err
			}
			totalCost += cost
			color.Yellow("uploaded k=%s txID=%s cost=%d totalCost=%d", k, txID, cost, totalCost)
			uploaded[k] = struct{}{}
		}
		hashes = append(hashes, k)
	}

	r := &Root{}
	if len(hashes) == 0 {
		if len(chunk) == 0 {
			return common.Hash{}, ErrEmpty
		}
		r.Contents = chunk
	} else {
		r.Children = hashes
	}

	rb, err := json.Marshal(r)
	if err != nil {
		return common.Hash{}, err
	}
	rk := chain.ValueHash(rb)
	tx := &chain.SetTx{
		BaseTx: &chain.BaseTx{},
		Value:  rb,
	}
	txID, cost, err := client.SignIssueRawTx(ctx, cli, tx, priv, opts...)
	if err != nil {
		return common.Hash{}, err
	}
	totalCost += cost
	color.Yellow("uploaded root=%v txID=%s cost=%d totalCost=%d", rk, txID, cost, totalCost)
	return rk, nil
}
```

#### Example 1

```bash
blob-cli set-file ~/Downloads/computer.gif -> 6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8
```

Given the root hash, a file can be looked up by deserializing all of its children chunk values and reconstructing the original file.

```go
// TODO: make multi-threaded
func Download(ctx context.Context, cli client.Client, root common.Hash, f io.Writer) error {
	exists, rb, _, err := cli.Resolve(ctx, root)
	if err != nil {
		return err
	}
	if !exists {
		return fmt.Errorf("%w:%v", ErrMissing, root)
	}
	var r Root
	if err := json.Unmarshal(rb, &r); err != nil {
		return err
	}

	// Use small file optimization
	if contentLen := len(r.Contents); contentLen > 0 {
		if _, err := f.Write(r.Contents); err != nil {
			return err
		}
		color.Yellow("downloaded root=%v size=%fKB", root, float64(contentLen)/units.KiB)
		return nil
	}

	if len(r.Children) == 0 {
		return ErrEmpty
	}

	amountDownloaded := 0
	for _, h := range r.Children {
		exists, b, _, err := cli.Resolve(ctx, h)
		if err != nil {
			return err
		}
		if !exists {
			return fmt.Errorf("%w:%s", ErrMissing, h)
		}
		if _, err := f.Write(b); err != nil {
			return err
		}
		size := len(b)
		color.Yellow("downloaded chunk=%v size=%fKB", h, float64(size)/units.KiB)
		amountDownloaded += size
	}
	color.Yellow("download complete root=%v size=%fMB", root, float64(amountDownloaded)/units.MiB)
	return nil
}
```

#### Example 2

```bash
blob-cli resolve-file 6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8 computer_copy.gif
```

## Conclusion

This documentation covers concepts about Virtual Machine by walking through a VM that implements a decentralized key-value store.

You can learn more about the BlobVM by referencing the [README](https://github.com/luxfi/blobvm/blob/master/README.md) in the GitHub repository.

# Simple Golang VM (/docs/lux-l1s/golang-vms/simple-golang-vm)

---
title: Simple Golang VM
description: In this tutorial, we will learn how to build a virtual machine by referencing the TimestampVM.
---

In this tutorial, we'll create a very simple VM called the [TimestampVM](https://github.com/luxfi/timestampvm/tree/v1.2.1). Each block in the TimestampVM's blockchain contains a strictly increasing timestamp when the block was created and a 32-byte payload of data.

Such a server is useful because it can be used to prove a piece of data existed at the time the block was created. Suppose you have a book manuscript, and you want to be able to prove in the future that the manuscript exists today. You can add a block to the blockchain where the block's payload is a hash of your manuscript. In the future, you can prove that the manuscript existed today by showing that the block has the hash of your manuscript in its payload (this follows from the fact that finding the pre-image of a hash is impossible).

## TimestampVM Implementation

Now we know the interface our VM must implement and the libraries we can use to build a VM.

Let's write our VM, which implements `block.ChainVM` and whose blocks implement `block.Block`. You can also follow the code in the [TimestampVM repository](https://github.com/luxfi/timestampvm/tree/main).

### Codec

`Codec` is required to encode/decode the block into byte representation. TimestampVM uses the default codec and manager.

```go title="timestampvm/codec.go"
const (
	// CodecVersion is the current default codec version
	CodecVersion = 0
)

// Codecs do serialization and deserialization
var (
	Codec codec.Manager
)

func init() {
	// Create default codec and manager
	c := linearcodec.NewDefault()
	Codec = codec.NewDefaultManager()

	// Register codec to manager with CodecVersion
	if err := Codec.RegisterCodec(CodecVersion, c); err != nil {
		panic(err)
	}
}
```

### State

The `State` interface defines the database layer and connections. Each VM should define their own database methods. `State` embeds the `BlockState` which defines block-related state operations.

```go title="timestampvm/state.go"
var (
	// These are prefixes for db keys.
	// It's important to set different prefixes for each separate database objects.
	singletonStatePrefix = []byte("singleton")
	blockStatePrefix     = []byte("block")

	_ State = &state{}
)

// State is a wrapper around lux.SingleTonState and BlockState
// State also exposes a few methods needed for managing database commits and close.
type State interface {
	// SingletonState is defined in luxgo,
	// it is used to understand if db is initialized already.
	lux.SingletonState
	BlockState

	Commit() error
	Close() error
}

type state struct {
	lux.SingletonState
	BlockState

	baseDB *versiondb.Database
}

func NewState(db database.Database, vm *VM) State {
	// create a new baseDB
	baseDB := versiondb.New(db)

	// create a prefixed "blockDB" from baseDB
	blockDB := prefixdb.New(blockStatePrefix, baseDB)
	// create a prefixed "singletonDB" from baseDB
	singletonDB := prefixdb.New(singletonStatePrefix, baseDB)

	// return state with created sub state components
	return &state{
		BlockState:     NewBlockState(blockDB, vm),
		SingletonState: lux.NewSingletonState(singletonDB),
		baseDB:         baseDB,
	}
}

// Commit commits pending operations to baseDB
func (s *state) Commit() error {
	return s.baseDB.Commit()
}

// Close closes the underlying base database
func (s *state) Close() error {
	return s.baseDB.Close()
}
```

#### Block State

This interface and implementation provides storage functions to VM to store and retrieve blocks.

```go title="timestampvm/block_state.go"
const (
	lastAcceptedByte byte = iota
)

const (
	// maximum block capacity of the cache
	blockCacheSize = 8192
)

// persists lastAccepted block IDs with this key
var lastAcceptedKey = []byte{lastAcceptedByte}

var _ BlockState = &blockState{}

// BlockState defines methods to manage state with Blocks and LastAcceptedIDs.
type BlockState interface {
	GetBlock(blkID ids.ID) (*Block, error)
	PutBlock(blk *Block) error

	GetLastAccepted() (ids.ID, error)
	SetLastAccepted(ids.ID) error
}

// blockState implements BlocksState interface with database and cache.
type blockState struct {
	// cache to store blocks
	blkCache cache.Cacher
	// block database
	blockDB      database.Database
	lastAccepted ids.ID

	// vm reference
	vm *VM
}

// blkWrapper wraps the actual blk bytes and status to persist them together
type blkWrapper struct {
	Blk    []byte         `serialize:"true"`
	Status choices.Status `serialize:"true"`
}

// NewBlockState returns BlockState with a new cache and given db
func NewBlockState(db database.Database, vm *VM) BlockState {
	return &blockState{
		blkCache: &cache.LRU{Size: blockCacheSize},
		blockDB:  db,
		vm:       vm,
	}
}

// GetBlock gets Block from either cache or database
func (s *blockState) GetBlock(blkID ids.ID) (*Block, error) {
	// Check if cache has this blkID
	if blkIntf, cached := s.blkCache.Get(blkID); cached {
		// there is a key but value is nil, so return an error
		if blkIntf == nil {
			return nil, database.ErrNotFound
		}
		// We found it return the block in cache
		return blkIntf.(*Block), nil
	}

	// get block bytes from db with the blkID key
	wrappedBytes, err := s.blockDB.Get(blkID[:])
	if err != nil {
		// we could not find it in the db, let's cache this blkID with nil value
		// so next time we try to fetch the same key we can return error
		// without hitting the database
		if err == database.ErrNotFound {
			s.blkCache.Put(blkID, nil)
		}
		// could not find the block, return error
		return nil, err
	}

	// first decode/unmarshal the block wrapper so we can have status and block bytes
	blkw := blkWrapper{}
	if _, err := Codec.Unmarshal(wrappedBytes, &blkw); err != nil {
		return nil, err
	}

	// now decode/unmarshal the actual block bytes to block
	blk := &Block{}
	if _, err := Codec.Unmarshal(blkw.Blk, blk); err != nil {
		return nil, err
	}

	// initialize block with block bytes, status and vm
	blk.Initialize(blkw.Blk, blkw.Status, s.vm)

	// put block into cache
	s.blkCache.Put(blkID, blk)

	return blk, nil
}

// PutBlock puts block into both database and cache
func (s *blockState) PutBlock(blk *Block) error {
	// create block wrapper with block bytes and status
	blkw := blkWrapper{
		Blk:    blk.Bytes(),
		Status: blk.Status(),
	}

	// encode block wrapper to its byte representation
	wrappedBytes, err := Codec.Marshal(CodecVersion, &blkw)
	if err != nil {
		return err
	}

	blkID := blk.ID()
	// put actual block to cache, so we can directly fetch it from cache
	s.blkCache.Put(blkID, blk)

	// put wrapped block bytes into database
	return s.blockDB.Put(blkID[:], wrappedBytes)
}

// DeleteBlock deletes block from both cache and database
func (s *blockState) DeleteBlock(blkID ids.ID) error {
	s.blkCache.Put(blkID, nil)
	return s.blockDB.Delete(blkID[:])
}

// GetLastAccepted returns last accepted block ID
func (s *blockState) GetLastAccepted() (ids.ID, error) {
	// check if we already have lastAccepted ID in state memory
	if s.lastAccepted != ids.Empty {
		return s.lastAccepted, nil
	}

	// get lastAccepted bytes from database with the fixed lastAcceptedKey
	lastAcceptedBytes, err := s.blockDB.Get(lastAcceptedKey)
	if err != nil {
		return ids.ID{}, err
	}
	// parse bytes to ID
	lastAccepted, err := ids.ToID(lastAcceptedBytes)
	if err != nil {
		return ids.ID{}, err
	}
	// put lastAccepted ID into memory
	s.lastAccepted = lastAccepted
	return lastAccepted, nil
}

// SetLastAccepted persists lastAccepted ID into both cache and database
func (s *blockState) SetLastAccepted(lastAccepted ids.ID) error {
	// if the ID in memory and the given memory are same don't do anything
	if s.lastAccepted == lastAccepted {
		return nil
	}
	// put lastAccepted ID to memory
	s.lastAccepted = lastAccepted
	// persist lastAccepted ID to database with fixed lastAcceptedKey
	return s.blockDB.Put(lastAcceptedKey, lastAccepted[:])
}
```

### Block

Let's look at our block implementation. The type declaration is:

```go title="timestampvm/block.go"
// Block is a block on the chain.
// Each block contains:
// 1) ParentID
// 2) Height
// 3) Timestamp
// 4) A piece of data (a string)
type Block struct {
	PrntID ids.ID        `serialize:"true" json:"parentID"`  // parent's ID
	Hght   uint64        `serialize:"true" json:"height"`    // This block's height. The genesis block is at height 0.
	Tmstmp int64         `serialize:"true" json:"timestamp"` // Time this block was proposed at
	Dt     [dataLen]byte `serialize:"true" json:"data"`      // Arbitrary data

	id     ids.ID         // hold this block's ID
	bytes  []byte         // this block's encoded bytes
	status choices.Status // block's status
	vm     *VM            // the underlying VM reference, mostly used for state
}
```

The `serialize:"true"` tag indicates that the field should be included in the byte representation of the block used when persisting the block or sending it to other nodes.

#### Verify

This method verifies that a block is valid and stores it in the memory. It is important to store the verified block in the memory and return them in the `vm.GetBlock` method.

```go title="timestampvm/block.go"
// Verify returns nil iff this block is valid.
// To be valid, it must be that:
// b.parent.Timestamp < b.Timestamp <= [local time] + 1 hour
func (b *Block) Verify() error {
	// Get [b]'s parent
	parentID := b.Parent()
	parent, err := b.vm.getBlock(parentID)
	if err != nil {
		return errDatabaseGet
	}

	// Ensure [b]'s height comes right after its parent's height
	if expectedHeight := parent.Height() + 1; expectedHeight != b.Hght {
		return fmt.Errorf(
			"expected block to have height %d, but found %d",
			expectedHeight,
			b.Hght,
		)
	}

	// Ensure [b]'s timestamp is after its parent's timestamp.
	if b.Timestamp().Unix() < parent.Timestamp().Unix() {
		return errTimestampTooEarly
	}

	// Ensure [b]'s timestamp is not more than an hour
	// ahead of this node's time
	if b.Timestamp().Unix() >= time.Now().Add(time.Hour).Unix() {
		return errTimestampTooLate
	}

	// Put that block to verified blocks in memory
	b.vm.verifiedBlocks[b.ID()] = b

	return nil
}
```

#### Accept

`Accept` is called by the consensus to indicate this block is accepted.

```go title="timestampvm/block.go"
// Accept sets this block's status to Accepted and sets lastAccepted to this
// block's ID and saves this info to b.vm.DB
func (b *Block) Accept() error {
	b.SetStatus(choices.Accepted) // Change state of this block
	blkID := b.ID()

	// Persist data
	if err := b.vm.state.PutBlock(b); err != nil {
		return err
	}

	// Set last accepted ID to this block ID
	if err := b.vm.state.SetLastAccepted(blkID); err != nil {
		return err
	}

	// Delete this block from verified blocks as it's accepted
	delete(b.vm.verifiedBlocks, b.ID())

	// Commit changes to database
	return b.vm.state.Commit()
}
```

#### Reject

`Reject` is called by the consensus to indicate this block is rejected.

```go title="timestampvm/block.go"
// Reject sets this block's status to Rejected and saves the status in state
// Recall that b.vm.DB.Commit() must be called to persist to the DB
func (b *Block) Reject() error {
	b.SetStatus(choices.Rejected) // Change state of this block
	if err := b.vm.state.PutBlock(b); err != nil {
		return err
	}
	// Delete this block from verified blocks as it's rejected
	delete(b.vm.verifiedBlocks, b.ID())
	// Commit changes to database
	return b.vm.state.Commit()
}
```

#### Block Field Methods

These methods are required by the `block.Block` interface.

```go title="timestampvm/block.go"
// ID returns the ID of this block
func (b *Block) ID() ids.ID { return b.id }

// ParentID returns [b]'s parent's ID
func (b *Block) Parent() ids.ID { return b.PrntID }

// Height returns this block's height. The genesis block has height 0.
func (b *Block) Height() uint64 { return b.Hght }

// Timestamp returns this block's time. The genesis block has time 0.
func (b *Block) Timestamp() time.Time { return time.Unix(b.Tmstmp, 0) }

// Status returns the status of this block
func (b *Block) Status() choices.Status { return b.status }

// Bytes returns the byte repr. of this block
func (b *Block) Bytes() []byte { return b.bytes }
```

#### Helper Functions

These methods are convenience methods for blocks, they're not a part of the block interface.

```go
// Initialize sets [b.bytes] to [bytes], [b.id] to hash([b.bytes]),
// [b.status] to [status] and [b.vm] to [vm]
func (b *Block) Initialize(bytes []byte, status choices.Status, vm *VM) {
	b.bytes = bytes
	b.id = hashing.ComputeHash256Array(b.bytes)
	b.status = status
	b.vm = vm
}

// SetStatus sets the status of this block
func (b *Block) SetStatus(status choices.Status) { b.status = status }
```

### Virtual Machine

Now, let's look at our timestamp VM implementation, which implements the `block.ChainVM` interface. The declaration is:

```go title="timestampvm/vm.go"
// This Virtual Machine defines a blockchain that acts as a timestamp server
// Each block contains data (a payload) and the timestamp when it was created

const (
  dataLen = 32
	Name    = "timestampvm"
)

// VM implements the block.ChainVM interface
// Each block in this chain contains a Unix timestamp
// and a piece of data (a string)
type VM struct {
	// The context of this vm
	ctx       *snow.Context
	dbManager manager.Manager

	// State of this VM
	state State

	// ID of the preferred block
	preferred ids.ID

	// channel to send messages to the consensus engine
	toEngine chan<- common.Message

	// Proposed pieces of data that haven't been put into a block and proposed yet
	mempool [][dataLen]byte

	// Block ID --> Block
	// Each element is a block that passed verification but
	// hasn't yet been accepted/rejected
	verifiedBlocks map[ids.ID]*Block
}
```

#### Initialize

This method is called when a new instance of VM is initialized. Genesis block is created under this method.

```go title="timestampvm/vm.go"
// Initialize this vm
// [ctx] is this vm's context
// [dbManager] is the manager of this vm's database
// [toEngine] is used to notify the consensus engine that new blocks are
//   ready to be added to consensus
// The data in the genesis block is [genesisData]
func (vm *VM) Initialize(
	ctx *snow.Context,
	dbManager manager.Manager,
	genesisData []byte,
	upgradeData []byte,
	configData []byte,
	toEngine chan<- common.Message,
	_ []*common.Fx,
	_ common.AppSender,
) error {
	version, err := vm.Version()
	if err != nil {
		log.Error("error initializing Timestamp VM: %v", err)
		return err
	}
	log.Info("Initializing Timestamp VM", "Version", version)

	vm.dbManager = dbManager
	vm.ctx = ctx
	vm.toEngine = toEngine
	vm.verifiedBlocks = make(map[ids.ID]*Block)

	// Create new state
	vm.state = NewState(vm.dbManager.Current().Database, vm)

	// Initialize genesis
	if err := vm.initGenesis(genesisData); err != nil {
		return err
	}

	// Get last accepted
	lastAccepted, err := vm.state.GetLastAccepted()
	if err != nil {
		return err
	}

	ctx.Log.Info("initializing last accepted block as %s", lastAccepted)

	// Build off the most recently accepted block
	return vm.SetPreference(lastAccepted)
}
```

#### `initGenesis`

`initGenesis` is a helper method which initializes the genesis block from given bytes and puts into the state.

```go title="timestampvm/vm.go"
// Initializes Genesis if required
func (vm *VM) initGenesis(genesisData []byte) error {
	stateInitialized, err := vm.state.IsInitialized()
	if err != nil {
		return err
	}

	// if state is already initialized, skip init genesis.
	if stateInitialized {
		return nil
	}

	if len(genesisData) > dataLen {
		return errBadGenesisBytes
	}

	// genesisData is a byte slice but each block contains an byte array
	// Take the first [dataLen] bytes from genesisData and put them in an array
	var genesisDataArr [dataLen]byte
	copy(genesisDataArr[:], genesisData)

	// Create the genesis block
	// Timestamp of genesis block is 0. It has no parent.
	genesisBlock, err := vm.NewBlock(ids.Empty, 0, genesisDataArr, time.Unix(0, 0))
	if err != nil {
		log.Error("error while creating genesis block: %v", err)
		return err
	}

	// Put genesis block to state
	if err := vm.state.PutBlock(genesisBlock); err != nil {
		log.Error("error while saving genesis block: %v", err)
		return err
	}

	// Accept the genesis block
	// Sets [vm.lastAccepted] and [vm.preferred]
	if err := genesisBlock.Accept(); err != nil {
		return fmt.Errorf("error accepting genesis block: %w", err)
	}

	// Mark this vm's state as initialized, so we can skip initGenesis in further restarts
	if err := vm.state.SetInitialized(); err != nil {
		return fmt.Errorf("error while setting db to initialized: %w", err)
	}

	// Flush VM's database to underlying db
	return vm.state.Commit()
}
```

#### CreateHandlers

Registered handlers defined in `Service`. See [below](/docs/lux-l1s/golang-vms/simple-golang-vm#api) for more on APIs.

```go title="timestampvm/vm.go"
// CreateHandlers returns a map where:
// Keys: The path extension for this blockchain's API (empty in this case)
// Values: The handler for the API
// In this case, our blockchain has only one API, which we name timestamp,
// and it has no path extension, so the API endpoint:
// [Node IP]/ext/bc/[this blockchain's ID]
// See API section in documentation for more information
func (vm *VM) CreateHandlers() (map[string]*common.HTTPHandler, error) {
	server := rpc.NewServer()
	server.RegisterCodec(json.NewCodec(), "application/json")
	server.RegisterCodec(json.NewCodec(), "application/json;charset=UTF-8")
    // Name is "timestampvm"
	if err := server.RegisterService(&Service{vm: vm}, Name); err != nil {
		return nil, err
	}

	return map[string]*common.HTTPHandler{
		"": {
			Handler: server,
		},
	}, nil
}
```

#### CreateStaticHandlers

Registers static handlers defined in `StaticService`. See [below](/docs/lux-l1s/golang-vms/simple-golang-vm#static-api) for more on static APIs.

```go title="timestampvm/vm.go"
// CreateStaticHandlers returns a map where:
// Keys: The path extension for this VM's static API
// Values: The handler for that static API
func (vm *VM) CreateStaticHandlers() (map[string]*common.HTTPHandler, error) {
	server := rpc.NewServer()
	server.RegisterCodec(json.NewCodec(), "application/json")
	server.RegisterCodec(json.NewCodec(), "application/json;charset=UTF-8")
	if err := server.RegisterService(&StaticService{}, Name); err != nil {
		return nil, err
	}

	return map[string]*common.HTTPHandler{
		"": {
			LockOptions: common.NoLock,
			Handler:     server,
		},
	}, nil
}
```

#### BuildBock

`BuildBlock` builds a new block and returns it. This is mainly requested by the consensus engine.

```go title="timestampvm/vm.go"
// BuildBlock returns a block that this vm wants to add to consensus
func (vm *VM) BuildBlock() (block.Block, error) {
	if len(vm.mempool) == 0 { // There is no block to be built
		return nil, errNoPendingBlocks
	}

	// Get the value to put in the new block
	value := vm.mempool[0]
	vm.mempool = vm.mempool[1:]

	// Notify consensus engine that there are more pending data for blocks
	// (if that is the case) when done building this block
	if len(vm.mempool) > 0 {
		defer vm.NotifyBlockReady()
	}

	// Gets Preferred Block
	preferredBlock, err := vm.getBlock(vm.preferred)
	if err != nil {
		return nil, fmt.Errorf("couldn't get preferred block: %w", err)
	}
	preferredHeight := preferredBlock.Height()

	// Build the block with preferred height
	newBlock, err := vm.NewBlock(vm.preferred, preferredHeight+1, value, time.Now())
	if err != nil {
		return nil, fmt.Errorf("couldn't build block: %w", err)
	}

	// Verifies block
	if err := newBlock.Verify(); err != nil {
		return nil, err
	}
	return newBlock, nil
}
```

#### NotifyBlockReady

`NotifyBlockReady` is a helper method that can send messages to the consensus engine through `toEngine` channel.

```go title="timestampvm/vm.go"
// NotifyBlockReady tells the consensus engine that a new block
// is ready to be created
func (vm *VM) NotifyBlockReady() {
	select {
	case vm.toEngine <- common.PendingTxs:
	default:
		vm.ctx.Log.Debug("dropping message to consensus engine")
	}
}
```

#### GetBlock

`GetBlock` returns the block with the given block ID.

```go title="timestampvm/vm.go"
// GetBlock implements the block.ChainVM interface
func (vm *VM) GetBlock(blkID ids.ID) (block.Block, error) { return vm.getBlock(blkID) }

func (vm *VM) getBlock(blkID ids.ID) (*Block, error) {
	// If block is in memory, return it.
	if blk, exists := vm.verifiedBlocks[blkID]; exists {
		return blk, nil
	}

	return vm.state.GetBlock(blkID)
}
```

#### `proposeBlock`

This method adds a piece of data to the mempool and notifies the consensus layer of the blockchain that a new block is ready to be built and voted on. This is called by API method `ProposeBlock`, which we'll see later.

```go title="timestampvm/vm.go"
// proposeBlock appends [data] to [p.mempool].
// Then it notifies the consensus engine
// that a new block is ready to be added to consensus
// (namely, a block with data [data])
func (vm *VM) proposeBlock(data [dataLen]byte) {
    vm.mempool = append(vm.mempool, data)
    vm.NotifyBlockReady()
}
```

#### ParseBlock

Parse a block from its byte representation.

```go title="timestampvm/vm.go"
// ParseBlock parses [bytes] to a block.Block
// This function is used by the vm's state to unmarshal blocks saved in state
// and by the consensus layer when it receives the byte representation of a block
// from another node
func (vm *VM) ParseBlock(bytes []byte) (block.Block, error) {
	// A new empty block
	block := &Block{}

	// Unmarshal the byte repr. of the block into our empty block
	_, err := Codec.Unmarshal(bytes, block)
	if err != nil {
		return nil, err
	}

	// Initialize the block
	block.Initialize(bytes, choices.Processing, vm)

	if blk, err := vm.getBlock(block.ID()); err == nil {
		// If we have seen this block before, return it with the most up-to-date
		// info
		return blk, nil
	}

	// Return the block
	return block, nil
}
```

#### NewBlock

`NewBlock` creates a new block with given block parameters.

```go title="timestampvm/vm.go"
// NewBlock returns a new Block where:
// - the block's parent is [parentID]
// - the block's data is [data]
// - the block's timestamp is [timestamp]
func (vm *VM) NewBlock(parentID ids.ID, height uint64, data [dataLen]byte, timestamp time.Time) (*Block, error) {
	block := &Block{
		PrntID: parentID,
		Hght:   height,
		Tmstmp: timestamp.Unix(),
		Dt:     data,
	}

	// Get the byte representation of the block
	blockBytes, err := Codec.Marshal(CodecVersion, block)
	if err != nil {
		return nil, err
	}

	// Initialize the block by providing it with its byte representation
	// and a reference to this VM
	block.Initialize(blockBytes, choices.Processing, vm)
	return block, nil
}
```

#### SetPreference

`SetPreference` implements the `block.ChainVM`. It sets the preferred block ID.

```go title="timestampvm/vm.go"
// SetPreference sets the block with ID [ID] as the preferred block
func (vm *VM) SetPreference(id ids.ID) error {
	vm.preferred = id
	return nil
}
```

#### Other Functions

These functions needs to be implemented for `block.ChainVM`. Most of them are just blank functions returning `nil`.

```go title="timestampvm/vm.go"
// Bootstrapped marks this VM as bootstrapped
func (vm *VM) Bootstrapped() error { return nil }

// Bootstrapping marks this VM as bootstrapping
func (vm *VM) Bootstrapping() error { return nil }

// Returns this VM's version
func (vm *VM) Version() (string, error) {
	return Version.String(), nil
}

func (vm *VM) Connected(id ids.ShortID, nodeVersion version.Application) error {
	return nil // noop
}

func (vm *VM) Disconnected(id ids.ShortID) error {
	return nil // noop
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppGossip(nodeID ids.ShortID, msg []byte) error {
	return nil
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppRequest(nodeID ids.ShortID, requestID uint32, time time.Time, request []byte) error {
	return nil
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppResponse(nodeID ids.ShortID, requestID uint32, response []byte) error {
	return nil
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppRequestFailed(nodeID ids.ShortID, requestID uint32) error {
	return nil
}

// Health implements the common.VM interface
func (vm *VM) HealthCheck() (interface{}, error) { return nil, nil }
```

### Factory

VMs should implement the `Factory` interface. `New` method in the interface returns a new VM instance.

```go title="timestampvm/factory.go"
var _ vms.Factory = &Factory{}

// Factory ...
type Factory struct{}

// New ...
func (f *Factory) New(*snow.Context) (interface{}, error) { return &VM{}, nil }
```

### Static API

A VM may have a static API, which allows clients to call methods that do not query or update the state of a particular blockchain, but rather apply to the VM as a whole. This is analogous to static methods in computer programming. LuxGo uses [Gorilla's RPC library](https://www.gorillatoolkit.org/pkg/rpc) to implement HTTP APIs. `StaticService` implements the static API for our VM.

```go title="timestampvm/static_service.go"
// StaticService defines the static API for the timestamp vm
type StaticService struct{}
```

#### Encode

For each API method, there is:

- A struct that defines the method's arguments
- A struct that defines the method's return values
- A method that implements the API method, and is parameterized on the above 2 structs

This API method encodes a string to its byte representation using a given encoding scheme. It can be used to encode data that is then put in a block and proposed as the next block for this chain.

```go title="timestampvm/static_service.go"
// EncodeArgs are arguments for Encode
type EncodeArgs struct {
    Data     string              `json:"data"`
    Encoding formatting.Encoding `json:"encoding"`
    Length   int32               `json:"length"`
}

// EncodeReply is the reply from Encoder
type EncodeReply struct {
    Bytes    string              `json:"bytes"`
    Encoding formatting.Encoding `json:"encoding"`
}

// Encoder returns the encoded data
func (ss *StaticService) Encode(_ *http.Request, args *EncodeArgs, reply *EncodeReply) error {
    if len(args.Data) == 0 {
        return fmt.Errorf("argument Data cannot be empty")
    }
    var argBytes []byte
    if args.Length > 0 {
        argBytes = make([]byte, args.Length)
        copy(argBytes, args.Data)
    } else {
        argBytes = []byte(args.Data)
    }

    bytes, err := formatting.EncodeWithChecksum(args.Encoding, argBytes)
    if err != nil {
        return fmt.Errorf("couldn't encode data as string: %s", err)
    }
    reply.Bytes = bytes
    reply.Encoding = args.Encoding
    return nil
}
```

#### Decode

This API method is the inverse of `Encode`.

```go title="timestampvm/static_service.go"
// DecoderArgs are arguments for Decode
type DecoderArgs struct {
    Bytes    string              `json:"bytes"`
    Encoding formatting.Encoding `json:"encoding"`
}

// DecoderReply is the reply from Decoder
type DecoderReply struct {
    Data     string              `json:"data"`
    Encoding formatting.Encoding `json:"encoding"`
}

// Decoder returns the Decoded data
func (ss *StaticService) Decode(_ *http.Request, args *DecoderArgs, reply *DecoderReply) error {
    bytes, err := formatting.Decode(args.Encoding, args.Bytes)
    if err != nil {
        return fmt.Errorf("couldn't Decode data as string: %s", err)
    }
    reply.Data = string(bytes)
    reply.Encoding = args.Encoding
    return nil
}
```

### API

A VM may also have a non-static HTTP API, which allows clients to query and update the blockchain's state. `Service`'s declaration is:

```go title="timestampvm/service.go"
// Service is the API service for this VM
type Service struct{ vm *VM }
```

Note that this struct has a reference to the VM, so it can query and update state.

This VM's API has two methods. One allows a client to get a block by its ID. The other allows a client to propose the next block of this blockchain. The blockchain ID in the endpoint changes, since every blockchain has an unique ID.

#### `timestampvm.getBlock`

Get a block by its ID. If no ID is provided, get the latest block.

##### `getBlock` Signature

```
timestampvm.getBlock({id: string}) ->
    {
        id: string,
        data: string,
        timestamp: int,
        parentID: string
    }
```

- `id` is the ID of the block being retrieved. If omitted from arguments, gets the latest block
- `data` is the base 58 (with checksum) representation of the block's 32 byte payload
- `timestamp` is the Unix timestamp when this block was created
- `parentID` is the block's parent

##### `getBlock` Example Call

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "timestampvm.getBlock",
    "params":{
        "id":"xqQV1jDnCXDxhfnNT7tDBcXeoH2jC3Hh7Pyv4GXE1z1hfup5K"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/sw813hGSWH8pdU9uzaYy9fCtYFfY7AjDd2c9rm64SbApnvjmk
```

##### `getBlock` Example Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "timestamp": "1581717416",
    "data": "11111111111111111111111111111111LpoYY",
    "id": "xqQV1jDnCXDxhfnNT7tDBcXeoH2jC3Hh7Pyv4GXE1z1hfup5K",
    "parentID": "22XLgiM5dfCwTY9iZnVk8ZPuPe3aSrdVr5Dfrbxd3ejpJd7oef"
  },
  "id": 1
}
```

##### `getBlock` Implementation

```go title="timestampvm/service.go"
// GetBlockArgs are the arguments to GetBlock
type GetBlockArgs struct {
	// ID of the block we're getting.
	// If left blank, gets the latest block
	ID *ids.ID `json:"id"`
}

// GetBlockReply is the reply from GetBlock
type GetBlockReply struct {
	Timestamp json.Uint64 `json:"timestamp"` // Timestamp of most recent block
	Data      string      `json:"data"`      // Data in the most recent block. Base 58 repr. of 5 bytes.
	ID        ids.ID      `json:"id"`        // String repr. of ID of the most recent block
	ParentID  ids.ID      `json:"parentID"`  // String repr. of ID of the most recent block's parent
}

// GetBlock gets the block whose ID is [args.ID]
// If [args.ID] is empty, get the latest block
func (s *Service) GetBlock(_ *http.Request, args *GetBlockArgs, reply *GetBlockReply) error {
	// If an ID is given, parse its string representation to an ids.ID
	// If no ID is given, ID becomes the ID of last accepted block
	var (
		id  ids.ID
		err error
	)

	if args.ID == nil {
		id, err = s.vm.state.GetLastAccepted()
		if err != nil {
			return errCannotGetLastAccepted
		}
	} else {
		id = *args.ID
	}

	// Get the block from the database
	block, err := s.vm.getBlock(id)
	if err != nil {
		return errNoSuchBlock
	}

	// Fill out the response with the block's data
	reply.ID = block.ID()
	reply.Timestamp = json.Uint64(block.Timestamp().Unix())
	reply.ParentID = block.Parent()
	data := block.Data()
	reply.Data, err = formatting.EncodeWithChecksum(formatting.CB58, data[:])

	return err
}
```

#### `timestampvm.proposeBlock`

Propose the next block on this blockchain.

##### `proposeBlock` Signature

```go
timestampvm.proposeBlock({data: string}) -> {success: bool}
```

- `data` is the base 58 (with checksum) representation of the proposed block's 32 byte payload.

##### `proposeBlock` Example Call

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "timestampvm.proposeBlock",
    "params":{
        "data":"SkB92YpWm4Q2iPnLGCuDPZPgUQMxajqQQuz91oi3xD984f8r"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/sw813hGSWH8pdU9uzaYy9fCtYFfY7AjDd2c9rm64SbApnvjmk
```

###### `proposeBlock` Example Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "Success": true
  },
  "id": 1
}
```

##### `proposeBlock` Implementation

```go title="timestampvm/service.go"
// ProposeBlockArgs are the arguments to ProposeValue
type ProposeBlockArgs struct {
    // Data for the new block. Must be base 58 encoding (with checksum) of 32 bytes.
    Data string
}

// ProposeBlockReply is the reply from function ProposeBlock
type ProposeBlockReply struct{
    // True if the operation was successful
    Success bool
}

// ProposeBlock is an API method to propose a new block whose data is [args].Data.
// [args].Data must be a string repr. of a 32 byte array
func (s *Service) ProposeBlock(_ *http.Request, args *ProposeBlockArgs, reply *ProposeBlockReply) error {
	bytes, err := formatting.Decode(formatting.CB58, args.Data)
	if err != nil || len(bytes) != dataLen {
		return errBadData
	}

	var data [dataLen]byte         // The data as an array of bytes
	copy(data[:], bytes[:dataLen]) // Copy the bytes in dataSlice to data

	s.vm.proposeBlock(data)
	reply.Success = true
	return nil
}
```

### Plugin

In order to make this VM compatible with `go-plugin`, we need to define a `main` package and method, which serves our VM over gRPC so that LuxGo can call its methods. `main.go`'s contents are:

```go title="main/main.go"
func main() {
    log.Root().SetHandler(log.LvlFilterHandler(log.LvlDebug, log.StreamHandler(os.Stderr, log.TerminalFormat())))
    plugin.Serve(&plugin.ServeConfig{
        HandshakeConfig: rpcchainvm.Handshake,
        Plugins: map[string]plugin.Plugin{
            "vm": rpcchainvm.New(&timestampvm.VM{}),
        },

        // A non-nil value here enables gRPC serving for this plugin...
        GRPCServer: plugin.DefaultGRPCServer,
    })
}
```

Now LuxGo's `rpcchainvm` can connect to this plugin and calls its methods.

### Executable Binary

This VM has a [build script](https://github.com/luxfi/timestampvm/blob/v1.2.1/scripts/build.sh) that builds an executable of this VM (when invoked, it runs the `main` method from above.)

The path to the executable, as well as its name, can be provided to the build script via arguments. For example:

```bash
./scripts/build.sh ../luxgo/build/plugins timestampvm
```

If no argument is given, the path defaults to a binary named with default VM ID: `$GOPATH/src/github.com/luxfi/luxgo/build/plugins/tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH`

This name `tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH` is the CB58 encoded 32 byte identifier for the VM. For the timestampvm, this is the string "timestamp" zero-extended in a 32 byte array and encoded in CB58.

### VM Aliases

Each VM has a predefined, static ID. For instance, the default ID of the TimestampVM is: `tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH`.

It's possible to give an alias for these IDs. For example, we can alias `TimestampVM` by creating a JSON file at `~/.luxgo/configs/vms/aliases.json` with:

<Callout type="warn">
The name of the VM binary is also its static ID and should not be changed manually. Changing the name of the VM binary will result in LuxGo failing to start the VM. To reference a VM by another name, define a VM alias as described below.
</Callout>

```json
{
  "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": [
    "timestampvm",
    "timestamp"
  ]
}
```

### Installing a VM

LuxGo searches for and registers plugins under the `plugins` [directory](/docs/nodes/configure/configs-flags#--plugin-dir-string).

To install the virtual machine onto your node, you need to move the built virtual machine binary under this directory. Virtual machine executable names must be either a full virtual machine ID (encoded in CB58), or a VM alias.

Copy the binary into the plugins directory.

```bash
cp -n <path to your binary> $GOPATH/src/github.com/luxfi/luxgo/build/plugins/
```

#### Node Is Not Running

If your node isn't running yet, you can install all virtual machines under your `plugin` directory by starting the node.

#### Node Is Already Running

Load the binary with the `loadVMs` API.

```bash
curl -sX POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.loadVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

Confirm the response of `loadVMs` contains the newly installed virtual machine `tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH`. You'll see this virtual machine as well as any others that weren't already installed previously in the response.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "newVMs": {
      "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": [
        "timestampvm",
        "timestamp"
      ],
      "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ": []
    }
  },
  "id": 1
}
```

Now, this VM's static API can be accessed at endpoints `/ext/vm/timestampvm` and `/ext/vm/timestamp`. For more details about VM configs, see [here](/docs/nodes/configure/configs-flags#virtual-machine-vm-configs).

In this tutorial, we used the VM's ID as the executable name to simplify the process. However, LuxGo would also accept `timestampvm` or `timestamp` since those are registered aliases in previous step.

## Wrapping Up

That's it! That's the entire implementation of a VM which defines a blockchain-based timestamp server.

In this tutorial, we learned:

- The `block.ChainVM` interface, which all VMs that define a linear chain must implement
- The `block.Block` interface, which all blocks that are part of a linear chain must implement
- The `rpcchainvm` type, which allows blockchains to run in their own processes.
- An actual implementation of `block.ChainVM` and `block.Block`.

# AllowList Interface (/docs/lux-l1s/precompiles/allowlist-interface)

---
title: AllowList Interface
description: The AllowList interface is used by many default precompiles to permission access to the features they provide.
---

## Overview

The AllowList is a security feature used by precompiles to manage which addresses have permission to interact with certain contract functionalities. It provides a consistent role-based permission system inherited by all precompiles that use it.

| Property | Value |
|----------|-------|
| **Address** | Inherited by each precompile |
| **ConfigKey** | N/A (Interface only) |

## Role-Based Permissions

The AllowList implements a consistent role-based permission system:

| Role | Value | Description | Permissions |
|------|-------|-------------|-------------|
| Admin | 2 | Can manage all roles | Can add/remove any role (Admin, Manager, Enabled) |
| Manager | 3 | Can manage enabled addresses | Can add/remove only Enabled addresses |
| Enabled | 1 | Basic permissions | Can use the precompile's functionality |
| None | 0 | No permissions | Cannot use the precompile or manage permissions |

Each precompile that uses the AllowList interface follows this permission structure, though the specific actions allowed for "Enabled" addresses vary depending on the precompile's purpose. For example:
- In the Contract Deployer AllowList, "Enabled" addresses can deploy contracts
- In the Transaction AllowList, "Enabled" addresses can submit transactions
- In the Native Minter, "Enabled" addresses can mint tokens

## Interface

The AllowList interface is defined as follows:

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

interface IAllowList {
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

## Implementation

The AllowList interface is implemented by multiple precompiles in the Subnet-EVM. You can find the core implementation in the [subnet-evm repository](https://github.com/luxfi/subnet-evm/blob/master/precompile/allowlist/allowlist.go).

## Precompiles Using AllowList

Several precompiles in Subnet-EVM use the AllowList interface:

- [Deployer AllowList](/docs/lux-l1s/precompiles/deployer-allowlist)
- [Transaction AllowList](/docs/lux-l1s/precompiles/transaction-allowlist)
- [Native Minter](/docs/lux-l1s/precompiles/native-minter)
- [Fee Manager](/docs/lux-l1s/precompiles/fee-manager)
- [Reward Manager](/docs/lux-l1s/precompiles/reward-manager)



# Deployer AllowList (/docs/lux-l1s/precompiles/deployer-allowlist)

---
title: Deployer AllowList
description: Control which addresses can deploy smart contracts on your Lux L1 blockchain.
---

## Overview

The Contract Deployer Allowlist allows you to maintain a controlled environment where only authorized addresses can deploy new smart contracts. This is particularly useful for:

- Maintaining a curated ecosystem of verified contracts
- Preventing malicious contract deployments
- Implementing KYC/AML requirements for contract deployers

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000000` |
| **ConfigKey** | `contractDeployerAllowListConfig` |

## Configuration

You can activate this precompile in your genesis file:

```json
{
  "config": {
    "contractDeployerAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

By enabling this feature, you can define which addresses are allowed to deploy smart contracts and manage these permissions over time.

## Interface

The Contract Deployer Allowlist implements the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface):

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

interface IAllowList {
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

## Permissions Management

The Deployer Allowlist uses the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface) to manage permissions. This provides a consistent way to:
- Assign and revoke deployment permissions
- Manage admin and manager roles
- Control who can deploy contracts

For detailed information about the role-based permission system and available functions, see the [AllowList interface documentation](/docs/lux-l1s/precompiles/allowlist-interface).

## Best Practices

1. **Initial Setup**: Always configure at least one admin address in the genesis file to ensure you can manage permissions after deployment.

2. **Role Management**:
   - Use Admin roles sparingly and secure their private keys
   - Assign Manager roles to trusted entities who need to manage user access
   - Regularly audit the list of enabled addresses

3. **Security Considerations**:
   - Keep private keys of admin addresses secure
   - Implement a multi-sig wallet as an admin for additional security
   - Maintain an off-chain record of role assignments

4. **Monitoring**:
   - Monitor the `RoleSet` events to track permission changes
   - Regularly audit the enabled addresses list
   - Keep documentation of why each address was granted permissions

## Implementation

You can find the implementation in the [subnet-evm repository](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/deployerallowlist/contract.go).

## Interacting with the Precompile

For information on how to interact with this precompile, see:
- [Interacting with Precompiles](/docs/lux-l1s/precompiles/interacting-with-precompiles)
- [Deployer Allowlist Console](/console/l1-access-restrictions/deployer-allowlist)



# Fee Manager (/docs/lux-l1s/precompiles/fee-manager)

---
title: Fee Manager
description: Configure dynamic fee parameters and gas costs for your Lux L1 blockchain.
---

## Overview

The Fee Manager allows you to configure the parameters of the dynamic fee algorithm on-chain. This gives you control over:

- Gas limits and target block rates
- Base fee parameters
- Block gas cost parameters

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000003` |
| **ConfigKey** | `feeManagerConfig` |

## Configuration

You can activate this precompile in your genesis file:

```json
{
  "config": {
    "feeManagerConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"],
      "initialFeeConfig": {
        "gasLimit": 20000000,
        "targetBlockRate": 2,
        "minBaseFee": 1000000000,
        "targetGas": 100000000,
        "baseFeeChangeDenominator": 48,
        "minBlockGasCost": 0,
        "maxBlockGasCost": 10000000,
        "blockGasCostStep": 500000
      }
    }
  }
}
```

<Callout type="warn">
The following parameters were deprecated by the Granite upgrade:
- `targetBlockRate`
- `minBlockGasCost`
- `maxBlockGasCost`
- `blockGasCostStep`
</Callout>

## Fee Parameters

The Fee Manager allows configuration of the following parameters:

| Parameter | Description | Recommended Range |
|-----------|-------------|------------------|
| gasLimit | Maximum gas allowed per block | 8M - 100M |
| targetBlockRate | Target time between blocks (seconds) | 2 - 10 |
| minBaseFee | Minimum base fee (in wei) | 25 - 500 gwei |
| targetGas | Target gas spending over the last 10 seconds | 5M - 50M |
| baseFeeChangeDenominator | Controls how quickly base fee changes | 8 - 1000 |
| minBlockGasCost | Minimum gas cost for a block | 0 - 1B |
| maxBlockGasCost | Maximum gas cost for a block | > minBlockGasCost |
| blockGasCostStep | How quickly block gas cost changes | < 5M |

## Interface

```solidity
interface IFeeManager {
  struct FeeConfig {
    uint256 gasLimit;
    uint256 targetBlockRate;
    uint256 minBaseFee;
    uint256 targetGas;
    uint256 baseFeeChangeDenominator;
    uint256 minBlockGasCost;
    uint256 maxBlockGasCost;
    uint256 blockGasCostStep;
  }
  
  event FeeConfigChanged(address indexed sender, FeeConfig oldFeeConfig, FeeConfig newFeeConfig);

  function setFeeConfig(
    uint256 gasLimit,
    uint256 targetBlockRate,
    uint256 minBaseFee,
    uint256 targetGas,
    uint256 baseFeeChangeDenominator,
    uint256 minBlockGasCost,
    uint256 maxBlockGasCost,
    uint256 blockGasCostStep
  ) external;

  function getFeeConfig() external view returns (
    uint256 gasLimit,
    uint256 targetBlockRate,
    uint256 minBaseFee,
    uint256 targetGas,
    uint256 baseFeeChangeDenominator,
    uint256 minBlockGasCost,
    uint256 maxBlockGasCost,
    uint256 blockGasCostStep
  );

  function getFeeConfigLastChangedAt() external view returns (uint256 blockNumber);
}
```

## Access Control and Additional Features

The FeeManager precompile uses the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface) to restrict access to its functionality.

In addition to the AllowList interface, the FeeManager adds the following capabilities:

- `getFeeConfig`: retrieves the current dynamic fee config
- `getFeeConfigLastChangedAt`: retrieves the timestamp of the last block where the fee config was updated
- `setFeeConfig`: sets the dynamic fee config on chain. This function can only be called by an Admin, Manager or Enabled address.
- `FeeConfigChanged`: an event that is emitted when the fee config is updated. Topics include the sender, the old fee config, and the new fee config.

You can also get the fee configuration at a block with the `eth_feeConfig` RPC method. For more information see [here](/docs/rpcs/subnet-evm#eth_feeconfig).

## Best Practices

1. **Fee Configuration**:
   - Test fee changes on testnet first
   - Monitor network congestion and adjust accordingly
   - Document rationale for fee parameter changes
   - Announce changes to validators in advance

2. **Security Considerations**:
   - Use multi-sig for admin addresses
   - Monitor events for unauthorized changes
   - Have a plan for fee parameter adjustments
   - Keep backup of previous configurations

## Implementation

You can find the Fee Manager implementation in the [subnet-evm repository](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/feemanager/contract.go).

## Interacting with the Precompile

For information on how to interact with this precompile, see:
- [Interacting with Precompiles](/docs/lux-l1s/precompiles/interacting-with-precompiles)
- [Fee Manager Console](/console/l1-tokenomics/fee-manager)



# Interacting with Precompiles (/docs/lux-l1s/precompiles/interacting-with-precompiles)

---
title: Interacting with Precompiles
description: Learn how to interact with Lux L1 precompiles using the Lux Build Developer Console or Remix IDE.
---

This guide shows you how to interact with precompiled contracts on your Lux L1. For standard precompile implementations, we recommend using the **Lux Build Developer Console** for the best experience. For custom implementations or advanced use cases, you can use **Remix IDE** with browser wallets.

## Recommended: Using Lux Build Developer Console

The Lux Build provides dedicated tools for interacting with standard Lux L1 precompiles. These tools offer:

- ✅ **User-friendly interface** - No need to manually enter contract addresses or ABIs
- ✅ **Built-in validation** - Prevents common configuration mistakes
- ✅ **Connected to your Builder account** - Track your L1s and configurations
- ✅ **Visual feedback** - See changes reflected in real-time

### Available Console Tools

| Precompile | Console Tool |
|------------|--------------|
| Fee Manager | [Fee Manager Console](/console/l1-tokenomics/fee-manager) |
| Reward Manager | [Reward Manager Console](/console/l1-tokenomics/reward-manager) |
| Native Minter | [Native Minter Console](/console/l1-tokenomics/native-minter) |
| Contract Deployer Allowlist | [Deployer Allowlist Console](/console/l1-access-restrictions/deployer-allowlist) |
| Transaction Allowlist | [Transactor Allowlist Console](/console/l1-access-restrictions/transactor-allowlist) |

### How to Use Console Tools

1. **Navigate** to the appropriate console tool from the table above
2. **Connect** your wallet (Core or MetaMask)
3. **Switch** to your L1 network in your wallet
4. The tool will automatically detect your permissions
5. **Configure** using the visual interface:
   - For Fee Manager: Adjust gas limits, base fees, and target rates
   - For Native Minter: Mint tokens to specific addresses
   - For Allowlists: Add or remove addresses with specific roles
   - For Reward Manager: Configure fee distribution settings
6. **Review** the transaction details
7. **Submit** and approve in your wallet

<Callout type="info">
**Why use the Developer Console?**

Using the Lux Build console tools allows us to:
- Provide better support for your L1
- Track feature usage to improve the platform
- Build your profile in our builders/developers database
- Offer personalized recommendations and resources
</Callout>

### Example Workflows

**Configuring Transaction Fees:**
1. Go to [Fee Manager Console](/console/l1-tokenomics/fee-manager)
2. Connect wallet and switch to your L1
3. Adjust fee parameters using sliders and inputs
4. See real-time preview of how changes affect gas costs
5. Submit transaction to update fees

**Minting Native Tokens:**
1. Go to [Native Minter Console](/console/l1-tokenomics/native-minter)
2. Connect with an admin/manager address
3. Enter recipient address and amount
4. Review the minting transaction
5. Approve to mint tokens instantly

**Managing Permissions:**
1. Go to [Deployer Allowlist](/console/l1-access-restrictions/deployer-allowlist) or [Transactor Allowlist](/console/l1-access-restrictions/transactor-allowlist)
2. Connect with an admin address
3. Add addresses with desired roles (Admin, Manager, Enabled)
4. Remove addresses by changing their role to "None"
5. View current allowlist status

## Alternative: Using Remix IDE

For custom precompile implementations or if you prefer a code-based approach, you can use Remix IDE to interact with precompiles directly.

### When to Use Remix

Use Remix when:
- You have a **custom precompile** implementation (non-standard addresses or interfaces)
- You need to interact with precompiles **programmatically**
- You're **debugging** contract interactions
- The Builder Console doesn't support your specific use case

### Prerequisites

- Access to an Lux L1 where you have admin/manager rights for a precompile
- [Core Browser Extension](https://core.app) or MetaMask
- Private key for an admin/manager address on your L1
- Your L1's RPC URL and Chain ID

## Setup Your Wallet

### Using Core

1. Install the [Core Browser Extension](https://core.app)
2. Import or create the account with admin/manager privileges
3. Enable **Testnet Mode** (if using testnet):
   - Open Core extension
   - Click hamburger menu → **Advanced**
   - Toggle **Testnet Mode** on

4. Add your L1 network:
   - Click the networks dropdown
   - Select **Manage Networks**
   - Click **Add Network** and enter:
     - **Network Name**: Your L1 name
     - **RPC URL**: Your L1's RPC endpoint
     - **Chain ID**: Your L1's chain ID
     - **Symbol**: Your native token symbol
     - **Explorer**: (Optional) Your L1's explorer URL

5. Switch to your L1 network in the dropdown

### Using MetaMask

1. Install MetaMask browser extension
2. Import the account with admin/manager privileges
3. Add your L1 network:
   - Click the networks dropdown
   - Click **Add Network** → **Add a network manually**
   - Enter your L1's network details
   - Click **Save**

## Connect Remix to Your L1

1. Open [Remix IDE](https://remix.ethereum.org/) in your browser

2. In the left sidebar, click the **Deploy & run transactions** icon

3. In the **Environment** dropdown, select **Injected Provider - MetaMask** (or Core)

4. Approve the connection request in your wallet extension

5. Verify the connection shows your L1's network (e.g., "Custom (11111) network")

## Load Precompile Interfaces

You need to load the Solidity interfaces for the precompiles you want to interact with.

### Available Precompile Interfaces

From the Remix home screen, use **load from GitHub** to import:

**Required for all precompiles:**
- [IAllowList.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol)

**Specific precompile interfaces:**
- [IFeeManager.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IFeeManager.sol) - For fee configuration
- [INativeMinter.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/INativeMinter.sol) - For minting native tokens
- [IAllowList.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol) - For transaction/deployer allowlists
- [IRewardManager.sol](https://github.com/luxfi/subnet-evm/blob/master/contracts/contracts/interfaces/IRewardManager.sol) - For block rewards

### Compile the Interface

1. In Remix, click the **Solidity Compiler** icon in the left sidebar
2. Select the precompile interface file (e.g., `IFeeManager.sol`)
3. Click **Compile**

## Interact with Precompiles

### Connect to Deployed Precompile

Each precompile is deployed at a fixed address on your L1:

| Precompile | Address |
|------------|---------|
| NativeMinter | `0x0200000000000000000000000000000000000001` |
| ContractDeployerAllowList | `0x0200000000000000000000000000000000000000` |
| FeeManager | `0x0200000000000000000000000000000000000003` |
| RewardManager | `0x0200000000000000000000000000000000000004` |
| TransactionAllowList | `0x0200000000000000000000000000000000000002` |

1. In Remix, click **Deploy & run transactions**
2. In the **Contract** dropdown, select your compiled interface
3. Paste the precompile address in the **At Address** field
4. Click **At Address**

The precompile contract will appear in the **Deployed Contracts** section.

## Example: Using Fee Manager

### Read Current Fee Configuration

Anyone can read the current fee configuration (no special permissions required):

1. Expand the FeeManager contract in **Deployed Contracts**
2. Click **getFeeConfig**
3. View the current fee parameters:
   - `gasLimit`: Maximum gas per block
   - `targetBlockRate`: Target time between blocks (seconds)
   - `minBaseFee`: Minimum base fee (wei)
   - `targetGas`: Target gas per second
   - `baseFeeChangeDenominator`: Rate of base fee adjustment
   - `minBlockGasCost`: Minimum gas cost for a block
   - `maxBlockGasCost`: Maximum gas cost for a block
   - `blockGasCostStep`: Increment for block gas cost

### Update Fee Configuration

Only admin addresses can update the fee configuration:

1. Ensure you're connected with the admin address in your wallet
2. Expand **setFeeConfig** in the FeeManager contract
3. Fill in the new fee parameters:
   ```
   gasLimit: 8000000
   targetBlockRate: 2
   minBaseFee: 25000000000
   targetGas: 15000000
   baseFeeChangeDenominator: 36
   minBlockGasCost: 0
   maxBlockGasCost: 1000000
   blockGasCostStep: 200000
   ```
4. Click **transact**
5. Approve the transaction in your wallet
6. Wait for transaction confirmation

The new fee configuration takes effect immediately after the transaction is accepted.

## Example: Using Native Minter

### Mint Native Tokens

Only admin, manager, or enabled addresses can mint native tokens:

1. Expand the NativeMinter contract in **Deployed Contracts**
2. Click on **mintNativeCoin**
3. Fill in the parameters:
   - `addr`: Recipient address (e.g., `0xB78cbAa319ffBD899951AA30D4320f5818938310`)
   - `amount`: Amount to mint in wei (e.g., `1000000000000000000` for 1 token)
4. Click **transact**
5. Approve the transaction in your wallet

The minted tokens are added directly to the recipient's balance by the EVM (no sender transaction).

### Check Minting Permissions

Anyone can check who has minting permissions:

1. Click **readAllowList** with an address parameter
2. Returns:
   - `0`: No permission
   - `1`: Enabled (can mint)
   - `2`: Manager (can mint and manage enabled addresses)  
   - `3`: Admin (full control)

## Example: Managing Allow Lists

### Add Address to Allow List

Admins can add addresses to transaction or deployer allow lists:

1. Expand the AllowList contract
2. Use **setAdmin**, **setManager**, or **setEnabled**:
   ```
   addr: 0x1234...5678
   ```
3. Click **transact**
4. Approve in wallet

### Remove Address from Allow List

1. Use **setNone** with the address:
   ```
   addr: 0x1234...5678
   ```
2. Click **transact**

### Check Address Status

1. Click **readAllowList**:
   ```
   addr: 0x1234...5678
   ```
2. Returns permission level (0-3)

## Best Practices

### Security

- **Never share private keys** for admin addresses
- **Use hardware wallets** for admin accounts when possible
- **Test on testnet first** before making changes on mainnet
- **Use multi-sig contracts** for critical admin operations
- **Document all changes** and announce them to validators

### Network Upgrades

When enabling precompiles via network upgrades:

1. **Announce upgrades** well in advance on social media and Discord
2. **Coordinate with validators** to ensure they update their nodes
3. **Use upgrade.json** to schedule precompile activation (see [Precompile Upgrades](/docs/lux-l1s/upgrade/precompile-upgrades))
4. **Test the upgrade** on a testnet first
5. **Monitor** the network after activation

### Troubleshooting

**Connection Issues:**
- Verify your wallet is connected to the correct network
- Check that the RPC URL is accessible
- Ensure you have native tokens for gas fees

**Transaction Failures:**
- Confirm you're using an admin/manager address
- Check that the precompile is enabled on your L1
- Verify parameter formats (addresses must be checksummed)
- Ensure sufficient gas limit

**Precompile Not Found:**
- Verify the precompile address is correct
- Confirm the precompile is activated in your genesis or upgrade.json
- Check that you're on the correct network

## Additional Resources

### Lux Build Console Tools
- [Fee Manager Console](/console/l1-tokenomics/fee-manager) - Configure transaction fees
- [Reward Manager Console](/console/l1-tokenomics/reward-manager) - Manage fee distribution
- [Native Minter Console](/console/l1-tokenomics/native-minter) - Mint native tokens
- [Deployer Allowlist Console](/console/l1-access-restrictions/deployer-allowlist) - Control contract deployment
- [Transactor Allowlist Console](/console/l1-access-restrictions/transactor-allowlist) - Control transaction submission

### Documentation
- [Precompile Configuration](/docs/lux-l1s/evm-configuration/evm-l1-customization) - Overview of precompiles
- [Fee Manager](/docs/lux-l1s/precompiles/fee-manager) - Fee Manager details
- [Reward Manager](/docs/lux-l1s/precompiles/reward-manager) - Reward Manager details
- [Native Minter](/docs/lux-l1s/precompiles/native-minter) - Native Minter details
- [Deployer AllowList](/docs/lux-l1s/precompiles/deployer-allowlist) - Deployer Allowlist details
- [Transaction AllowList](/docs/lux-l1s/precompiles/transaction-allowlist) - Transaction Allowlist details
- [Warp Messenger](/docs/lux-l1s/precompiles/warp-messenger) - Warp Messenger details
- [Precompile Upgrades](/docs/lux-l1s/upgrade/precompile-upgrades) - Network upgrade process
- [AllowList Interface](/docs/lux-l1s/precompiles/allowlist-interface) - Role-based access control
- [Subnet-EVM Contracts](https://github.com/luxfi/subnet-evm/tree/master/contracts/contracts/interfaces) - Precompile interfaces

## Conclusion

For standard Lux L1 precompiles, **we strongly recommend using the [Lux Build Developer Console tools](/console)** for the best experience. These tools provide:

- ✅ Guided workflows with validation
- ✅ No need to manage contract addresses or ABIs manually  
- ✅ Integration with your Lux Build account
- ✅ Support from the Lux Build team

For custom implementations or advanced scenarios, the Remix IDE approach provides flexibility to interact with any contract at any address. This is useful for:

- Custom precompile implementations
- Testing and debugging
- Programmatic interactions
- Non-standard use cases

Whichever method you choose, always test on testnet first and follow security best practices when managing admin keys.



# Native Minter (/docs/lux-l1s/precompiles/native-minter)

---
title: Native Minter
description: Manage the minting and burning of native tokens on your Lux L1 blockchain.
---

## Overview

The Native Minter precompile allows authorized addresses to mint additional tokens after network launch. This is useful for:

- Implementing programmatic token emission schedules
- Providing validator rewards
- Supporting ecosystem growth initiatives
- Implementing monetary policy

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000001` |
| **ConfigKey** | `contractNativeMinterConfig` |

## Configuration

You can activate this precompile in your genesis file:

```json
{
  "config": {
    "contractNativeMinterConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

## Interface

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
 
interface INativeMinter {
  event NativeCoinMinted(address indexed sender, address indexed recipient, uint256 amount);
  // Mint [amount] number of native coins and send to [addr]
  function mintNativeCoin(address addr, uint256 amount) external;
 
  // IAllowList
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);
 
  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;
 
  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;
 
  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;
 
  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;
 
  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

The Native Minter precompile uses the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface) to restrict access to its functionality.

## Best Practices

1. **Minting Policy**:
   - Define clear minting guidelines
   - Use multi-sig for admin control
   - Implement transparent emission schedules
   - Monitor total supply changes

2. **Supply Management**:
   - Balance minting with burning mechanisms
   - Consider implementing supply caps
   - Monitor token velocity and distribution
   - Plan for long-term sustainability

3. **Security Considerations**:
   - Use multi-sig wallets for admin addresses
   - Implement time-locks for large mints
   - Regular audits of minting activity
   - Monitor for unusual minting patterns

4. **Validator Incentives**:
   - Design sustainable reward mechanisms
   - Balance inflation with network security
   - Consider validator stake requirements
   - Plan for long-term validator participation

## Example Implementations

### Programmatic Emission Schedule

```solidity
contract EmissionSchedule {
    INativeMinter public constant NATIVE_MINTER = INativeMinter(0x0200000000000000000000000000000000000001);
    uint256 public constant EMISSION_RATE = 1000 * 1e18; // 1000 tokens per day
    uint256 public constant EMISSION_DURATION = 365 days;
    uint256 public immutable startTime;

    constructor() {
        startTime = block.timestamp;
    }

    function mintDailyEmission() external {
        require(block.timestamp < startTime + EMISSION_DURATION, "Emission ended");
        NATIVE_MINTER.mintNativeCoin(address(this), EMISSION_RATE);
        // Distribution logic here
    }
}
```

### Validator Reward Contract

```solidity
contract ValidatorRewards {
    INativeMinter public constant NATIVE_MINTER = INativeMinter(0x0200000000000000000000000000000000000001);
    uint256 public constant REWARD_RATE = 10 * 1e18; // 10 tokens per block

    function distributeRewards(address[] calldata validators) external {
        uint256 reward = REWARD_RATE / validators.length;
        for (uint i = 0; i < validators.length; i++) {
            NATIVE_MINTER.mintNativeCoin(validators[i], reward);
        }
    }
}
```

## Implementation

You can find the Native Minter implementation in the [subnet-evm repository](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/nativeminter/contract.go).

## Interacting with the Precompile

For information on how to interact with this precompile, see:
- [Interacting with Precompiles](/docs/lux-l1s/precompiles/interacting-with-precompiles)
- [Native Minter Console](/console/l1-tokenomics/native-minter)



# Reward Manager (/docs/lux-l1s/precompiles/reward-manager)

---
title: Reward Manager
description: Control how transaction fees are distributed or burned on your Lux L1 blockchain.
---

## Overview

The Reward Manager allows you to control how transaction fees are handled in your network. You can:

- Send fees to a specific address (e.g., treasury)
- Allow validators to collect fees
- Burn fees entirely

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000004` |
| **ConfigKey** | `rewardManagerConfig` |

## Configuration

You can activate this precompile in your genesis file:

```json
{
  "config": {
    "rewardManagerConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"],
      "initialRewardConfig": {
        // Choose one of:
        "allowFeeRecipients": true,  // Allow validators to collect fees
        "rewardAddress": "0x...",    // Send fees to specific address
        // Empty config = burn fees
      }
    }
  }
}
```

## Reward Mechanisms

The Reward Manager supports three mutually exclusive mechanisms:

1. **Validator Fee Collection** (`allowFeeRecipients`)
   - Validators can specify their own fee recipient addresses
   - Fees go to the block producer's chosen address
   - Good for incentivizing network participation

2. **Fixed Reward Address** (`rewardAddress`)
   - All fees go to a single specified address
   - Can be a contract or EOA
   - Useful for treasury or DAO-controlled fee collection

3. **Fee Burning** (default)
   - All transaction fees are burned
   - Reduces total token supply over time
   - Similar to Ethereum's EIP-1559

## Interface

```solidity
interface IRewardManager {
  event RewardAddressChanged(
    address indexed sender,
    address indexed oldRewardAddress,
    address indexed newRewardAddress
  );
  event FeeRecipientsAllowed(address indexed sender);
  event RewardsDisabled(address indexed sender);

  function setRewardAddress(address addr) external;
  function allowFeeRecipients() external;
  function disableRewards() external;
  function currentRewardAddress() external view returns (address rewardAddress);
  function areFeeRecipientsAllowed() external view returns (bool isAllowed);
}
```

The Reward Manager precompile uses the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface) to restrict access to its functionality.

## Best Practices

1. **Reward Management**:
   - Choose reward mechanism based on network goals
   - Consider using a multi-sig or DAO as reward address
   - Monitor fee collection and distribution
   - Keep documentation of fee policy changes

2. **Security Considerations**:
   - Use multi-sig for admin addresses
   - Test reward changes on testnet first
   - Monitor events for unauthorized changes
   - Have a plan for reward parameter adjustments

## Implementation

You can find the Reward Manager implementation in the [subnet-evm repository](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/rewardmanager/contract.go).

## Interacting with the Precompile

For information on how to interact with this precompile, see:
- [Interacting with Precompiles](/docs/lux-l1s/precompiles/interacting-with-precompiles)
- [Reward Manager Console](/console/l1-tokenomics/reward-manager)



# Transaction AllowList (/docs/lux-l1s/precompiles/transaction-allowlist)

---
title: Transaction AllowList
description: Control which addresses can submit transactions on your Lux L1 blockchain.
---

## Overview

The Transaction Allowlist enables you to control which addresses can submit transactions to your network. This is essential for:

- Creating fully permissioned networks
- Implementing KYC/AML requirements for users
- Controlling network access during testing or initial deployment

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000002` |
| **ConfigKey** | `txAllowListConfig` |

## Configuration

You can activate this precompile in your genesis file:

```json
{
  "config": {
    "txAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

By enabling this feature, you can define which addresses are allowed to submit transactions and manage these permissions over time.

## Interface

The Transaction Allowlist implements the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface):

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

interface IAllowList {
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

## Permissions Management

The Transaction Allowlist uses the [AllowList interface](/docs/lux-l1s/precompiles/allowlist-interface) to manage permissions. This provides a consistent way to:
- Assign and revoke transaction permissions
- Manage admin and manager roles
- Control who can submit transactions

For detailed information about the role-based permission system and available functions, see the [AllowList interface documentation](/docs/lux-l1s/precompiles/allowlist-interface).

## Best Practices

1. **Initial Setup**: Always configure at least one admin address in the genesis file to ensure you can manage permissions after deployment.

2. **Role Management**:
   - Use Admin roles sparingly and secure their private keys
   - Assign Manager roles to trusted entities who need to manage user access
   - Regularly audit the list of enabled addresses

3. **Security Considerations**:
   - Keep private keys of admin addresses secure
   - Implement a multi-sig wallet as an admin for additional security
   - Maintain an off-chain record of role assignments

4. **Monitoring**:
   - Monitor the `RoleSet` events to track permission changes
   - Regularly audit the enabled addresses list
   - Keep documentation of why each address was granted permissions

## Implementation

You can find the implementation in the [subnet-evm repository](https://github.com/luxfi/subnet-evm/blob/master/precompile/contracts/txallowlist/contract.go).

## Interacting with the Precompile

For information on how to interact with this precompile, see:
- [Interacting with Precompiles](/docs/lux-l1s/precompiles/interacting-with-precompiles)
- [Transactor Allowlist Console](/console/l1-access-restrictions/transactor-allowlist)



# Warp Messenger (/docs/lux-l1s/precompiles/warp-messenger)

---
title: Warp Messenger
description: Enable cross-chain communication between Lux L1s using Lux Warp Messaging.
edit_url: https://github.com/luxfi/subnet-evm/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/precompile/contracts/warp/README.md
---

## Overview

Lux Warp Messaging offers a basic primitive to enable Cross-L1 communication on the Lux Network. It is intended to allow communication between arbitrary Custom Virtual Machines (including, but not limited to Subnet-EVM and Coreth).

| Property | Value |
|----------|-------|
| **Address** | `0x0200000000000000000000000000000000000005` |
| **ConfigKey** | `warpConfig` |

## How does Lux Warp Messaging Work?

Lux Warp Messaging uses BLS Multi-Signatures with Public-Key Aggregation where every Lux validator registers a public key alongside its NodeID on the Lux Platform-Chain.

Every node tracking an Lux L1 has read access to the Lux Platform-Chain. This provides weighted sets of BLS Public Keys that correspond to the validator sets of each L1 on the Lux Network. Lux Warp Messaging provides a basic primitive for signing and verifying messages between L1s: the receiving network can verify whether an aggregation of signatures from a set of source L1 validators represents a threshold of stake large enough for the receiving network to process the message.

For more details on Lux Warp Messaging, see the LuxGo [Warp README](https://docs.lux.network/build/cross-chain/awm/deep-dive).

## Configuration

The Warp Messenger precompile is enabled by default on all Lux L1s and does not require explicit configuration in the genesis file. However, you can configure it if needed:

```json
{
  "config": {
    "warpConfig": {
      "blockTimestamp": 0,
      "quorumNumerator": 67
    }
  }
}
```

### Configuration Parameters

- `blockTimestamp`: The timestamp when the precompile should be activated (0 for genesis)
- `quorumNumerator`: The percentage of stake weight required to verify a message (default: 67, meaning 67%)

<Callout type="info">
Unlike other precompiles, Warp Messenger does not use the AllowList interface - it is available to all addresses by default.
</Callout>

## Interface

The Warp Messenger precompile provides the following Solidity interface:

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

interface IWarpMessenger {
  event SendWarpMessage(address indexed sender, bytes32 indexed messageID, bytes message);

  // sendWarpMessage emits a request for the subnet to sign a Warp message with the provided payload
  // The message emitted in the log is the unsigned Warp message
  function sendWarpMessage(bytes calldata payload) external returns (bytes32 messageID);

  // getVerifiedWarpMessage returns the verified Warp message if it exists, otherwise returns (WarpMessage, false)
  function getVerifiedWarpMessage(uint32 index) external view returns (WarpMessage memory message, bool valid);

  // getBlockchainID returns the blockchainID of the current chain
  function getBlockchainID() external view returns (bytes32 blockchainID);
}

struct WarpMessage {
  bytes32 sourceChainID;
  address originSenderAddress;
  bytes payload;
}
```

## Flow of Sending / Receiving a Warp Message within the EVM

The Lux Warp Precompile enables this flow to send a message from blockchain A to blockchain B:

1. Call the Warp Precompile `sendWarpMessage` function with the arguments for the `UnsignedMessage`
2. Warp Precompile emits an event / log containing the `UnsignedMessage` specified by the caller of `sendWarpMessage`
3. Network accepts the block containing the `UnsignedMessage` in the log, so that validators are willing to sign the message
4. An off-chain relayer queries the validators for their signatures of the message and aggregates the signatures to create a `SignedMessage`
5. The off-chain relayer encodes the `SignedMessage` as the [predicate](#predicate-encoding) in the AccessList of a transaction to deliver on blockchain B
6. The transaction is delivered on blockchain B, the signature is verified prior to executing the block, and the message is accessible via the Warp Precompile's `getVerifiedWarpMessage` during the execution of that transaction

## Warp Precompile Functions

The Warp Precompile is broken down into three functions defined in the Solidity interface file [here](https://github.com/luxfi/subnet-evm/blob/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/contracts/contracts/interfaces/IWarpMessenger.sol).

### sendWarpMessage

`sendWarpMessage` is used to send a verifiable message. Calling this function results in sending a message with the following contents:

- `SourceChainID` - blockchainID of the sourceChain on the Lux Platform-Chain
- `SourceAddress` - `msg.sender` encoded as a 32 byte value that calls `sendWarpMessage`
- `Payload` - `payload` argument specified in the call to `sendWarpMessage` emitted as the unindexed data of the resulting log

Calling this function will issue a `SendWarpMessage` event from the Warp Precompile. Since the EVM limits the number of topics to 4 including the EventID, this message includes only the topics that would be expected to help filter messages emitted from the Warp Precompile the most.

Specifically, the `payload` is not emitted as a topic because each topic must be encoded as a hash. Therefore, we opt to take advantage of each possible topic to maximize the possible filtering for emitted Warp Messages.

Additionally, the `SourceChainID` is excluded because anyone parsing the chain can be expected to already know the blockchainID. Therefore, the `SendWarpMessage` event includes the indexable attributes:

- `sender`
- The `messageID` of the unsigned message (sha256 of the unsigned message)

The actual `message` is the entire [Lux Warp Unsigned Message](https://github.com/luxfi/luxgo/blob/master/vms/platformvm/warp/unsigned_message.go#L14) including an [AddressedCall](https://github.com/luxfi/luxgo/tree/master/vms/platformvm/warp/payload#readme). The unsigned message is emitted as the unindexed data in the log.

### getVerifiedMessage

`getVerifiedMessage` is used to read the contents of the delivered Lux Warp Message into the expected format.

It returns the message if present and a boolean indicating if a message is present.

To use this function, the transaction must include the signed Lux Warp Message encoded in the [predicate](#predicate-encoding) of the transaction. Prior to executing a block, the VM iterates through transactions and pre-verifies all predicates. If a transaction's predicate is invalid, then it is considered invalid to include in the block and dropped.

This leads to the following advantages:

1. The EVM execution does not need to verify the Warp Message at runtime (no signature verification or external calls to the Platform-Chain)
2. The EVM can deterministically re-execute and re-verify blocks assuming the predicate was verified by the network (e.g., in bootstrapping)

This pre-verification is performed using the ProposerVM Block header during [block verification](https://github.com/luxfi/subnet-evm/blob/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/plugin/evm/block.go#L220) and [block building](https://github.com/luxfi/subnet-evm/blob/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/miner/worker.go#L200).

### getBlockchainID

`getBlockchainID` returns the blockchainID of the blockchain that the VM is running on.

This is different from the conventional Ethereum ChainID registered to [ChainList](https://chainlist.org/).

The `blockchainID` in Lux refers to the txID that created the blockchain on the Lux Platform-Chain ([docs](https://docs.lux.network/specs/platform-transaction-serialization#unsigned-create-chain-tx)).

## Predicate Encoding

Lux Warp Messages are encoded as a signed Lux [Warp Message](https://github.com/luxfi/luxgo/blob/master/vms/platformvm/warp/message.go) where the [UnsignedMessage](https://github.com/luxfi/luxgo/blob/master/vms/platformvm/warp/unsigned_message.go)'s payload includes an [AddressedPayload](https://github.com/luxfi/luxgo/blob/master/vms/platformvm/warp/payload/payload.go).

Since the predicate is encoded into the [Transaction Access List](https://eips.ethereum.org/EIPS/eip-2930), it is packed into 32 byte hashes intended to declare storage slots that should be pre-warmed into the cache prior to transaction execution.

Therefore, we use the [Predicate Utils](https://github.com/luxfi/subnet-evm/blob/master/predicate/Predicate.md) package to encode the actual byte slice of size N into the access list.

## Performance Optimization: Primary Network to Lux L1

The Primary Network has a large validator set compared to most Subnets and L1s, which makes Warp signature collection and verification from the entire Primary Network validator set costly. All Subnets and L1s track at least one blockchain of the Primary Network, so we can instead optimize this by using the validator set of the receiving L1 instead of the Primary Network for certain Warp messages.

### Subnets

Recall that Lux Subnet validators must also validate the Primary Network, so it tracks all of the blockchains in the Primary Network (X, C, and Platform-Chains).

When an Lux Subnet receives a message from a blockchain on the Primary Network, we use the validator set of the receiving Subnet instead of the entire network when validating the message. 

Sending messages from the X, C, or Platform-Chain remains unchanged.
However, when the Subnet receives the message, it changes the semantics to the following:

1. Read the `SourceChainID` of the signed message
2. Look up the `SubnetID` that validates `SourceChainID`. In this case it will be the Primary Network's `SubnetID`
3. Look up the validator set of the Subnet (instead of the Primary Network) and the registered BLS Public Keys of the Subnet validators at the Platform-Chain height specified by the ProposerVM header
4. Continue Warp Message verification using the validator set of the Subnet instead of the Primary Network

This means that Primary Network to Subnet communication only requires a threshold of stake on the receiving Subnet to sign the message instead of a threshold of stake for the entire Primary Network.

Since the security of the Subnet is provided by trust in its validator set, requiring a threshold of stake from the receiving Subnet's validator set instead of the whole Primary Network does not meaningfully change the security of the receiving L1.

Note: this special case is ONLY applied during Warp Message verification. The message sent by the Primary Network will still contain the blockchainID of the Primary Network chain that sent the message as the sourceChainID and signatures will be served by querying the source chain directly.

### L1s

Lux L1s are only required to sync the Platform-Chain, but are not required to validate the Primary Network. Therefore, **for L1s, this optimization only applies to Warp messages sent by the Platform-Chain.** The rest of the description of this optimization in the above section applies to L1s.

Note that **in order to properly verify messages from the LUExchange-Chain and Exchange-Chain, the Warp precompile must be configured with `requirePrimaryNetworkSigners` set to `true`**. Otherwise, we will attempt to verify the message signature against the receiving L1's validator set, which is not required to track the LUExchange-Chain or Exchange-Chain, and therefore will not in general be able to produce a valid Warp message.

## Design Considerations

### Re-Processing Historical Blocks

Lux Warp Messaging depends on the Lux Platform-Chain state at the Platform-Chain height specified by the ProposerVM block header.

Verifying a message requires looking up the validator set of the source L1 on the Platform-Chain. To support this, Lux Warp Messaging uses the ProposerVM header, which includes the Platform-Chain height it was issued at as the canonical point to lookup the source L1's validator set.

This means verifying the Warp Message and therefore the state transition on a block depends on state that is external to the blockchain itself: the Platform-Chain.

The Lux Platform-Chain tracks only its current state and reverse diff layers (reversing the changes from past blocks) in order to re-calculate the validator set at a historical height. This means calculating a very old validator set that is used to verify a Warp Message in an old block may become prohibitively expensive.

Therefore, we need a heuristic to ensure that the network can correctly re-process old blocks (note: re-processing old blocks is a requirement to perform bootstrapping and is used in some VMs to serve or verify historical data).

As a result, we require that the block itself provides a deterministic hint which determines which Lux Warp Messages were considered valid/invalid during the block's execution. This ensures that we can always re-process blocks and use the hint to decide whether an Lux Warp Message should be treated as valid/invalid even after the Platform-Chain state that was used at the original execution time may no longer support fast lookups.

To provide that hint, we've explored two designs:

1. Include a predicate in the transaction to ensure any referenced message is valid
2. Append the results of checking whether a Warp Message is valid/invalid to the block data itself

The current implementation uses option (1).

The original reason for this was that the notion of predicates for precompiles was designed with Shared Memory in mind. In the case of shared memory, there is no canonical "Platform-Chain height" in the block which determines whether or not Lux Warp Messages are valid.

Instead, the VM interprets a shared memory import operation as valid as soon as the UTXO is available in shared memory. This means that if it were up to the block producer to staple the valid/invalid results of whether or not an attempted atomic operation should be treated as valid, a byzantine block producer could arbitrarily report that such atomic operations were invalid and cause a griefing attack to burn the gas of users that attempted to perform an import.

Therefore, a transaction specified predicate is required to implement the shared memory precompile to prevent such a griefing attack.

In contrast, Lux Warp Messages are validated within the context of an exact Platform-Chain height. Therefore, if a block producer attempted to lie about the validity of such a message, the network would interpret that block as invalid.

### Guarantees Offered by Warp Precompile vs. Built on Top

#### Guarantees Offered by Warp Precompile

The Warp Precompile was designed with the intention of minimizing the trusted computing base for the VM as much as possible. Therefore, it makes several tradeoffs which encourage users to use protocols built ON TOP of the Warp Precompile itself as opposed to directly using the Warp Precompile.

The Warp Precompile itself provides ONLY the following ability:

- Emit a verifiable message from (Address A, Blockchain A) to (Address B, Blockchain B) that can be verified by the destination chain

#### Explicitly Not Provided / Built on Top

The Warp Precompile itself does not provide any guarantees of:

- Eventual message delivery (may require re-send on blockchain A and additional assumptions about off-chain relayers and chain progress)
- Ordering of messages (requires ordering provided a layer above)
- Replay protection (requires replay protection provided a layer above)



# Considerations (/docs/lux-l1s/upgrade/considerations)

---
title: Considerations
description: Learn about some of the key considerations while upgrading your Lux L1.
---

In the course of Lux L1 operation, you will inevitably need to upgrade or change some part of the software stack that is running your Lux L1. If nothing else, you will have to upgrade the LuxGo node client. Same goes for the VM plugin binary that is used to run the blockchain on your Lux L1, which is most likely the [Subnet-EVM](https://github.com/luxfi/subnet-evm), the Lux L1 implementation of the Ethereum virtual machine.

Node and VM upgrades usually don't change the way your Lux L1 functions, instead they keep your Lux L1 in sync with the rest of the network, bringing security, performance and feature upgrades. Most upgrades are optional, but all of them are recommended, and you should make optional upgrades part of your routine Lux L1 maintenance. Some upgrades will be mandatory, and those will be clearly communicated as such ahead of time, you need to pay special attention to those.

Besides the upgrades due to new releases, you also may want to change the configuration of the VM, to alter the way Lux L1 runs, for various business or operational needs. These upgrades are solely the purview of your team, and you have complete control over the timing of their roll out. Any such change represents a **network upgrade** and needs to be carefully planned and executed.

<Callout type="warn">
Network Upgrades Permanently Change the Rules of Your Lux L1. Procedural mistakes or a botched upgrade can halt your Lux L1 or lead to data loss!

When performing an Lux L1 upgrade, every single validator on the Lux L1 will need to perform the identical upgrade.

If you are coordinating a network upgrade, you must schedule advance notice to every Lux L1 validator so that they have time to perform the upgrade prior to activation. Make sure you have direct line of communication to all your validators!
</Callout>

This tutorial will guide you through the process of doing various Lux L1 upgrades and changes. We will point out things to watch out for and precautions you need to be mindful about.

General Upgrade Considerations[​](#general-upgrade-considerations "Direct link to heading")
-------------------------------------------------------------------------------------------

When operating an Lux L1, you should always keep in mind that Proof of Stake networks like Lux can only make progress if sufficient amount of validating nodes are connected and processing transactions. Each validator on an Lux L1 is assigned a certain `weight`, which is a numerical value representing the significance of the node in consensus decisions. On the Primary Network, weight is equal to the amount of LUX staked on the node. On Lux L1s, weight is currently assigned by the Lux L1 owners when they issue the transaction adding a validator to the Lux L1.

Lux L1s can operate normally only if validators representing 80% or more of the cumulative validator weight is connected. If the amount of connected stake falls close to or below 80%, Lux L1 performance (time to finality) will suffer, and ultimately the Lux L1 will halt (stop processing transactions).

You as an Lux L1 operator need to ensure that whatever you do, at least 80% of the validators' cumulative weight is connected and working at all times.

<Callout title="Note">
It is mandatory that the cumulative weight of all validators in the Lux L1 must be at least the value of [`snow-sample-size`](/docs/nodes/configure/configs-flags#--snow-sample-size-int) (default 20). For example, if there is only one validator in the Lux L1, its weight must be at least `snow-sample-size` . Hence, when assigning weight to the nodes, always use values greater than 20. Recall that a validator's weight can't be changed while it is validating, so take care to use an appropriate value.
</Callout>

Upgrading Lux L1 Validator Nodes[​](#upgrading-lux-l1-validator-nodes "Direct link to heading")
-----------------------------------------------------------------------------------------------

LuxGo, the node client that is running the Lux validators is under constant and rapid development. New versions come out often (roughly every two weeks), bringing added capabilities, performance improvements or security fixes. Updates are usually optional, but from time to time (much less frequently than regular updates) there will be an update that includes a mandatory network upgrade. Those upgrades are **MANDATORY** for every node running the Lux L1. Any node that does not perform the update before the activation timestamp will immediately stop working when the upgrade activates.

That's why having a node upgrade strategy is absolutely vital, and you should always update to the latest LuxGo client immediately when it is made available.

For a general guide on upgrading LuxGo check out [this tutorial](/docs/nodes/maintain/upgrade). When upgrading Lux L1 nodes and keeping in mind the previous section, make sure to stagger node upgrades and start a new upgrade only once the previous node has successfully upgraded. Use the [Health API](/docs/rpcs/other/health-rpc#healthhealth) to check that `healthy` value in the response is `true` on the upgraded node, and on other Lux L1 validators check that [platform.getCurrentValidators()](/docs/rpcs/p-chain#platformgetcurrentvalidators) has `true` in `connected` attribute for the upgraded node's `nodeID`. Once those two conditions are satisfied, node is confirmed to be online and validating the Lux L1 and you can start upgrading another node.

Continue the upgrade cycle until all the Lux L1 nodes are upgraded.

Upgrading Lux L1 VM Plugin Binaries[​](#upgrading-lux-l1-vm-plugin-binaries "Direct link to heading")
-----------------------------------------------------------------------------------------------------

Besides the LuxGo client itself, new versions get released for the VM binaries that run the blockchains on the Lux L1. On most Lux L1s, that is the [Subnet-EVM](https://github.com/luxfi/subnet-evm), so this tutorial will go through the steps for updating the `subnet-evm` binary. The update process will be similar for updating any VM plugin binary.

All the considerations for doing staggered node upgrades as discussed in previous section are valid for VM upgrades as well.

In the future, VM upgrades will be handled by the [Lux-CLI tool](https://github.com/luxfi/lux-cli), but for now we need to do it manually.

Go to the [releases page](https://github.com/luxfi/subnet-evm/releases) of the Subnet-EVM repository. Locate the latest version, and copy link that corresponds to the OS and architecture of the machine the node is running on (`darwin` = Mac, `amd64` = Intel/AMD processor, `arm64` = Arm processor). Log into the machine where the node is running and download the archive, using `wget` and the link to the archive, like this:

```bash
wget https://github.com/luxfi/subnet-evm/releases/download/v0.2.9/subnet-evm_0.2.9_linux_amd64.tar.gz
```

This will download the archive to the machine. Unpack it like this (use the correct filename, of course):

```bash
tar xvf subnet-evm_0.2.9_linux_amd64.tar.gz
```

This will unpack and place the contents of the archive in the current directory, file `subnet-evm` is the plugin binary. You need to stop the node now (if the node is running as a service, use `sudo systemctl stop luxgo` command). You need to place that file into the plugins directory where the LuxGo binary is located. If the node is installed using the install script, the path will be `~/lux-node/plugins` Instead of the `subnet-evm` filename, VM binary needs to be named as the VM ID of the chain on the Lux L1. For example, for the [WAGMI Lux L1](/docs/lux-l1s/wagmi-lux-l1) that VM ID is `srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`. So, the command to copy the new plugin binary would look like:

```bash
cp subnet-evm ~/lux-node/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
```

<Callout type="warn">
Make sure you use the correct VM ID, otherwise, your VM will not get updated and your Lux L1 may halt.
</Callout>

After you do that, you can start the node back up (if running as service do `sudo systemctl start luxgo`). You can monitor the log output on the node to check that everything is OK, or you can use the [info.getNodeVersion()](/docs/rpcs/other/info-rpc#infogetnodeversion) API to check the versions. Example output would look like:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "version": "lux/1.7.18",
    "databaseVersion": "v1.4.5",
    "gitCommit": "b6d5827f1a87e26da649f932ad649a4ea0e429c4",
    "vmVersions": {
      "xvm": "v1.7.18",
      "evm": "v0.8.15",
      "platform": "v1.7.18",
      "sqja3uK17MJxfC7AN8nGadBw9JK5BcrsNwNynsqP5Gih8M5Bm": "v0.0.7",
      "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy": "v0.2.9"
    }
  },
  "id": 1
}
```

Note that entry next to the VM ID we upgraded correctly says `v0.2.9`. You have successfully upgraded the VM!

Refer to the previous section on how to make sure node is healthy and connected before moving on to upgrading the next Lux L1 validator.

If you don't get the expected result, you can stop the `LuxGo`, examine and follow closely step-by-step of the above. You are free to remove files under `~/lux-node/plugins`, however, you should keep in mind that removing files is to remove an existing VM binary. You must put the correct VM plugin in place before you restart LuxGo.

Network Upgrades[​](#network-upgrades "Direct link to heading")
---------------------------------------------------------------

Sometimes you need to do a network upgrade to change the configured rules in the genesis under which the Chain operates. In regular EVM, network upgrades are a pretty involved process that includes deploying the new EVM binary, coordinating the timed upgrade and deploying changes to the nodes. But since [Subnet-EVM v0.2.8](https://github.com/luxfi/subnet-evm/releases/tag/v0.2.8), we introduced the long awaited feature to perform network upgrades by just using a few lines of JSON. Upgrades can consist of enabling/disabling particular precompiles, or changing their parameters. Currently available precompiles allow you to:

- Restrict Smart Contract Deployers
- Restrict Who Can Submit Transactions
- Mint Native Coins
- Configure Dynamic Fees

Please refer to [Customize an Lux L1](/docs/lux-l1s/evm-configuration/customize-lux-l1#network-upgrades-enabledisable-precompiles) for a detailed discussion of possible precompile upgrade parameters.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Vital part of Lux L1 maintenance is performing timely upgrades at all levels of the software stack running your Lux L1. We hope this tutorial will give you enough information and context to allow you to do those upgrades with confidence and ease. If you have additional questions or any issues, please reach out to us on [Discord](https://chat.avalabs.org/).


# Precompile Upgrades (/docs/lux-l1s/upgrade/precompile-upgrades)

---
title: Precompile Upgrades
description: Learn how to enable, disable, and configure precompiles in your Subnet-EVM.
---

# Precompile Upgrades

<Callout type="warn">
Performing a network upgrade requires coordinating the upgrade network-wide. A network upgrade changes the rule set used to process and verify blocks, such that any node that upgrades incorrectly or fails to upgrade by the time that upgrade goes into effect may become out of sync with the rest of the network.

Any mistakes in configuring network upgrades or coordinating them on validators may cause the network to halt and recovering may be difficult.
</Callout>

Subnet-EVM precompiles can be individually enabled or disabled at a given timestamp as a network upgrade. When disabling a precompile, it disables calling the precompile and destructs its storage, allowing it to be enabled later with a new configuration if desired.

## Configuration File

These upgrades must be specified in a file named `upgrade.json` placed in the same directory where `config.json` resides: `{chain-config-dir}/{blockchainID}/upgrade.json`. For example, `WAGMI Subnet` upgrade should be placed in `~/.luxgo/configs/chains/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/upgrade.json`.

The content of the `upgrade.json` should be formatted according to the following:

```json
{
  "precompileUpgrades": [
    {
      "[PRECOMPILE_NAME]": {
        "blockTimestamp": "[ACTIVATION_TIMESTAMP]", // unix timestamp precompile should activate at
        "[PARAMETER]": "[VALUE]" // precompile specific configuration options, eg. "adminAddresses"
      }
    }
  ]
}
```

<Callout type="warn">
An invalid `blockTimestamp` in an upgrade file results the update failing. The `blockTimestamp` value should be set to a valid Unix timestamp value which is in the _future_ relative to the _head of the chain_. If the node encounters a `blockTimestamp` which is in the past, it will fail on startup.
</Callout>

## Disabling Precompiles

To disable a precompile, use the following format:

```json
{
  "precompileUpgrades": [
    {
      "<precompileName>": {
        "blockTimestamp": "[DEACTIVATION_TIMESTAMP]", // unix timestamp the precompile should deactivate at
        "disable": true
      }
    }
  ]
}
```

Each item in `precompileUpgrades` must specify exactly one precompile to enable or disable and the block timestamps must be in increasing order. Once an upgrade has been activated (a block after the specified timestamp has been accepted), it must always be present in `upgrade.json` exactly as it was configured at the time of activation (otherwise the node will refuse to start).

<Callout type="warn">
For safety, you should always treat `precompileUpgrades` as append-only.

As a last resort measure, it is possible to abort or reconfigure a precompile upgrade that has not been activated since the chain is still processing blocks using the prior rule set.
</Callout>

If aborting an upgrade becomes necessary, you can remove the precompile upgrade from `upgrade.json` from the end of the list of upgrades. As long as the blockchain has not accepted a block with a timestamp past that upgrade's timestamp, it will abort the upgrade for that node.

## Example Configuration

Here's a complete example that demonstrates enabling and disabling precompiles:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "txAllowListConfig": {
        "blockTimestamp": 1668960000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668970000,
        "disable": true
      }
    }
  ]
}
```

This example:
1. Enables the `feeManagerConfig` at timestamp `1668950000`
2. Enables `txAllowListConfig` at timestamp `1668960000`
3. Disables `feeManagerConfig` at timestamp `1668970000`

## Initial Precompile Configurations

Precompiles can be managed by privileged addresses to change their configurations and activate their effects. For example, the `feeManagerConfig` precompile can have `adminAddresses` which can change the fee structure of the network:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    }
  ]
}
```

In this example, only the specified address can change the network's fee structure. The admin must call the precompile to activate changes by sending a transaction with a new fee config.

### Initial Configurations Without Admin

Precompiles can also activate their effect immediately at the activation timestamp without admin addresses. For example:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "initialFeeConfig": {
          "gasLimit": 20000000,
          "targetBlockRate": 2,
          "minBaseFee": 1000000000,
          "targetGas": 100000000,
          "baseFeeChangeDenominator": 48,
          "minBlockGasCost": 0,
          "maxBlockGasCost": 10000000,
          "blockGasCostStep": 500000
        }
      }
    }
  ]
}
```

<Callout title="Note">
It's still possible to add `adminAddresses` or `enabledAddresses` along with these initial configurations. In this case, the precompile will be activated with the initial configuration, and admin/enabled addresses can access to the precompiled contract normally.
</Callout>

<Callout title="Note">
If you want to change the precompile initial configuration, you will need to first disable it then activate the precompile again with the new configuration.
</Callout>

## Verifying Upgrades

After creating or modifying `upgrade.json`, restart your node to load the changes. The node will print the chain configuration on startup, allowing you to verify the upgrade configuration:

```bash
INFO [08-15|15:09:36.772] <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain>
github.com/luxfi/subnet-evm/eth/backend.go:155: Initialised chain configuration
config="{ChainID: 11111 Homestead: 0 EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0
Constantinople: 0 Petersburg: 0 Istanbul: 0, Muir Glacier: 0, Subnet EVM: 0, FeeConfig:
{\"gasLimit\":20000000,\"targetBlockRate\":2,\"minBaseFee\":1000000000,\"targetGas\
":100000000,\"baseFeeChangeDenominator\":48,\"minBlockGasCost\":0,\"maxBlockGasCost\
":10000000,\"blockGasCostStep\":500000}, AllowFeeRecipients: false, NetworkUpgrades: {\
"subnetEVMTimestamp\":0}, PrecompileUpgrade: {}, UpgradeConfig: {\"precompileUpgrades\":[{\"feeManagerConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668950000}},{\"txAllowListConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668960000}},{\"feeManagerConfig\":{\"adminAddresses\":null,\"enabledAddresses\":null,\"blockTimestamp\":1668970000,\"disable\":true}}]}, Engine: Dummy Consensus Engine}"
```

You can also verify precompile configurations using:
- [`eth_getActiveRulesAt`](/docs/rpcs/subnet-evm#eth_getactiverulesat) RPC method to check activated precompiles at a timestamp
- [`eth_getChainConfig`](/docs/rpcs/subnet-evm#eth_getchainconfig) RPC method to view the complete configuration including upgrades 


# Installing Your VM (/docs/lux-l1s/rust-vms/installing-vm)

---
title: Installing Your VM
description: Learn how to install your VM on your node.
---

LuxGo searches for and registers VM plugins under the `plugins` [directory](/docs/nodes/configure/configs-flags#--plugin-dir-string).

To install the virtual machine onto your node, you need to move the built virtual machine binary under this directory. Virtual machine executable names must be either a full virtual machine ID (encoded in CB58), or a VM alias.

Copy the binary into the plugins directory.

```bash
cp -n <path to your binary> $GOPATH/src/github.com/luxfi/luxgo/build/plugins/
```

## Node Is Not Running

If your node isn't running yet, you can install all virtual machines under your `plugin` directory by starting the node.

## Node Is Already Running

Load the binary with the `loadVMs` API.

```bash
curl -sX POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.loadVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

Confirm the response of `loadVMs` contains the newly installed virtual machine `tGas3T58KzdjcJ32c6GpePhtqo9rrHJ1oR9wFBtCcMgaosthX`. You'll see this virtual machine as well as any others that weren't already installed previously in the response.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "newVMs": {
      "tGas3T58KzdjcJ32c6GpePhtqo9rrHJ1oR9wFBtCcMgaosthX": [
        "timestampvm-rs",
        "timestamp-rs"
      ],
      "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ": []
    }
  },
  "id": 1
}
```

Now, this VM's static API can be accessed at endpoints `/ext/vm/timestampvm-rs` and `/ext/vm/timestamp-rs`. For more details about VM configs, see [here](/docs/nodes/configure/configs-flags#virtual-machine-vm-configs).

In this tutorial, we used the VM's ID as the executable name to simplify the process. However, LuxGo would also accept `timestampvm-rs` or `timestamp-rs` since those are registered aliases in previous step.

# Introduction to Lux-RS (/docs/lux-l1s/rust-vms/intro-avalanche-rs)

---
title: Introduction to Lux-RS
description: Learn how to write a simple virtual machine in Rust using Lux-RS.
---

Since Rust is a language which we can write and implement Proto interfaces, this implies that we can also use Rust to write VMs which can then be deployed on Lux.

However, rather than build Rust-based from the ground-up, we can utilize Lux-RS, a developer toolkit comprised of powerful building blocks and primitive types which allow us to focus exclusively on the business logic of our VM rather than working on low-level logic.

## Structure of Lux-RS

Although Lux-RS is currently primarily used to build Rust-based VMs, Lux-RS actually consists of three different frameworks; as per the [GitHub](https://github.com/luxfi/lux-rs) description of the Lux-RS repository, the three frameworks are as follows:

- Core: framework for core networking components for a P2P Lux node
- Lux-Consensus: a Rust implementation of the novel Lux consensus protocol
- Lux-Types: implements foundational types used in Lux and provides an SDK for building Rust-based VMs

As the above might make it obvious, the Lux-Types crate is the main framework that one would use to build Rust-based VMs.

## Documentation

For the most up-to-date information regarding the Avalache-Types library, please refer to the associated [crates.io](https://crates.io/crates/lux-types) page for the Lux-Types crate.

# Setting Up Your Environment (/docs/lux-l1s/rust-vms/setting-up-environment)

---
title: Setting Up Your Environment
description: Learn how to set up your environment to build a Rust VM.
---

In this section, we will focus on getting set up with the Rust environment necessary to build with the `lux-types` crates (recall that `lux-types` contains the SDK we want to use to build our Rust VM).

## Installing Rust

First and foremost, we will need to have Rust installed locally. If you do not have Rust installed, you can install `rustup` (the tool that manages your Rust installation) [here](https://www.rust-lang.org/tools/install).

## Adding `lux-types` to Your Project

Once you have Rust installed and are ready to build, you will want to add the Lux-Types crate to your project. Below is a baseline example of how you can do this:

```toml title="Cargo.toml"
[dependencies]
lux-types = "0.1.4"
```

However, if you want to use the [TimestampVM](https://github.com/luxfi/timestampvm-rs) as a reference for your project, a more appropriate import would be the following:

```toml title="Cargo.toml"
[dependencies]
lux-types = { version = "0.1.4", features = ["subnet", "codec_base64"] } 
```


# APIs (/docs/lux-l1s/timestamp-vm/apis)

---
title: APIs
description: Learn how to interact with TimestampVM.
---

Throughout this case study, we have been focusing of the functionality of the TimestampVM. However, one thing we haven't discussed is how external users can interact with an instance of TimestampVM.

Without a way for users to interact with TimestampVM, the blockchain itself will be stagnant. In this section, we will go over the two types of APIs used in TimestampVM:

- Static APIs
- Chain APIs

## Precursor: Static and Instance Methods

When understanding the static and chain APIs used in TimestampVM, a good way to think about these APIs is to compare them to static and instance methods in object-oriented programming. That is,

- **Static Methods**: functions which belong to the class itself, and not any instance of the class
- **Instance Methods**: functions which belong to the instance of a class

## Static APIs

We can think of the static APIs in TimestampVM as functions which call the VM and are not associated with any specific instance of the TimestampVM. Within TimestampVM, we have just one static API function - the ping function:

```rust title="timestampvm/src/api/static_handlers.rs"
/// Defines static handler RPCs for this VM.
#[rpc]
pub trait Rpc {
    #[rpc(name = "ping", alias("timestampvm.ping"))]
    fn ping(&self) -> BoxFuture<Result<crate::api::PingResponse>>;
}
```

## Chain APIs

In contrast to the static API, the chain API of TimestampVM is much more rich in the sense that we have functions with read from and write to an instance of TimestampVM. In this case, we have four functions defined in the chain API:

- `ping`: when called, this function pings an instance of TimestampVM
- `propose_Block`: write function which passes a block to TimestampVM for consideration to be appended to 	the blockchain
- `last_accepted`: read function which returns 	the last accepted block (that is, 	the block at 	the tip	of 	the blockchain)
- `get_block`: read	function	which fetches		the requested	block	

We can see 	the functions included in the chain API here:

```rust title="timestampvm/src/api/chain_handlers.rs"
/// Defines RPCs specific to the chain.
#[rpc]
pub	trait	Rpc {
    /// Pings		th	e VM.
    #[rpc(name = "ping", alias("timestampvm.ping"))]
	fn	ping(&self) -> BoxFuture<Result<PingResponse>>;

    /// Proposes th	e arbitrary data.
    #[rpc(name = "proposeBlock", alias("timestampvm.proposeBlock"))]
	fn	propose_block(&self,args:ProposeBlockArgs)->BoxFuture<Result<ProposeBlockResponse>>;

   /// Fetches th	e last accepted	block.
   #[rpc(name="lastAccepted",alias("timestampvm.lastAccepted"))] 
   fn	last_accepted(&self)->BoxFuture<Result<LastAcceptedResponse>>;

   /// Fetches th	e block.
   #[rpc(name="getBlock",alias("timestampvm.getBlock"))] 
   fn	get_block(&self,args:GetBlockArgs)->BoxFutur e <Result<GetBl ock Response>>;
}
```

# Blocks (/docs/lux-l1s/timestamp-vm/blocks)

---
title: Blocks
descscription: Learn about the Block data structure in TimestampVM.
---

In this section, we will examine the Block data structure. In contrast to the design choice of the TimestampVM state (which was mostly in control of the implementers), blocks in TimestampVM must adhere to the ChainVM Block Interface.

## ChainVM.Block Interface

TimestampVM is designed to be used in tandem with the chain consensus engine. In particular, this relationship is defined by the usage of blocks - TimestampVM will produce blocks which the chain consensus engine will use and eventually mark as accepted or rejected. Therefore, the chain consensus engine requires for all blocks to have the following interface:

```go
type Block interface {
	choices.Decidable

	// Parent returns the ID of this block's parent.
	Parent() ids.ID

	// Verify that the state transition this block would make if accepted is
	// valid. If the state transition is invalid, a non-nil error should be
	// returned.
	//
	// It is guaranteed that the Parent has been successfully verified.
	//
	// If nil is returned, it is guaranteed that either Accept or Reject will be
	// called on this block, unless the VM is shut down.
	Verify(context.Context) error

	// Bytes returns the binary representation of this block.
	//
	// This is used for sending blocks to peers. The bytes should be able to be
	// parsed into the same block on another node.
	Bytes() []byte

	// Height returns the height of this block in the chain.
	Height() uint64

	// Time this block was proposed at. This value should be consistent across
	// all nodes. If this block hasn't been successfully verified, any value can
	// be returned. If this block is the last accepted block, the timestamp must
	// be returned correctly. Otherwise, accepted blocks can return any value.
	Timestamp() time.Time
}
```

## Implementing the Block Data Structure

With the above in mind, we now examine the block data structure:

```rust
/// Represents a block, specific to `Vm` (crate::vm::Vm).
#[serde_as]
#[derive(Serialize, Deserialize, Clone, Derivative, Default)]
#[derivative(Debug, PartialEq, Eq)]
pub struct Block {
    /// The block Id of the parent block.
    parent_id: ids::Id,
    /// This block's height.
    /// The height of the genesis block is 0.
    height: u64,
    /// Unix second when this block was proposed.
    timestamp: u64,
    /// Arbitrary data.
    #[serde_as(as = "Hex0xBytes")]
    data: Vec<u8>,

    /// Current block status.
    #[serde(skip)]
    status: choices::status::Status,
    /// This block's encoded bytes.
    #[serde(skip)]
    bytes: Vec<u8>,
    /// Generated block Id.
    #[serde(skip)]
    id: ids::Id,

    /// Reference to the Vm state manager for blocks.
    #[derivative(Debug = "ignore", PartialEq = "ignore")]
    #[serde(skip)]
    state: state::State,
}
```

Notice above that many of the fields of the `Block` struct store the information required to implement the `block.Block` interface we saw previously. Tying the concept of Blocks back to the VM State, notice the last field `state` within the `Block` struct. This is where the `Block` struct stores a copy of the `State` struct from the previous section (and since each field of the `State` struct is wrapped in an `Arc` pointer, this implies that `Block` is really just storing a reference to both the `db` and `verified_blocks` data structures).

## `Block` Functions

In this section, we examine some of the functions associated with the `Block` struct:

### `verify`

This function verifies that a block is valid and stores it in memory. Note that a verified block does not mean that it has been accepted - rather, a verified block is eligible to be accepted.

```rust
/// Verifies [`Block`](Block) properties (e.g., heights),
/// and once verified, records it to the `State` (crate::state::State).
/// # Errors
/// Can fail if the parent block can't be retrieved.
pub async fn verify(&mut self) -> io::Result<()> {
    if self.height == 0 && self.parent_id == ids::Id::empty() {
        log::debug!(
            "block {} has an empty parent Id since it's a genesis block -- skipping verify",
            self.id
        );
        self.state.add_verified(&self.clone()).await;
        return Ok(());
    }

    // if already exists in database, it means it's already accepted
    // thus no need to verify once more
    if self.state.get_block(&self.id).await.is_ok() {
        log::debug!("block {} already verified", self.id);
        return Ok(());
    }

    let prnt_blk = self.state.get_block(&self.parent_id).await?;

    // ensure the height of the block is immediately following its parent
    if prnt_blk.height != self.height - 1 {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!(
                "parent block height {} != current block height {} - 1",
                prnt_blk.height, self.height
            ),
        ));
    }

    // ensure block timestamp is after its parent
    if prnt_blk.timestamp > self.timestamp {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!(
                "parent block timestamp {} > current block timestamp {}",
                prnt_blk.timestamp, self.timestamp
            ),
        ));
    }

    let one_hour_from_now = Utc::now() + Duration::hours(1);
    let one_hour_from_now = one_hour_from_now
        .timestamp()
        .try_into()
        .expect("failed to convert timestamp from i64 to u64");

    // ensure block timestamp is no more than an hour ahead of this nodes time
    if self.timestamp >= one_hour_from_now {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!(
                "block timestamp {} is more than 1 hour ahead of local time",
                self.timestamp
            ),
        ));
    }

    // add newly verified block to memory
    self.state.add_verified(&self.clone()).await;
    Ok(())
}
```

### `reject`

When called by the chain consensus engine, this tells the VM that the particular block has been rejected.

```rust
/// Mark this [`Block`](Block) rejected and updates `State` (crate::state::State) accordingly.
/// # Errors
/// Returns an error if the state can't be updated.
pub async fn reject(&mut self) -> io::Result<()> {
    self.set_status(choices::status::Status::Rejected);

    // only decided blocks are persistent -- no reorg
    self.state.write_block(&self.clone()).await?;

    self.state.remove_verified(&self.id()).await;
    Ok(())
}
```

### `accept`

When called by the chain consensus engine, this tells the VM that the particular block has been rejected.

```rust
/// Mark this [`Block`](Block) accepted and updates `State` (crate::state::State) accordingly.
/// # Errors
/// Returns an error if the state can't be updated.
pub async fn accept(&mut self) -> io::Result<()> {
    self.set_status(choices::status::Status::Accepted);

    // only decided blocks are persistent -- no reorg
    self.state.write_block(&self.clone()).await?;
    self.state.set_last_accepted_block(&self.id()).await?;

    self.state.remove_verified(&self.id()).await;
    Ok(())
}
```


# Architecture of TimestampVM (/docs/lux-l1s/timestamp-vm/defining-vm-itself)

---
title: Architecture of TimestampVM
description: After examining several of the data structures and functionalities that TimestampVM relies on, it is time that we examine the architecture of the TimestampVM itself. In addition, we will look at some data structures that TimestampVM utilizes.
---

## Aside: ChainVM

In addition to blocks having to adhere to the `block.Block` interface, VMs which interact with the chain consensus engine must also implement the `ChainVM` interface. In the context of a Rust-based VM, this means that we must satisfy the `ChainVM` trait in `lux-types`:

```rust title="lux-types/src/subnet/rpc/chain/block.rs"
/// ref. <https://pkg.go.dev/github.com/luxfi/luxgo/snow/engine/chain/block#ChainVm>
#[tonic::async_trait]
pub trait ChainVm: CommonVm + BatchedChainVm + Getter + Parser {
    type Block: block::Block;

    /// Attempt to create a new block from ChainVm data
    /// Returns either a block or an error
    async fn build_block(&self) -> Result<<Self as ChainVm>::Block>;

    /// Issues a transaction to the chain
    async fn issue_tx(&self) -> Result<<Self as ChainVm>::Block>;

    /// Notify the Vm of the currently preferred block.
    async fn set_preference(&self, id: Id) -> Result<()>;

    /// Returns ID of last accepted block.
    async fn last_accepted(&self) -> Result<Id>;

}
```

## Defining TimestampVM

Below is definition of VM struct which represents TimestampVM:

```rust title="timestampvm/src/vm/mod.rs"
pub struct Vm<A> {
   /// Maintains Vm-specific states.
   pub state: Arc<RwLock<State>>,

   pub app_sender: Option<A>,

   /// A queue not yet proposed into a block.
   pub mempool: Arc<RwLock<VecDeque<Vec<u8>>>>,
}
```

We see following three fields:

- `state`: represents state of VM. Note different than earlier seen State structure.
- `app_sender`: channel for receiving and sending requests by our VM
- `mempool`: where proposed blocks are kept before being processed.

We now examine the `state` data structure mentioned earlier:

```rust title="timestampvm/src/vm/mod.rs"
/// Represents VM-specific states.
/// Defined separately for interior mutability in [`Vm`](vm).
/// Protected with 'Arc' and 'RwLock'.
pub struct State {
  pub ctx : Option<Context<ValidatorStateClient>>,
  pub version : Version,
  pub genesis : Genesis,

  // Persistent Vm state representation 
  pub state : Option<state::State>,
  
  // Preferred block Id 
  pub preferred : ids::Id,
  
  // Channel for messages to chain consensus engine 
  pub bootstrapped : bool,
}
```

Relationship between State and state - contains alongside other fields relevant to chain consensus algorithm.

# Introduction (/docs/lux-l1s/timestamp-vm/introduction)

---
title: Introduction
description: Learn about the TimestampVM Virtual Machine.
---

To really get an understanding of how one can use the `lux-types` library to build a Rust-based VM, we will look at [TimeStampVM](https://github.com/luxfi/timestampvm-rs/tree/main), a basic VM which utilizes the `lux-types` library.

## Idea of TimestampVM

In contrast to complex VMs like the EVM which provide a general-purpose computing environment, TimestampVM is _much, much_ simpler. In fact, we can describe the goal of TimestampVM in two bullet points:

- To store the timestamp when each block was appended to the blockchain
- To store arbitrary payloads of data (within each block)

Even though the above seems quite simple, this still requires us to define and build out an architecture to support such functionalities. In this case study, we will look at the following pieces of the architecture that define TimestampVM:

- State
- Blocks
- API
- The VM itself

# State (/docs/lux-l1s/timestamp-vm/state)

---
title: State
description: Learn about the state within the context of TimestampVM.
---

Blockchains can be defined as follows:

> A linked-list where each list element consists of a block

Implementations of blockchains, while adhering to the functionality above from a white-box perspective, are defined much more like databases than regular linked lists themselves. In fact, this is what TimestampVM utilizes! By utilizing a general database, TimestampVM is able to store blocks (and thus, store its blockchain) while also being able to store additional data such as pending blocks.

## State Definition

Below is the definition of the `State` struct which is used to maintain the state of the TimestampVM:

```rust
/// Manages block and chain states for this Vm, both in-memory and persistent.
#[derive(Clone)]
pub struct State {
    pub db: Arc<RwLock<Box<dyn subnet::rpc::database::Database + Send + Sync>>>,

    /// Maps block Id to Block.
    /// Each element is verified but not yet accepted/rejected (e.g., preferred).
    pub verified_blocks: Arc<RwLock<HashMap<ids::Id, Block>>>,
}
```

`State` in this context acts like the database of TimestampVM. Within `State`, we are managing two different data structures:

- `db`: a byte-based mapping which maps bytes to bytes. This is where finalized (that is, accepted blocks are stored)
- `verified_blocks`: a hashmap which maps block numbers to their respective blocks. This is where all verified, but pending blocks are stored

While one could have guessed the functionalities of `db` and `verified_blocks` from their respective types `subnet::rpc::database::Database + Send + Sync` and `HashMap<ids::Id, Block>`, it is not immediately clear why we are wrapping these fields with Read/Write locks and Arc pointers. However, as we'll see soon when we examine the Block data structure, blocks need access to the VM state so they can add themselves to state. This is due to the `SetPrefernce` function of ChainVM interface, which states:

> `Set Preference`
> 
> The VM implements the function SetPreference(blkID ids.ID) to allow the consensus engine to notify the VM which block is currently preferred to be accepted. The VM should use this information to set the head of its blockchain. Most importantly, when the consensus engine calls BuildBlock, the VM should be sure to build on top of the block that is the most recently set preference.
> 
> Note: SetPreference will always be called with a block that has no verified children.

Therefore, when building a Rust-based VM (or a VM in any supported language), the VM itself is only responsible for tracking the ID of the most recent finalized block; blocks bear the responsibility of storing themselves in VM state. As a result, we will need to wrap the `db` and `verified_blocks` fields with the following:

- An `Arc` pointer so that whenever we clone the `State` structure, the cloned versions of `db` and `verified_blocks` are still pointing to the same data structures in memory. This allows for multiple Blocks to share the same `db` and `verified_blocks`
- A read/write lock (that is, `RwLock`) so that we safely utilize concurrency in our VM

## `State` Functions

Below are the functions associated with the `State` struct:

```rust title="timestampvm/src/state/mod.rs"
impl State {
    /// Persists the last accepted block Id to state.
    /// # Errors
    /// Fails if the db can't be updated
    pub async fn set_last_accepted_block(&self, blk_id: &ids::Id) -> io::Result<()> {
        let mut db = self.db.write().await;
        db.put(LAST_ACCEPTED_BLOCK_KEY, &blk_id.to_vec())
            .await
            .map_err(|e| {
                Error::new(
                    ErrorKind::Other,
                    format!("failed to put last accepted block: {e:?}"),
                )
            })
    }

    /// Returns "true" if there's a last accepted block found.
    /// # Errors
    /// Fails if the db can't be read
    pub async fn has_last_accepted_block(&self) -> io::Result<bool> {
        let db = self.db.read().await;
        match db.has(LAST_ACCEPTED_BLOCK_KEY).await {
            Ok(found) => Ok(found),
            Err(e) => Err(Error::new(
                ErrorKind::Other,
                format!("failed to load last accepted block: {e}"),
            )),
        }
    }

    /// Returns the last accepted block Id from state.
    /// # Errors
    /// Can fail if the db can't be read
    pub async fn get_last_accepted_block_id(&self) -> io::Result<ids::Id> {
        let db = self.db.read().await;
        match db.get(LAST_ACCEPTED_BLOCK_KEY).await {
            Ok(d) => Ok(ids::Id::from_slice(&d)),
            Err(e) => {
                if subnet::rpc::errors::is_not_found(&e) {
                    return Ok(ids::Id::empty());
                }
                Err(e)
            }
        }
    }

    /// Adds a block to "`verified_blocks`".
    pub async fn add_verified(&mut self, block: &Block) {
        let blk_id = block.id();
        log::info!("verified added {blk_id}");

        let mut verified_blocks = self.verified_blocks.write().await;
        verified_blocks.insert(blk_id, block.clone());
    }

    /// Removes a block from "`verified_blocks`".
    pub async fn remove_verified(&mut self, blk_id: &ids::Id) {
        let mut verified_blocks = self.verified_blocks.write().await;
        verified_blocks.remove(blk_id);
    }

    /// Returns "true" if the block Id has been already verified.
    pub async fn has_verified(&self, blk_id: &ids::Id) -> bool {
        let verified_blocks = self.verified_blocks.read().await;
        verified_blocks.contains_key(blk_id)
    }

    /// Writes a block to the state storage.
    /// # Errors
    /// Can fail if the block fails to serialize or if the db can't be updated
    pub async fn write_block(&mut self, block: &Block) -> io::Result<()> {
        let blk_id = block.id();
        let blk_bytes = block.to_vec()?;

        let mut db = self.db.write().await;

        let blk_status = BlockWithStatus {
            block_bytes: blk_bytes,
            status: block.status(),
        };
        let blk_status_bytes = blk_status.encode()?;

        db.put(&block_with_status_key(&blk_id), &blk_status_bytes)
            .await
            .map_err(|e| Error::new(ErrorKind::Other, format!("failed to put block: {e:?}")))
    }

    /// Reads a block from the state storage using the `block_with_status_key`.
    /// # Errors
    /// Can fail if the block is not found in the state storage, or if the block fails to deserialize
    pub async fn get_block(&self, blk_id: &ids::Id) -> io::Result<Block> {
        // check if the block exists in memory as previously verified.
        let verified_blocks = self.verified_blocks.read().await;
        if let Some(b) = verified_blocks.get(blk_id) {
            return Ok(b.clone());
        }

        let db = self.db.read().await;

        let blk_status_bytes = db.get(&block_with_status_key(blk_id)).await?;
        let blk_status = BlockWithStatus::from_slice(blk_status_bytes)?;

        let mut blk = Block::from_slice(&blk_status.block_bytes)?;
        blk.set_status(blk_status.status);

        Ok(blk)
    }
}
```

The functions above are called will be called by both blocks and the VM itself.

# Consensus Protocols (/docs/nodes/architecture/consensus)

---
title: Consensus Protocols
description: Deep dive into Lux's Snow* family of consensus protocols including Snowball, Snowman, and Lux consensus.
---

Lux uses a novel family of consensus protocols collectively known as the **Snow* protocols**. These protocols achieve consensus through repeated random sampling, providing probabilistic safety guarantees with sub-second finality.

## Consensus Overview

Traditional consensus protocols (like PBFT) require all-to-all communication, limiting scalability. Lux's approach is fundamentally different:

| Property | Traditional (PBFT) | Lux Snow* |
|----------|-------------------|-----------------|
| **Communication** | All-to-all (O(n²)) | Random sampling (O(k log n)) |
| **Finality** | Deterministic | Probabilistic (tunable) |
| **Scalability** | ~100 nodes | Thousands of nodes |
| **Latency** | Seconds | Sub-second |

<Callout type="info">
The Snow* protocols are named after their "snowball" effect - once a preference starts forming, it quickly luxs to a decision.
</Callout>

## The Snow* Protocol Family

### Snowball: Binary Consensus

Snowball is the foundational protocol for deciding between two conflicting options:

<Mermaid chart={`
sequenceDiagram
    participant V as Validator
    participant S1 as Sample 1
    participant S2 as Sample 2
    participant S3 as Sample 3

    Note over V: Has preference for option A

    V->>S1: Query preference?
    V->>S2: Query preference?
    V->>S3: Query preference?

    S1-->>V: A
    S2-->>V: A
    S3-->>V: B

    Note over V: Supermajority 2/3 for A
    Note over V: Increment confidence for A

    loop Until confidence threshold
        V->>S1: Query preference?
        Note over V: Continue sampling
    end

    Note over V: Decision Accept A
`} />

**Key Parameters:**
- **k (sample size)**: Number of validators to query (default `20`)
- **αₚ (preference threshold)**: Votes needed to switch preference (default `15`)
- **α꜀ (confidence threshold)**: Votes needed to increase confidence (default `15`)
- **β (finalization threshold)**: Consecutive successful rounds (default `20`)
- **Concurrent polls**: Parallel polls while processing (default `4`)
- **Optimal processing**: Soft cap on in-flight items (default `10`)

### Snowman: Linear Chain Consensus

Snowman extends Snowball to decide on a linear sequence of blocks. It's used by:
- **Platform-Chain** (Platform Chain)
- **LUExchange-Chain** (Contract Chain)
- **Exchange-Chain** (Exchange Chain) - linearized in the Cortina upgrade (April 2023)
- **Most Lux L1s**

[View source on GitHub](https://github.com/luxfi/luxgo/blob/master/snow/consensus/snowman/consensus.go)

```go title="snow/consensus/snowman/consensus.go"
type Consensus interface {
    // Initialize with last accepted block
    Initialize(
        ctx *snow.ConsensusContext,
        params snowball.Parameters,
        lastAcceptedID ids.ID,
        lastAcceptedHeight uint64,
        lastAcceptedTime time.Time,
    ) error

    // Tracking & liveness
    NumProcessing() int
    Processing(ids.ID) bool
    IsPreferred(ids.ID) bool

    // Add a new block to consensus
    Add(Block) error

    // Get the preferred blocks
    Preference() ids.ID
    PreferenceAtHeight(height uint64) (ids.ID, bool)

    // Get the last accepted block
    LastAccepted() (ids.ID, uint64)

    // Record poll results from network sampling
    RecordPoll(context.Context, bag.Bag[ids.ID]) error

    // Lightweight ancestry lookup
    GetParent(id ids.ID) (ids.ID, bool)
}
```

**Block Lifecycle in Snowman:**

<Mermaid chart={`
stateDiagram-v2
    [*] --> Processing: ParseBlock
    Processing --> Processing: Verify
    Processing --> Accepted: Accept
    Processing --> Rejected: Reject
    Accepted --> [*]
    Rejected --> [*]
`} />

### Lux DAG Consensus (Historical)

<Callout type="warning">
The Lux DAG consensus engine is **no longer used on the Primary Network**. The Exchange-Chain was linearized in the **Cortina upgrade** (April 2023 on Mainnet) and now uses Snowman consensus. The DAG engine code remains in the codebase for historical compatibility only.
</Callout>

Historically, Lux consensus operated on a Directed Acyclic Graph (DAG) of transactions, where non-conflicting transactions could be processed in parallel:

```
       ┌───┐
       │ G │  Genesis
       └─┬─┘
      ┌──┴──┐
    ┌─┴─┐ ┌─┴─┐
    │ A │ │ B │  Vertices could have
    └─┬─┘ └─┬─┘  multiple parents
      │  ╲╱  │
      │  ╱╲  │
    ┌─┴─┐ ┌─┴─┐
    │ C │ │ D │
    └───┘ └───┘
```

The linearization was implemented via the `LinearizableVMWithEngine` interface, which allows a DAG-based VM to transition to linear block production after a designated "stop vertex."

## Consensus Engine Architecture

The consensus engine sits between the VM and the network:

<Mermaid chart={`
graph LR
    subgraph Consensus_Engine["Consensus Engine"]
        B[Bootstrapper]
        E[Engine]
        S[Sender]
    end

    VM[Virtual Machine] <--> E
    E <--> S
    S <--> Network
    B --> E
`} />

### Engine States

The consensus engine progresses through several states ([`snow/state.go`](https://github.com/luxfi/luxgo/blob/master/snow/state.go)):

```go
type State uint8

const (
    Initializing State = iota  // 0
    StateSyncing               // 1
    Bootstrapping              // 2
    NormalOp                   // 3
)
```

| State | Description |
|-------|-------------|
| **Initializing** | Initial setup before sync begins |
| **StateSyncing** | Fast catch-up using state summaries |
| **Bootstrapping** | Catching up with network state via block replay |
| **NormalOp** | Participating in consensus |

### The Snowman Engine

[View source on GitHub](https://github.com/luxfi/luxgo/blob/master/snow/engine/snowman/engine.go)

```go title="snow/engine/snowman/engine.go"
type Engine struct {
    Config

    // Consensus instance
    Consensus smcon.Consensus

    // VM interface
    VM block.ChainVM

    // Network communication
    Sender common.Sender

    // Block management
    pending   map[ids.ID]block.Block
    blocked   map[ids.ID][]block.Block
}
```

**Engine Responsibilities:**
1. **Block fetching**: Request missing blocks from peers
2. **Block verification**: Validate blocks via the VM
3. **Consensus voting**: Query peers and record votes
4. **Block finalization**: Accept or reject blocks based on consensus

## Block Processing Flow

### 1. Receiving a Block

```go
func (e *Engine) Put(ctx context.Context, nodeID ids.NodeID, requestID uint32, blkBytes []byte) error {
    // Parse the block
    blk, err := e.VM.ParseBlock(ctx, blkBytes)

    // Verify ancestry exists
    if !e.hasAncestry(blk) {
        // Request missing ancestors
        e.requestAncestors(blk.Parent())
        return nil
    }

    // Issue to consensus
    return e.issue(ctx, blk)
}
```

### 2. Issuing to Consensus

```go
func (e *Engine) issue(ctx context.Context, blk block.Block) error {
    // Verify the block
    if err := blk.Verify(ctx); err != nil {
        return err
    }

    // Add to consensus
    if err := e.Consensus.Add(blk); err != nil {
        return err
    }

    // Start voting
    e.sendQuery(ctx, blk.ID())
    return nil
}
```

### 3. Recording Votes

```go
func (e *Engine) Chits(ctx context.Context, nodeID ids.NodeID, requestID uint32, preferredID ids.ID, ...) error {
    // Collect votes in a bag
    votes := bag.Of(preferredID)

    // When enough votes collected, record the poll
    if e.polls.Finished() {
        return e.Consensus.RecordPoll(ctx, e.polls.Result())
    }
    return nil
}
```

## Snowman++ (ProposerVM)

Snowman++ adds **soft proposer windows** on top of Snowman to pace block production. It is implemented by wrapping a ChainVM in the [ProposerVM](https://github.com/luxfi/luxgo/tree/master/vms/proposervm) and is enabled on the Platform-Chain and LUExchange-Chain.

```go title="vms/proposervm/vm.go"
// ProposerVM wraps a ChainVM to add proposer selection
type VM struct {
    inner block.ChainVM

    // Proposer selection
    windower Windower
}
```

**How it works:**
1. Validators are sampled (by stake) to form a proposer list for the next block.
2. Each proposer gets a 5s window; up to 6 windows are scheduled from the parent timestamp.
3. Within their window, only the designated proposer can build a valid block.
4. After the final window, any validator may propose, which preserves liveness if proposers are offline.

**Benefits:**
- **Predictable pacing**: Prevents multiple validators from racing the same height.
- **Stake-weighted fairness**: Windows are derived from the subnet validator set.
- **Graceful fallback**: Production opens to everyone after the final window.

## Consensus Parameters

Consensus parameters live in [`snow/consensus/snowball/parameters.go`](https://github.com/luxfi/luxgo/blob/master/snow/consensus/snowball/parameters.go):

```go
type Parameters struct {
    // Sample size for each poll
    K int `json:"k"`

    // Switch preference threshold
    AlphaPreference int `json:"alphaPreference"`

    // Increase confidence threshold
    AlphaConfidence int `json:"alphaConfidence"`

    // Finalization threshold
    Beta int `json:"beta"`

    // Concurrent polls
    ConcurrentRepolls int `json:"concurrentRepolls"`

    // Congestion control
    OptimalProcessing     int `json:"optimalProcessing"`
    MaxOutstandingItems   int `json:"maxOutstandingItems"`
    MaxItemProcessingTime time.Duration `json:"maxItemProcessingTime"`
}
```

| Parameter | Default | Description |
|-----------|---------|-------------|
| **K** | 20 | Validators sampled per round |
| **AlphaPreference** | 15 | Votes needed to change preference |
| **AlphaConfidence** | 15 | Votes needed to increase confidence |
| **Beta** | 20 | Consecutive successful polls to finalize |
| **ConcurrentRepolls** | 4 | Parallel polls while processing |
| **OptimalProcessing** | 10 | Soft target for in-flight vertices/blocks |
| **MaxOutstandingItems** | 256 | Health threshold for queued items |
| **MaxItemProcessingTime** | 30s | Health threshold for a single item |

<Callout type="warning">
These parameters are network-wide and cannot be changed for individual nodes. Modifying them would cause consensus failures.
</Callout>

## Security Properties

### Probabilistic Safety

The probability of a safety violation (accepting conflicting blocks) is:

$$P(\text{safety violation}) < \left(1 - \frac{\alpha_{confidence}}{k}\right)^\beta$$

With default parameters: $P < \left(1 - \frac{15}{20}\right)^{20} \approx 10^{-12}$

### Liveness

Lux guarantees liveness as long as:
- More than `α/k` (75%) of stake is honest
- Network is eventually synchronous

## Next Steps

<Cards>
  <Card title="Virtual Machines" href="/docs/nodes/architecture/virtual-machines">
    Learn how VMs implement block building and verification
  </Card>
  <Card title="Networking" href="/docs/nodes/architecture/networking">
    Understand how consensus messages are transmitted
  </Card>
</Cards>


# Core Components (/docs/nodes/architecture/core-components)

---
title: Core Components
description: Deep dive into LuxGo's package structure, startup flow, and how components interact.
---

This page provides a detailed overview of LuxGo's internal architecture, including the main packages, startup sequence, and how components communicate.

## Package Structure

LuxGo is organized into well-defined packages, each responsible for specific functionality (top-level folders only):

```
luxgo/
├── main/            # CLI entry point
├── app/             # Process lifecycle (signals, shutdown)
├── config/          # Flags/env/config parsing
├── node/            # Node wiring and initialization
├── chains/          # Chain manager and handlers
├── snow/            # Consensus protocols and engines
├── vms/             # Built-in VMs, proposerVM, rpcchainvm
├── network/         # P2P stack
├── message/         # Message codecs
├── database/        # LevelDB/Pebble/memdb backends
├── graft/           # Grafted Coreth (LUExchange-Chain EVM)
├── subnets/         # Subnet configs and validator utilities
├── staking/         # TLS/BLS staking keys and POP
├── upgrade/         # Network upgrade rules
├── trace/           # OpenTelemetry tracing helpers
├── utils/           # Common utilities
└── genesis/         # Genesis configuration and samples
```

## Startup Flow

When you run LuxGo, the following initialization sequence occurs:

<Mermaid chart={`
sequenceDiagram
    participant Main as main.go
    participant Config as Config
    participant App as App
    participant Node as Node

    Main->>Config: Parse flags & config
    Config-->>Main: NodeConfig
    Main->>App: New(nodeConfig)
    App->>Node: Initialize components
    Node->>Node: Init database
    Node->>Node: Init networking
    Node->>Node: Init API server
    Node->>Node: Register VMs
    Node->>Node: Start chain manager
    Main->>App: Run()
    App->>Node: Dispatch (event loop)
`} />

### 1. Configuration Parsing

[View source on GitHub](https://github.com/luxfi/luxgo/blob/master/main/main.go)

```go title="main/main.go"
func main() {
    evm.RegisterAllLibEVMExtras()

    // Build configuration from flags/env/config file
    fs := config.BuildFlagSet()
    v, err := config.BuildViper(fs, os.Args[1:])

    if errors.Is(err, pflag.ErrHelp) {
        os.Exit(0)
    }

    if v.GetBool(config.VersionJSONKey) && v.GetBool(config.VersionKey) {
        fmt.Println("can't print both JSON and human readable versions")
        os.Exit(1)
    }

    if v.GetBool(config.VersionJSONKey) {
        versions := version.GetVersions()
        jsonBytes, err := json.MarshalIndent(versions, "", "  ")
        if err != nil {
            fmt.Printf("couldn't marshal versions: %s\n", err)
            os.Exit(1)
        }
        fmt.Println(string(jsonBytes))
        os.Exit(0)
    }

    if v.GetBool(config.VersionKey) {
        fmt.Println(version.GetVersions().String())
        os.Exit(0)
    }

    nodeConfig, err := config.GetNodeConfig(v)
    if term.IsTerminal(int(os.Stdout.Fd())) {
        fmt.Println(app.Header)
    }

    nodeApp, err := app.New(nodeConfig)
    exitCode := app.Run(nodeApp)
    os.Exit(exitCode)
}
```

The configuration system supports:
- **Command-line flags**: `--network-id=testnet`, `--http-port=9650`
- **Config file**: Pass `--config-file=/path/to/file`. The installer writes `~/.luxgo/configs/node.json`; source builds do not create a default file.
- **Environment variables**: Prefixed with `AVAGO_`

### 2. Node Initialization

The `Node` struct in [`node/node.go`](https://github.com/luxfi/luxgo/blob/master/node/node.go) orchestrates all components:

```go title="node/node.go"
type Node struct {
    Log        logging.Logger
    ID         ids.NodeID
    Config     *node.Config

    // Networking & routing
    Net         network.Network
    chainRouter router.Router
    msgCreator  message.Creator

    // Storage & shared state
    DB           database.Database
    sharedMemory *atomic.Memory

    // VM/chain orchestration
    VMAliaser    ids.Aliaser
    VMManager    vms.Manager
    VMRegistry   registry.VMRegistry
    chainManager chains.Manager

    // APIs and services
    APIServer       server.Server
    health          health.Health
    resourceManager resource.Manager
}
```

### 3. Component Initialization Order

Components are initialized in a specific order to satisfy dependencies:

| Order | Component | Purpose |
|-------|-----------|---------|
| 1 | **Identity & logging** | Staking certs/POP, VM aliases, log factories |
| 2 | **Metrics** | Prometheus registries + `/ext/metrics` |
| 3 | **APIs** | HTTP server + metrics API (health/info/admin added later) |
| 4 | **Database & shared memory** | Open LevelDB/PebbleDB/memdb and atomic memory |
| 5 | **Message codec** | `message.Creator` shared by network/engines |
| 6 | **Validators & resources** | Validator manager, CPU/disk targeters, resource manager |
| 7 | **Networking** | Listener, NAT/port mapping, throttlers, IP updater |
| 8 | **Health & aliases** | Health API, default VM/API/chain aliases |
| 9 | **Chain manager & VM registry** | Chain manager, register PlatformVM/XVM/EVM + plugins |
| 10 | **Indexer & profiler** | Optional index API and continuous profiler |
| 11 | **Chains** | Start PlatformVM, then other chains/bootstrap |

## The Node Struct

The `Node` struct is the central coordinator. Here are its key responsibilities:

### VM Management

```go
// Register built-in VMs
n.VMManager.RegisterFactory(ctx, constants.PlatformVMID, &platformvm.Factory{})
n.VMManager.RegisterFactory(ctx, constants.AVMID, &xvm.Factory{})
n.VMManager.RegisterFactory(ctx, constants.EVMID, &coreth.Factory{})
```

### Chain Creation

When a new chain needs to be created (e.g., during Platform-Chain bootstrap):

```go
type ChainParameters struct {
    ID          ids.ID      // Chain ID
    SubnetID    ids.ID      // Subnet that validates this chain
    GenesisData []byte      // Genesis state
    VMID        ids.ID      // Which VM to run
    FxIDs       []ids.ID    // Feature extensions
    CustomBeacons validators.Manager // Optional: bootstrap peers for Platform-Chain
}
```

### API Registration

Each VM can register its own API endpoints:

```go
// VM implements CreateHandlers
func (vm *VM) CreateHandlers(ctx context.Context) (map[string]http.Handler, error) {
    return map[string]http.Handler{
        "/rpc": vm.rpcHandler,
        "/ws":  vm.wsHandler,
    }, nil
}
```

## Chain Manager

The Chain Manager ([`chains/manager.go`](https://github.com/luxfi/luxgo/blob/master/chains/manager.go)) is responsible for:

1. **Creating chains** when requested by the Platform-Chain
2. **Managing chain lifecycle** (start, stop, restart)
3. **Handling bootstrapping** and state sync
4. **Routing messages** between chains and the network

```go title="chains/manager.go"
type Manager interface {
    // Queue a chain to be created after Platform-Chain bootstraps
    QueueChainCreation(ChainParameters)

    // Check if a chain has finished bootstrapping
    IsBootstrapped(ids.ID) bool

    // Resolve chain aliases
    Lookup(string) (ids.ID, error)

    // Start the chain creation process
    StartChainCreator(platformChain ChainParameters) error
}
```

### Chain Bootstrapping

When a chain starts, it progresses through several states to catch up with the network:

<Mermaid chart={`
stateDiagram-v2
    [*] --> Initializing
    Initializing --> StateSyncing: State sync enabled
    Initializing --> Bootstrapping: State sync disabled
    StateSyncing --> Bootstrapping: State summaries applied
    Bootstrapping --> NormalOp: Bootstrap complete
    NormalOp --> [*]
`} />

## Database Layer

LuxGo supports multiple database backends:

### Database Backends

| Backend | Description |
|---------|-------------|
| **LevelDB** | Default, widely tested |
| **PebbleDB** | Modern alternative, better performance |
| **memdb** | In-memory (non-persistent), useful for fast testing |

### Database Organization

Data is organized using prefix databases:

```go
// Each component gets its own namespace
vmDB := prefixdb.New(VMDBPrefix, db)
chainDB := prefixdb.New(chainID[:], vmDB)
```

This allows:
- **Isolation**: Each VM and chain has isolated storage
- **Metrics**: Per-database metrics via `meterdb`
- **Cleanup**: Easy removal of chain data

## Message Flow

Here's how a transaction flows through the system:

<Mermaid chart={`
sequenceDiagram
    participant Client
    participant API as API Server
    participant VM as Virtual Machine
    participant Engine as Consensus Engine
    participant Network as Network Layer

    Client->>API: Submit transaction
    API->>VM: IssueTx(tx)
    VM->>VM: Validate tx
    VM->>Engine: Notify pending txs
    Engine->>VM: BuildBlock()
    VM-->>Engine: New block
    Engine->>Network: Broadcast block
    Network->>Engine: Receive votes
    Engine->>VM: Accept/Reject block
    VM-->>API: Confirmation
    API-->>Client: Response
`} />

## Health Checks

LuxGo exposes health checks at `/ext/health`:

```go
type Checker interface {
    // HealthCheck returns nil if healthy
    HealthCheck(context.Context) (interface{}, error)
}
```

Components that implement health checks:
- **Network**: Peer connectivity
- **Chains**: Bootstrap status
- **Database**: I/O health
- **Consensus**: Liveness

## Metrics

Prometheus metrics are exposed at `/ext/metrics`:

```go
// Example metrics namespaces
const (
    networkNamespace = "lux_network"
    dbNamespace      = "lux_db"
    consensusNS      = "lux_snowman"
)
```

Key metrics include:
- `lux_network_peers`: Connected peer count
- `lux_db_*`: Database operations
- `lux_snowman_*`: Consensus metrics
- `lux_api_*`: API request metrics

## Next Steps

<Cards>
  <Card title="Consensus Protocols" href="/docs/nodes/architecture/consensus">
    Learn how Snowman and Lux consensus work
  </Card>
  <Card title="Virtual Machines" href="/docs/nodes/architecture/virtual-machines">
    Understand VM architecture and interfaces
  </Card>
</Cards>


# LuxGo Architecture (/docs/nodes/architecture)

---
title: LuxGo Architecture
description: Understand the internal architecture and components of LuxGo, the official Lux node implementation.
---

LuxGo is the official Go implementation of an Lux node. It powers the Primary Network (P/C/X) and any Lux L1s you launch, delivering high throughput and sub-second probabilistic finality.

<Callout>
**Source Code**: [github.com/luxfi/luxgo](https://github.com/luxfi/luxgo)
</Callout>

## What is LuxGo?

LuxGo is a full-node implementation that:

- **Validates transactions** across the Primary Network (Platform-Chain, LUExchange-Chain, Exchange-Chain)
- **Participates in consensus** using Lux's Snow* family of protocols
- **Serves API requests** for wallets, dApps, and other clients
- **Supports Lux L1s** (blockchains validated by Subnets) for custom networks

<Callout type="info">
LuxGo is written in Go and is designed to be modular, allowing developers to build custom Virtual Machines (VMs) that define their own blockchain logic.
</Callout>

## Execution at a glance

- **Networking**: Custom P2P stack with mutual TLS (staking certs), throttling, peer scoring, and chain-aware gossip.
- **Consensus engines**: Snowman/Snowman++ for all Primary Network chains (P/C/X post-Cortina). The legacy Lux DAG engine exists but is unused.
- **VMs**: PlatformVM (Platform-Chain), Coreth (LUExchange-Chain), XVM (Exchange-Chain), plus pluggable/`rpcchainvm` VMs for custom L1s.
- **Chain manager**: Boots P/C/X, creates new chains on request, routes consensus messages.
- **APIs**: HTTP/WS via `/ext/*`, with health/metrics, admin/info, and per-chain RPCs.
- **Storage**: LevelDB (default) or PebbleDB, shared atomic UTXO memory for cross-chain transfers, optional indexer.

## Core Components

| Component | Description |
|-----------|-------------|
| **Network Layer** | P2P networking for peer discovery, message routing, and validator communication |
| **Chain Manager** | Orchestrates blockchain lifecycle, bootstrapping, and state synchronization |
| **Consensus Engines** | Snowman/Snowman++ for all Primary Network chains and most L1s |
| **Virtual Machines** | PlatformVM, Coreth, XVM, and custom VMs (native Go or `rpcchainvm`) |
| **API Server** | HTTP/HTTPS endpoints for interacting with the node |
| **Database** | Persistent storage using LevelDB (default) or PebbleDB; shared atomic memory |

## Primary Network Chains

LuxGo validates three chains on the Primary Network:

<Cards>
  <Card title="Platform-Chain (Platform)" href="/docs/primary-network">
    Manages validators, staking, L1 chains, and chain creation. Uses PlatformVM (Snowman++).
  </Card>
  <Card title="LUExchange-Chain (Contract)" href="/docs/primary-network">
    EVM-compatible chain for smart contracts. Uses Coreth (grafted go-ethereum) with Snowman++.
  </Card>
  <Card title="Exchange-Chain (Exchange)" href="/docs/primary-network">
    High-throughput asset transfers using UTXO model. Uses XVM with Snowman (linearized in Cortina).
  </Card>
</Cards>

## Key Design Principles

### Modularity
LuxGo separates concerns into distinct layers:
- **Consensus** is decoupled from application logic
- **VMs** are pluggable and can be developed independently
- **Networking** is abstracted from chain-specific operations

### Extensibility
- Custom VMs can be loaded as plugins (native) or via `rpcchainvm` (any language)
- Lux L1s can run any VM that implements the required interface
- Chain configurations and upgrades can be customized per-network/chain

### Performance
- Sub-second finality through probabilistic consensus
- Parallel transaction processing across independent chains
- State sync and Snowman++ proposer windows to reduce contention and bootstrap faster

## Next Steps

<Cards>
  <Card title="Core Architecture" href="/docs/nodes/architecture/core-components">
    Deep dive into LuxGo's package structure and component interactions
  </Card>
  <Card title="Consensus Protocols" href="/docs/nodes/architecture/consensus">
    Learn how Snowman and Lux consensus work under the hood
  </Card>
  <Card title="Virtual Machines" href="/docs/nodes/architecture/virtual-machines">
    Understand how VMs define blockchain behavior and how to build custom VMs
  </Card>
  <Card title="Networking" href="/docs/nodes/architecture/networking">
    Explore the P2P protocol and peer management system
  </Card>
</Cards>


# Networking Layer (/docs/nodes/architecture/networking)

---
title: Networking Layer
description: Understanding LuxGo's P2P networking, peer management, and message protocols.
---

LuxGo uses a custom peer-to-peer (P2P) networking layer designed for high-throughput consensus messaging. This page covers the network architecture, peer management, and message protocols.

## Network Overview

<Mermaid chart={`
graph TB
    subgraph LuxGo_Node["LuxGo Node"]
        NM[Network Manager]
        PM[Peer Manager]
        Router[Message Router]

        subgraph Connections["Connections"]
            P1[Peer 1]
            P2[Peer 2]
            P3[Peer N]
        end
    end

    subgraph Chains["Chains"]
        PC[Platform-Chain Handler]
        CC[LUExchange-Chain Handler]
        XC[Exchange-Chain Handler]
    end

    P1 & P2 & P3 <--> PM
    PM <--> NM
    NM <--> Router
    Router --> PC & CC & XC
`} />

## Network Interface

The core network interface ([`network/network.go`](https://github.com/luxfi/luxgo/blob/master/network/network.go)) handles all P2P operations:

```go title="network/network.go"
type Network interface {
    // Message sending (from consensus)
    sender.ExternalSender

    // Health monitoring
    health.Checker

    // Peer management
    peer.Network

    // Lifecycle
    StartClose()
    Dispatch() error

    // Manual peer tracking
    ManuallyTrack(nodeID ids.NodeID, ip netip.AddrPort)

    // Peer information
    PeerInfo(nodeIDs []ids.NodeID) []peer.Info

    // Uptime tracking
    NodeUptime() (UptimeResult, error)
}
```

## Peer Discovery

LuxGo discovers peers through multiple mechanisms:

### Bootstrap Nodes

Initial connections to known bootstrap nodes are configured per-network (sampled from genesis) and can be overridden with `--bootstrap-ips`/`--bootstrap-ids`. See `config/config.go:getBootstrapConfig`.

### Peer Exchange

Nodes share known peers with each other:

<Mermaid chart={`
sequenceDiagram
    participant A as Node A
    participant B as Node B
    participant C as Node C

    A->>B: Connect
    A->>B: PeerList request
    B-->>A: Node C, Node D, ...
    A->>C: Connect discovered
`} />

### IP Tracking

The network maintains IP information for reconnection:

```go title="network/ip_tracker.go"
type ipTracker struct {
    // Known peer IPs
    mostRecentTrackedIPs map[ids.NodeID]*ips.ClaimedIPPort

    // Bloom filter for efficient gossip
    bloom *bloom.ReadFilter
}
```

## Connection Lifecycle

### Establishing Connections

<Mermaid chart={`
sequenceDiagram
    participant A as Node A
    participant B as Node B

    A->>B: TCP Connect
    A->>B: Mutual TLS with staking cert
    A->>B: Handshake (network ID, POP, subnets)
    B-->>A: Handshake + PeerList
    A-->>B: PeerList (optional pull)
    Note over A,B: Connection Established
`} />

### TLS Authentication

All connections use mutual TLS with staking certificates:

```go
// Each node has a staking keypair
type Node struct {
    StakingTLSSigner crypto.Signer
    StakingTLSCert   *staking.Certificate
    ID               ids.NodeID  // Derived from certificate
}
```

**Node ID Derivation:**
```go
// NodeID is derived from the staking certificate
nodeID := ids.NodeIDFromCert(stakingCert)
```

### Peer States

<Mermaid chart={`
stateDiagram-v2
    [*] --> Connecting: Dial
    Connecting --> Upgrading: TCP Connected
    Upgrading --> Handshaking: TLS Complete
    Handshaking --> Connected: Handshake + PeerList
    Connected --> Disconnected: Error or Timeout
    Disconnected --> Connecting: Reconnect
    Disconnected --> [*]: Manual Remove
`} />

## Message Protocol

### Message Types

Messages are defined using Protocol Buffers ([`proto/p2p/p2p.proto`](https://github.com/luxfi/luxgo/blob/master/proto/p2p/p2p.proto)):

```protobuf title="proto/p2p/p2p.proto"
message Message {
  reserved 1;
  oneof message {
    // Optional compression for supported message types
    bytes compressed_zstd = 2;

    // Handshake & peering
    Ping ping = 11;
    Pong pong = 12;
    Handshake handshake = 13;
    GetPeerList get_peer_list = 35;
    PeerList peer_list = 14;

    // State sync
    GetStateSummaryFrontier get_state_summary_frontier = 15;
    StateSummaryFrontier state_summary_frontier = 16;
    GetAcceptedStateSummary get_accepted_state_summary = 17;
    AcceptedStateSummary accepted_state_summary = 18;

    // Bootstrapping
    GetAcceptedFrontier get_accepted_frontier = 19;
    AcceptedFrontier accepted_frontier = 20;
    GetAccepted get_accepted = 21;
    Accepted accepted = 22;
    GetAncestors get_ancestors = 23;
    Ancestors ancestors = 24;

    // Consensus
    Get get = 25;
    Put put = 26;
    PushQuery push_query = 27;
    PullQuery pull_query = 28;
    Chits chits = 29;

    // Application-level
    AppRequest app_request = 30;
    AppResponse app_response = 31;
    AppGossip app_gossip = 32;
    AppError app_error = 34;

    // Streaming
    Simplex simplex = 36;
  }
}
```

### Consensus Messages

| Message | Purpose |
|---------|---------|
| `PushQuery` | Send block and request vote |
| `PullQuery` | Request vote without sending block |
| `Chits` | Vote response with preferences |
| `Get` | Request a specific block |
| `Put` | Send a requested block |
| `GetAcceptedFrontier` / `AcceptedFrontier` | Bootstrap frontier exchange |
| `GetAccepted` / `Accepted` | Request/return accepted containers for heights |
| `GetAncestors` / `Ancestors` | Fetch a container and its ancestors |
| `GetStateSummaryFrontier` / `StateSummaryFrontier` | State sync frontier |
| `GetAcceptedStateSummary` / `AcceptedStateSummary` | State summaries at heights |

### Application Messages

VMs send custom messages through the `common.AppSender` provided at initialization:

```go
type AppSender interface {
    SendAppRequest(ctx context.Context, nodeIDs set.Set[ids.NodeID],
        requestID uint32, appRequestBytes []byte) error
    SendAppResponse(ctx context.Context, nodeID ids.NodeID,
        requestID uint32, appResponseBytes []byte) error
    SendAppError(ctx context.Context, nodeID ids.NodeID,
        requestID uint32, errorCode int32, errorMessage string) error
    SendAppGossip(ctx context.Context, config common.SendConfig,
        appGossipBytes []byte) error
}
```

Inbound app traffic is delivered to the VM's `AppRequest`/`AppResponse`/`AppGossip` handlers via `common.AppHandler`.

## Message Routing

The router ([`snow/networking/router`](https://github.com/luxfi/luxgo/tree/master/snow/networking/router)) directs messages to appropriate handlers:

```go title="snow/networking/router/router.go"
type Router interface {
    // Route messages to chains
    HandleInbound(ctx context.Context, msg message.InboundMessage)

    // Register chain handlers
    AddChain(ctx context.Context, chain handler.Handler) error

    // Health checking
    health.Checker
}
```

### Chain Message Handler

```go title="snow/networking/handler/handler.go"
type Handler interface {
    // Consensus messages
    HandleMsg(ctx context.Context, msg Message) error

    // Lifecycle
    Start(ctx context.Context, recoverPanic bool)
    Stop(ctx context.Context)
}
```

## Throttling & Rate Limiting

### Inbound Throttling

Protects nodes from message floods ([`network/throttling`](https://github.com/luxfi/luxgo/tree/master/network/throttling)):

```go title="network/throttling/inbound_msg_throttler.go"
type InboundMsgThrottler interface {
    // Check if message should be allowed
    Acquire(msg message.InboundMessage, nodeID ids.NodeID) ReleaseFunc

    // Release acquired resources
    ReleaseFunc func()
}
```

**Throttling Dimensions:**
- **Bandwidth**: Bytes per second per peer
- **Message count**: Messages per second
- **CPU time**: Processing time limits

### Outbound Throttling

Prevents overwhelming peers:

```go title="network/throttling/outbound_msg_throttler.go"
type OutboundMsgThrottler interface {
    // Acquire permission to send
    Acquire(msg message.OutboundMessage, nodeID ids.NodeID) ReleaseFunc
}
```

### Connection Throttling

Limits connection attempts:

```go
type InboundConnUpgradeThrottler interface {
    // Check if connection upgrade should proceed
    ShouldUpgrade(ip netip.AddrPort) bool
}
```

## Peer Scoring

Nodes track peer behavior for connection prioritization:

```go
type PeerInfo struct {
    IP             netip.AddrPort
    PublicIP       netip.AddrPort
    ID             ids.NodeID
    Version        string
    LastSent       time.Time
    LastReceived   time.Time
    ObservedUptime uint32
    TrackedSubnets []ids.ID
}
```

### Benchlisting

Misbehaving peers are temporarily blacklisted ([`snow/networking/benchlist`](https://github.com/luxfi/luxgo/tree/master/snow/networking/benchlist)):

```go title="snow/networking/benchlist/benchlist.go"
type Benchlist interface {
    // Add peer to benchlist
    RegisterFailure(validatorID ids.NodeID)

    // Check if peer is benched
    IsBenched(validatorID ids.NodeID) bool
}
```

**Benchlist Triggers:**
- Repeated query timeouts
- Invalid message responses
- Resource exhaustion

## Health Monitoring

Network health is exposed via the health API:

```go
type UptimeResult struct {
    // Percent of stake that sees us as meeting uptime requirement
    RewardingStakePercentage float64

    // Weighted average of observed uptimes
    WeightedAveragePercentage float64
}
```

### Health Metrics

```go
const (
    ConnectedPeersKey          = "connectedPeers"
    TimeSinceLastMsgReceivedKey = "timeSinceLastMsgReceived"
    TimeSinceLastMsgSentKey     = "timeSinceLastMsgSent"
    SendFailRateKey            = "sendFailRate"
)
```

**Example Health Response:**
```json
{
  "healthy": true,
  "checks": {
    "network": {
      "message": {
        "connectedPeers": 45,
        "timeSinceLastMsgReceived": "1.2s",
        "timeSinceLastMsgSent": "0.8s",
        "sendFailRate": 0.001
      }
    }
  }
}
```

## Network Configuration

Key configuration options:

```go title="config/config.go"
type NetworkConfig struct {
    // Connection limits
    MaxInboundConnections  int
    MaxOutboundConnections int

    // Timeouts
    PingFrequency  time.Duration
    PongTimeout    time.Duration
    ReadHandshake  time.Duration

    // Throttling
    InboundThrottlerAtLargeAllocSize  uint64
    InboundThrottlerVdrAllocSize      uint64
    OutboundThrottlerAtLargeAllocSize uint64

    // Peer management
    PeerListGossipFrequency time.Duration
    PeerListPullGossipFreq  time.Duration
}
```

### Command Line Flags

```bash
# Connection settings
--network-max-reconnect-delay=1m
--network-initial-reconnect-delay=1s
--network-peer-list-gossip-frequency=1m

# Throttling
--network-inbound-throttler-at-large-alloc-size=6291456
--network-outbound-throttler-at-large-alloc-size=6291456
```

## Subnet Networking

Validators can participate in multiple subnets:

```go
type SubnetTracker interface {
    // Track additional subnet
    TrackedSubnets() set.Set[ids.ID]
}
```

**Subnet-Specific Peers:**
- Handshake carries tracked subnet IDs (and `all_subnets` flag)
- Nodes connect preferentially to same-subnet validators
- Gossip is scoped to relevant subnets
- Cross-subnet communication uses explicit routing

## Debugging Network Issues

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No peers | Firewall blocking 9651 | Open port 9651 |
| High latency | Geographic distance | Add regional bootstrappers |
| Disconnections | Rate limiting | Increase throttle limits |
| Benchmark failures | Peer misbehavior | Check peer logs |

### Useful Endpoints

```bash
# Get connected peers
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.peers"
}' -H 'content-type:application/json;' localhost:9650/ext/info

# Get network health
curl localhost:9650/ext/health
```

## Next Steps

<Cards>
  <Card title="Run a Node" href="/docs/nodes/run-a-node">
    Set up and configure your own LuxGo node
  </Card>
  <Card title="Node Configuration" href="/docs/nodes/configure/configs-flags">
    Full reference for network configuration options
  </Card>
</Cards>


# Virtual Machines (/docs/nodes/architecture/virtual-machines)

---
title: Virtual Machines
description: Understand how Virtual Machines (VMs) define blockchain behavior in LuxGo, including the VM interface and built-in VMs.
---

A Virtual Machine (VM) defines the application-level logic of a blockchain. In LuxGo, VMs are decoupled from consensus, allowing developers to create custom blockchain behavior while reusing the battle-tested consensus layer.

## What is a Virtual Machine?

Think of a VM as the "personality" of a blockchain:

| Aspect | What the VM Defines |
|--------|---------------------|
| **State** | What data the blockchain stores |
| **Transactions** | Valid operations and their effects |
| **Blocks** | How transactions are packaged |
| **APIs** | How users interact with the chain |
| **Validation** | Rules for accepting blocks |

<Callout type="info">
VMs are reusable. Multiple blockchains can run the same VM, each with independent state. This is similar to how a class can have multiple instances in object-oriented programming.
</Callout>

## VM Architecture

<Mermaid chart={`
graph TB
    subgraph LuxGo_Node["LuxGo Node"]
        CE[Consensus Engine]

        subgraph Virtual_Machine["Virtual Machine"]
            VMI[VM Interface]
            BM[Block Manager]
            TXP[Transaction Pool]
            ST[State]
            API[API Handlers]
        end

        DB[(Database)]
    end

    CE <-->|BuildBlock, Verify, Accept| VMI
    VMI --> BM
    VMI --> TXP
    VMI --> API
    BM --> ST
    ST --> DB

    User -->|RPC| API
    API -->|Submit TX| TXP
`} />

## Core VM Interface

Every VM must implement the [`ChainVM`](https://github.com/luxfi/luxgo/blob/master/snow/engine/snowman/block/vm.go) interface for linear chain consensus:

```go title="snow/engine/snowman/block/vm.go"
type ChainVM interface {
    common.VM

    // Block building
    BuildBlock(ctx context.Context) (block.Block, error)

    // Block retrieval
    GetBlock(ctx context.Context, blkID ids.ID) (block.Block, error)
    ParseBlock(ctx context.Context, blockBytes []byte) (block.Block, error)

    // Consensus integration
    SetPreference(ctx context.Context, blkID ids.ID) error
    LastAccepted(ctx context.Context) (ids.ID, error)

    // Optional: height-indexed access
    GetBlockIDAtHeight(ctx context.Context, height uint64) (ids.ID, error)
}
```

### Base VM Interface

The foundation interface that all VMs implement ([source](https://github.com/luxfi/luxgo/blob/master/snow/engine/common/vm.go)):

```go title="snow/engine/common/vm.go"
type VM interface {
    common.AppHandler          // AppRequest/AppResponse/AppGossip hooks
    health.Checker             // Exposed via /ext/health
    validators.Connector       // Called on peer connect/disconnect

    // Lifecycle
    Initialize(ctx context.Context, chainCtx *snow.Context,
        db database.Database, genesisBytes []byte,
        upgradeBytes []byte, configBytes []byte,
        fxs []*common.Fx, appSender common.AppSender) error
    SetState(ctx context.Context, state snow.State) error
    Shutdown(ctx context.Context) error

    // Info
    Version(ctx context.Context) (string, error)

    // APIs
    CreateHandlers(ctx context.Context) (map[string]http.Handler, error)
    NewHTTPHandler(ctx context.Context) (http.Handler, error)

    // Engine notifications (PendingTxs, etc.)
    WaitForEvent(ctx context.Context) (common.Message, error)
}
```

## Block Interface

Blocks are the fundamental unit of consensus ([source](https://github.com/luxfi/luxgo/blob/master/snow/consensus/snowman/block.go)):

```go title="snow/consensus/snowman/block.go"
type Block interface {
    // ID(), Accept(), Reject(), Status() come from snow.Decidable
    snow.Decidable

    // Identity
    Parent() ids.ID
    Height() uint64
    Timestamp() time.Time
    Bytes() []byte

    // Validation
    Verify(context.Context) error
}
```

### Block Lifecycle

<Mermaid chart={`
stateDiagram-v2
    [*] --> Received: ParseBlock
    Received --> Pending: Waiting for ancestors
    Pending --> Processing: Ancestors verified
    Processing --> Verified: Verify succeeds
    Processing --> Invalid: Verify fails
    Verified --> Accepted: Accept
    Verified --> Rejected: Reject
    Invalid --> [*]: Discarded
    Accepted --> [*]: Committed to state
    Rejected --> [*]: Discarded
`} />

### Block Status

```go
type Status int

const (
    Unknown Status = iota
    Processing
    Rejected
    Accepted
)
```

## Built-in Virtual Machines

### Platform VM (Platform-Chain)

The Platform VM ([`vms/platformvm`](https://github.com/luxfi/luxgo/tree/master/vms/platformvm)) manages the Lux network itself:

```go title="vms/platformvm/vm.go"
type VM struct {
    // State management
    state        state.State
    atomicUTXOs  atomic.SharedMemory

    // Block building
    Builder      blockbuilder.Builder
    Network      network.Network

    // Validators
    Validators   validators.Manager
}
```

**Responsibilities:**
- **Validator Management**: Add/remove validators, track stake
- **Subnet Creation**: Create new validator sets
- **Chain Creation**: Launch new blockchains
- **Staking**: Manage delegation and rewards
- **Warp Messaging**: Sign cross-chain messages

**Key Transaction Types:**

| Transaction | Purpose | Era |
|-------------|---------|-----|
| `AddValidatorTx` | Add a Primary Network validator | Apricot |
| `AddDelegatorTx` | Delegate stake to a validator | Apricot |
| `CreateSubnetTx` | Create a new subnet | Apricot |
| `CreateChainTx` | Launch a blockchain on a subnet | Apricot |
| `ImportTx` / `ExportTx` | Cross-chain asset transfers | Apricot |
| `AddPermissionlessValidatorTx` | Add validator to permissionless subnet | Banff |
| `AddPermissionlessDelegatorTx` | Delegate to permissionless validator | Banff |
| `TransformSubnetTx` | Convert subnet to permissionless | Banff |
| `TransferSubnetOwnershipTx` | Transfer subnet ownership | Durango |
| `ConvertSubnetToL1Tx` | Convert subnet to Lux L1 | Etna |
| `RegisterL1ValidatorTx` | Register validator on L1 | Etna |
| `SetL1ValidatorWeightTx` | Set L1 validator weight | Etna |
| `IncreaseL1ValidatorBalanceTx` | Add balance to L1 validator | Etna |
| `DisableL1ValidatorTx` | Disable an L1 validator | Etna |

<Callout type="info">
The **Etna upgrade** introduced 5 new transaction types for managing Lux L1s. These enable converting subnets to sovereign L1s with their own validator management.
</Callout>

### XVM (Exchange-Chain)

The XVM ([`vms/xvm`](https://github.com/luxfi/luxgo/tree/master/vms/xvm)) handles asset creation and transfers using the UTXO model:

<Callout type="info">
The Exchange-Chain was linearized in the **Cortina upgrade** (April 2023). It now uses Snowman consensus like the Platform-Chain and LUExchange-Chain, rather than the legacy Lux DAG consensus. The XVM implements the `LinearizableVMWithEngine` interface to support this transition.
</Callout>

```go title="vms/xvm/vm.go"
type VM struct {
    // Asset management
    fxs     []*Fx
    state   state.State

    // UTXO handling
    utxoSet atomic.SharedMemory
}
```

**Features:**
- **Multi-Asset Support**: Native LUX and custom assets
- **UTXO Model**: Bitcoin-style transaction inputs/outputs
- **Snowman Consensus**: Linear chain consensus (linearized from DAG in Cortina upgrade)
- **Feature Extensions (Fxs)**: Pluggable transaction types
  - `secp256k1fx`: Standard signatures
  - `nftfx`: Non-fungible tokens
  - `propertyfx`: Property ownership

**Transaction Types:**

| Transaction | Purpose |
|-------------|---------|
| `CreateAssetTx` | Create a new asset |
| `OperationTx` | Mint/burn assets |
| `BaseTx` | Transfer assets |
| `ImportTx` | Import from other chains |
| `ExportTx` | Export to other chains |

### Coreth (LUExchange-Chain)

Coreth is the EVM implementation for the LUExchange-Chain:

<Callout>
Coreth is **grafted** into the LuxGo repository at `graft/coreth/`. The standalone [`luxfi/coreth`](https://github.com/luxfi/coreth) repository has been archived and is now read-only. All active development occurs within the LuxGo monorepo.
</Callout>

**Features:**
- Full Ethereum Virtual Machine compatibility
- Supports Solidity smart contracts
- Web3 JSON-RPC API (`eth`, `personal`, `txpool`, `debug` namespaces)
- EIP-1559 dynamic fees
- Atomic transactions with other Lux chains (via shared memory)
- Support for Ethereum upgrades through Cancun

### ProposerVM (Snowman++)

The ProposerVM ([`vms/proposervm`](https://github.com/luxfi/luxgo/tree/master/vms/proposervm)) wraps other VMs to add Snowman++ proposer windows:

```go title="vms/proposervm/vm.go"
type VM struct {
    // Wrapped VM
    ChainVM block.ChainVM

    // Proposer selection
    windower proposer.Windower

    // Block timing
    MinBlockDelay time.Duration
}
```

**How it Works:**
1. Stake-weighted proposers are sampled for each height.
2. Each proposer has a 5s slot (up to 6 slots) counted from the parent timestamp.
3. Only the active proposer can build during its slot; after the final slot any validator may build.
4. The wrapper enforces proposer signatures/timestamps before issuing to consensus.

Snowman++ is enabled on all Primary Network chains (Platform-Chain, LUExchange-Chain, Exchange-Chain) to pace block production without sacrificing liveness.

## Custom VMs

You can build custom VMs that run on Lux L1s. There are two approaches:

### 1. Native Go VM

Implement the `ChainVM` interface directly in Go:

```go
type MyVM struct {
    db      database.Database
    state   *MyState
    builder *BlockBuilder
    pending <-chan struct{}
}

func (vm *MyVM) Initialize(ctx context.Context, ...) error {
    // Set up database and state
    vm.db = db
    vm.state = NewState(db)
    vm.pending = vm.builder.Subscribe() // emits when there are pending txs
    return nil
}

func (vm *MyVM) WaitForEvent(ctx context.Context) (common.Message, error) {
    select {
    case <-ctx.Done():
        return 0, ctx.Err()
    case <-vm.pending:
        return common.PendingTxs, nil
    }
}

func (vm *MyVM) BuildBlock(ctx context.Context) (block.Block, error) {
    // Collect pending transactions
    txs := vm.builder.GetPendingTxs()
    // Create new block
    return NewBlock(vm.state.LastAccepted(), txs), nil
}
```

### 2. RPC VM (Any Language)

Use the [`rpcchainvm`](https://github.com/luxfi/luxgo/tree/master/vms/rpcchainvm) interface to build VMs in any language:

<Mermaid chart={`
graph LR
    subgraph LuxGo["LuxGo"]
        Client[RPCChainVM Client]
    end

    subgraph External_Process["External Process"]
        Server[VM Server]
        Logic[VM Logic]
    end

    Client <-->|gRPC| Server
    Server --> Logic
`} />

**Benefits:**
- Write VMs in Rust, TypeScript, etc.
- Process isolation
- Independent deployment

**Protocol:**
```go
// gRPC service definition
service VM {
    rpc Initialize(InitializeRequest) returns (InitializeResponse);
    rpc BuildBlock(BuildBlockRequest) returns (BuildBlockResponse);
    rpc ParseBlock(ParseBlockRequest) returns (ParseBlockResponse);
    rpc GetBlock(GetBlockRequest) returns (GetBlockResponse);
    // ... more methods
}
```

## VM Registration

VMs are registered with the node at startup:

```go title="node/node.go"
func (n *Node) initVMs() error {
    // Built-in VMs
    n.VMManager.RegisterFactory(ctx, constants.PlatformVMID,
        &platformvm.Factory{})
    n.VMManager.RegisterFactory(ctx, constants.AVMID,
        &xvm.Factory{})
    n.VMManager.RegisterFactory(ctx, constants.EVMID,
        &coreth.Factory{})

    // Plugin VMs are discovered from the plugins directory
    // (default: ~/.luxgo/plugins/)
}
```

**Plugin Discovery:**
1. VMs are placed in `~/.luxgo/plugins/`
2. Filename is the VM ID (e.g., `srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`)
3. Node discovers and loads plugins at startup

## VM Configuration

Each chain can have custom VM configuration:

```json title="~/.luxgo/configs/chains/{chainID}/config.json"
{
  "pruning-enabled": true,
  "state-sync-enabled": true,
  "eth-apis": ["eth", "eth-filter", "net", "web3"]
}
```

**Chain-Specific Configs:**
- Stored in `~/.luxgo/configs/chains/{chainID}/`
- `config.json`: VM configuration
- `upgrade.json`: Upgrade coordination

## Best Practices

### State Management

```go
// Use versioned database for atomic commits
func (vm *VM) Accept(ctx context.Context, blk *Block) error {
    batch := vm.db.NewBatch()
    defer batch.Reset()

    // Apply state changes
    for _, tx := range blk.Txs {
        if err := vm.state.Apply(batch, tx); err != nil {
            return err
        }
    }

    // Commit atomically
    return batch.Write()
}
```

### Block Building

```go
// Drive block production: return PendingTxs when mempool has work
func (vm *VM) WaitForEvent(ctx context.Context) (common.Message, error) {
    select {
    case <-ctx.Done():
        return 0, ctx.Err()
    case <-vm.pending:
        return common.PendingTxs, nil
    }
}
```

### API Design

```go
func (vm *VM) CreateHandlers(ctx context.Context) (map[string]http.Handler, error) {
    return map[string]http.Handler{
        "/rpc":    vm.newJSONRPCHandler(),
        "/ws":     vm.newWebSocketHandler(),
        "/health": vm.newHealthHandler(),
    }, nil
}
```

## Next Steps

<Cards>
  <Card title="Networking" href="/docs/nodes/architecture/networking">
    Learn how VMs communicate over the network
  </Card>
  <Card title="Build a Custom VM" href="/docs/lux-l1s/build-custom-vm">
    Start building your own Virtual Machine
  </Card>
</Cards>


# Backup and Restore (/docs/nodes/maintain/backup-restore)

---
title: Backup and Restore
---

Once you have your node up and running, it's time to prepare for disaster recovery. Should your machine ever have a catastrophic failure due to either hardware or software issues, or even a case of natural disaster, it's best to be prepared for such a situation by making a backup.

When running, a complete node installation along with the database can grow to be multiple gigabytes in size. Having to back up and restore such a large volume of data can be expensive, complicated and time-consuming. Luckily, there is a better way.

Instead of having to back up and restore everything, we need to back up only what is essential, that is, those files that cannot be reconstructed because they are unique to your node. For LuxGo node, unique files are those that identify your node on the network, in other words, files that define your NodeID.

Even if your node is a validator on the network and has multiple delegations on it, you don't need to worry about backing up anything else, because the validation and delegation transactions are also stored on the blockchain and will be restored during bootstrapping, along with the rest of the blockchain data.

The installation itself can be easily recreated by installing the node on a new machine, and all the remaining gigabytes of blockchain data can be easily recreated by the process of bootstrapping, which copies the data over from other network peers. However, if you would like to speed up the process, see the [Database Backup and Restore section](#database)

NodeID[​](#nodeid "Direct link to heading")
-------------------------------------------

<Callout type="warn">
If more than one running nodes share the same NodeID, the communications from other nodes in the Lux network to this NodeID will be random to one of these nodes. If this NodeID is of a validator, it will dramatically impact the uptime calculation of the validator which will very likely disqualify the validator from receiving the staking rewards. Please make sure only one node with the same NodeID run at one time.
</Callout>

NodeID is a unique identifier that differentiates your node from all the other peers on the network. It's a string formatted like `NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD`. You can look up the technical background of how the NodeID is constructed [here](/docs/rpcs/other/standards/cryptographic-primitives#tls-addresses). In essence, NodeID is defined by two files:

- `staker.crt`
- `staker.key`

NodePOP is this node's BLS key and proof of possession. Nodes must register a BLS key to act as a validator on the Primary Network. Your node's POP is logged on startup and is accessible over this endpoint.

- `publicKey` is the 48 byte hex representation of the BLS key.
- `proofOfPossession` is the 96 byte hex representation of the BLS signature.

NodePOP is defined by the `signer.key` file.

<Callout type="info">
For enhanced security, you can use [CubeSigner remote signing](/docs/nodes/maintain/cube-signer-sidecar) instead of storing BLS keys locally. CubeSigner stores keys in hardware-backed enclaves and eliminates the need to back up `signer.key` files.
</Callout>

In the default installation, they can be found in the working directory, specifically in `~/.luxgo/staking/`. All we need to do to recreate the node on another machine is to run a new installation with those same three files.

If `staker.key` and `staker.crt` are removed from a node, which is restarted afterwards, they will be recreated and a new node ID will be assigned.

If the `signer.key` is regenerated, the node will lose its previous BLS identity, which includes its public key and proof of possession. This change means that the node's former identity on the network will no longer be recognized, affecting its ability to participate in the consensus mechanism as before. Consequently, the node may lose its established reputation and any associated staking rewards.

<Callout type="warn">
If you have users defined in the keystore of your node, then you need to back up and restore those as well. [Keystore API](/docs/rpcs/other) has methods that can be used to export and import user keys. Note that Keystore API is used by developers only and not intended for use in production nodes. If you don't know what a keystore API is and have not used it, you don't need to worry about it.
</Callout>

### Backup[​](#backup "Direct link to heading")

To back up your node, we need to store `staker.crt` and `staker.key` files somewhere safe and private, preferably to a different computer, to your private To back up your node, we need to store `staker.crt`, `staker.key` and `signer.key` files somewhere safe and private, preferably to a different computer.

<Callout type="warn">
If someone gets a hold of your staker files, they still cannot get to your funds, as they are controlled by the wallet private keys, not by the node. But, they could re-create your node somewhere else, and depending on the circumstances make you lose the staking rewards. So make sure your staker files are secure.

If someone gains access to your `signer.key`, they could potentially sign transactions on behalf of your node, which might disrupt the operations and integrity of your node on the network.
</Callout>

Let's get the files off the machine running the node.

#### From Local Node[​](#from-local-node "Direct link to heading")

If you're running the node locally, on your desktop computer, just navigate to where the files are and copy them somewhere safe.

On a default Linux installation, the path to them will be `/home/USERNAME/.luxgo/staking/`, where `USERNAME` needs to be replaced with the actual username running the node. Select and copy the files from there to a backup location. You don't need to stop the node to do that.

#### From Remote Node Using `scp`[​](#from-remote-node-using-scp "Direct link to heading")

`scp` is a 'secure copy' command line program, available built-in on Linux and MacOS computers. There is also a Windows version, `pscp`, as part of the [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) package. If using `pscp`, in the following commands replace each usage of `scp` with `pscp -scp`.

To copy the files from the node, you will need to be able to remotely log into the machine. You can use account password, but the secure and recommended way is to use the SSH keys. The procedure for acquiring and setting up SSH keys is highly dependent on your cloud provider and machine configuration. You can refer to our [Amazon Web Services](/docs/nodes/run-a-node/on-third-party-services/amazon-web-services) and [Microsoft Azure](/docs/nodes/run-a-node/on-third-party-services/microsoft-azure) setup guides for those providers. Other providers will have similar procedures.

When you have means of remote login into the machine, you can copy the files over with the following command:

```bash
scp -r ubuntu@PUBLICIP:/home/ubuntu/.luxgo/staking ~/lux_backup
```

This assumes the username on the machine is `ubuntu`, replace with correct username in both places if it is different. Also, replace `PUBLICIP` with the actual public IP of the machine. If `scp` doesn't automatically use your downloaded SSH key, you can point to it manually:

```bash
scp -i /path/to/the/key.pem -r ubuntu@PUBLICIP:/home/ubuntu/.luxgo/staking ~/lux_backup
```

Once executed, this command will create `lux_backup` directory and place those three files in it. You need to store them somewhere safe.

### Restore[​](#restore "Direct link to heading")

To restore your node from a backup, we need to do the reverse: restore `staker.key`, `staker.crt` and `signer.key` from the backup to the working directory of the new node.

First, we need to do the usual [installation](/docs/nodes/run-a-node/using-install-script/installing-lux-go) of the node. This will create a new NodeID, a new BLS key and a new BLS signature, which we need to replace. When the node is installed correctly, log into the machine where the node is running and stop it:

```bash
sudo systemctl stop luxgo
```

We're ready to restore the node.

#### To Local Node[​](#to-local-node "Direct link to heading")

If you're running the node locally, just copy the `staker.key`, `staker.crt` and `signer.key` files from the backup location into the working directory, which on the default Linux installation will be `/home/USERNAME/.luxgo/staking/`. Replace `USERNAME` with the actual username used to run the node.

#### To Remote Node Using `scp`[​](#to-remote-node-using-scp "Direct link to heading")

Again, the process is just the reverse operation. Using `scp` we need to copy the `staker.key`, `staker.crt` and `signer.key` files from the backup location into the remote working directory. Assuming the backed up files are located in the directory where the above backup procedure placed them:

```bash
scp ~/lux_backup/{staker.*,signer.key} ubuntu@PUBLICIP:/home/ubuntu/.luxgo/staking
```

Or if you need to specify the path to the SSH key:

```bash
scp -i /path/to/the/key.pem ~/lux_backup/{staker.*,signer.key} ubuntu@PUBLICIP:/home/ubuntu/.luxgo/staking
```

And again, replace `ubuntu` with correct username if different, and `PUBLICIP` with the actual public IP of the machine running the node, as well as the path to the SSH key if used.

#### Restart the Node and Verify[​](#restart-the-node-and-verify "Direct link to heading")

Once the files have been replaced, log into the machine and start the node using:

```bash
sudo systemctl start luxgo
```

You can now check that the node is restored with the correct NodeID and NodePOP by issuing the [getNodeID](/docs/rpcs/other/info-rpc#infogetnodeid) API call in the same console you ran the previous command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

You should see your original NodeID and NodePOP (BLS key and BLS signature). Restore process is done.

Database[​](#database "Direct link to heading")
-----------------------------------------------

Normally, when starting a new node, you can just bootstrap from scratch. However, there are situations when you may prefer to reuse an existing database (ex: preserve keystore records, reduce sync time).

This tutorial will walk you through compressing your node's DB and moving it to another computer using `zip` and `scp`.

### Database Backup[​](#database-backup "Direct link to heading")

First, make sure to stop LuxGo, run:

```bash
sudo systemctl stop luxgo
```

<Callout type="warn">
You must stop the Lux node before you back up the database otherwise data could become corrupted.
</Callout>

Once the node is stopped, you can `zip` the database directory to reduce the size of the backup and speed up the transfer using `scp`:

```bash
zip -r lux_db_backup.zip .luxgo/db
```

_Note: It may take > 30 minutes to zip the node's DB._

Next, you can transfer the backup to another machine:

```bash
scp -r ubuntu@PUBLICIP:/home/ubuntu/lux_db_backup.zip ~/lux_db_backup.zip
```

This assumes the username on the machine is `ubuntu`, replace with correct username in both places if it is different. Also, replace `PUBLICIP` with the actual public IP of the machine. If `scp` doesn't automatically use your downloaded SSH key, you can point to it manually:

```bash
scp -i /path/to/the/key.pem -r ubuntu@PUBLICIP:/home/ubuntu/lux_db_backup.zip ~/lux_db_backup.zip
```

Once executed, this command will create `lux_db_backup.zip` directory in you home directory.

### Database Restore[​](#database-restore "Direct link to heading")

_This tutorial assumes you have already completed "Database Backup" and have a backup at ~/lux\_db\_backup.zip._

First, we need to do the usual [installation](/docs/nodes/run-a-node/using-install-script/installing-lux-go) of the node. When the node is installed correctly, log into the machine where the node is running and stop it:

```bash
sudo systemctl stop luxgo
```

<Callout type="warn">
You must stop the Lux node before you restore the database otherwise data could become corrupted.
</Callout>

We're ready to restore the database. First, let's move the DB on the existing node (you can remove this old DB later if the restore was successful):

```bash
mv .luxgo/db .luxgo/db-old
```

Next, we'll unzip the backup we moved from another node (this will place the unzipped files in `~/.luxgo/db` when the command is run in the home directory):

```bash
unzip lux_db_backup.zip
```

After the database has been restored on a new node, use this command to start the node:

```bash
sudo systemctl start luxgo
```

Node should now be running from the database on the new instance. To check that everything is in order and that node is not bootstrapping from scratch (which would indicate a problem), use:

```bash
sudo journalctl -u luxgo -f
```

The node should be catching up to the network and fetching a small number of blocks before resuming normal operation (all the ones produced from the time when the node was stopped before the backup).

Once the backup has been restored and is working as expected, the zip can be deleted:

```bash
rm lux_db_backup.zip
```

### Database Direct Copy[​](#database-direct-copy "Direct link to heading")

You may be in a situation where you don't have enough disk space to create the archive containing the whole database, so you cannot complete the backup process as described previously.

In that case, you can still migrate your database to a new computer, by using a different approach: `direct copy`. Instead of creating the archive, moving the archive and unpacking it, we can do all of that on the fly.

To do so, you will need `ssh` access from the destination machine (where you want the database to end up) to the source machine (where the database currently is). Setting up `ssh` is the same as explained for `scp` earlier in the document.

Same as shown previously, you need to stop the node (on both machines):

```bash
sudo systemctl stop luxgo
```

<Callout type="warn">
You must stop the Lux node before you back up the database otherwise data could become corrupted.
</Callout>

Then, on the destination machine, change to a directory where you would like to the put the database files, enter the following command:

```bash
ssh -i /path/to/the/key.pem ubuntu@PUBLICIP 'tar czf - .luxgo/db' | tar xvzf - -C .
```

Make sure to replace the correct path to the key, and correct IP of the source machine. This will compress the database, but instead of writing it to a file it will pipe it over `ssh` directly to destination machine, where it will be decompressed and written to disk. The process can take a long time, make sure it completes before continuing.

After copying is done, all you need to do now is move the database to the correct location on the destination machine. Assuming there is a default LuxGo node installation, we remove the old database and replace it with the new one:

```bash
rm -rf ~/.luxgo/db
mv db ~/.luxgo/db
```

You can now start the node on the destination machine:

```bash
sudo systemctl start luxgo
```

Node should now be running from the copied database. To check that everything is in order and that node is not bootstrapping from scratch (which would indicate a problem), use:

```bash
sudo journalctl -u luxgo -f
```

The node should be catching up to the network and fetching a small number of blocks before resuming normal operation (all the ones produced from the time when the node was stopped before the backup).

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Essential part of securing your node is the backup that enables full and painless restoration of your node. Following this tutorial you can rest easy knowing that should you ever find yourself in a situation where you need to restore your node from scratch, you can easily and quickly do so.

If you have any problems following this tutorial, comments you want to share with us or just want to chat, you can reach us on our [Discord](https://chat.avalabs.org/) server.


# CubeSigner Remote BLS Signing (/docs/nodes/maintain/cube-signer-sidecar)

---
title: CubeSigner Remote BLS Signing
description: Learn how to use CubeSigner for secure hardware-backed BLS key management with LuxGo validators.
---

The CubeSigner sidecar enables LuxGo validators to use hardware-backed remote signing for BLS keys instead of storing them locally. This guide walks you through setting up and configuring the CubeSigner sidecar for enhanced security.

## Introduction

By default, LuxGo nodes store their BLS signing keys locally in a `signer.key` file. While functional, this approach has security limitations:

- Keys stored on disk are vulnerable to theft or compromise
- Lost or corrupted keys mean permanent loss of validator identity and staking rewards
- No protection against unauthorized signing operations

The CubeSigner sidecar solves these problems by delegating all BLS signing operations to [CubeSigner](https://cubist.dev/), a hardware-backed key management platform. Your BLS keys remain in secure AWS Nitro Enclaves and never touch local storage.

### Benefits

- **Hardware Security**: Keys stored in AWS Nitro Enclaves, never exposed in memory
- **Anti-Slashing Protection**: Built-in safeguards prevent double signing
- **High Availability**: 99.99% uptime with millisecond latency
- **Policy Enforcement**: Control what operations can be signed at the platform level
- **Disaster Recovery**: Keys remain safe even if validator node is compromised

## Prerequisites

Before you begin, ensure you have:

- **LuxGo v1.13.4 or later**: The `--staking-rpc-signer-endpoint` flag was added in the Fortuna.4 release
- **Cubist Account**: Sign up at [cubist.dev](https://cubist.dev/) for CubeSigner access
- **CubeSigner CLI**: Install the `cs` command-line tool ([installation guide](https://docs.cubist.dev/))
- **Shell Access**: Ability to configure and restart your LuxGo node

<Callout type="warn">
The CubeSigner sidecar is an advanced configuration for production validators. Make sure you understand the setup process before implementing on mainnet.
</Callout>

## Architecture Overview

The CubeSigner sidecar acts as a gRPC proxy between LuxGo and the CubeSigner API:

```
LuxGo Node
       ↓
  gRPC Request (localhost:50051)
       ↓
CubeSigner Sidecar
       ↓
  HTTPS Request
       ↓
CubeSigner API (AWS Nitro Enclaves)
       ↓
  BLS Signature
       ↓
Returns to LuxGo
```

The sidecar implements LuxGo's `signer.proto` gRPC interface, translating node signing requests into CubeSigner API calls. All cryptographic operations happen inside CubeSigner's secure enclaves.

## Step 1: Set Up CubeSigner

### Create a Role

First, create a CubeSigner role for your BLS signing operations:

```bash
cs role create --role-name lux-bls-signer
```

This command returns a role ID. Save this ID, as you'll need it in subsequent steps.

### Generate a BLS Key

Create a new BLS key for Lux ICM (Interchain Messaging):

```bash
cs keys create --key-type=bls-ava-icm
```

<Callout type="info">
CubeSigner uses the key type `bls-ava-icm` specifically for Lux BLS signing operations. This ensures the correct signing algorithm is used.
</Callout>

The command outputs a key ID in the format `Key#BlsAvaIcm_0x...`. Copy this key ID.

### Configure Signing Policy

Set the policy to allow raw BLS blob signing:

```bash
cs key set-policy --key-id <KEY_ID> --policy '"AllowRawBlobSigning"'
```

Replace `<KEY_ID>` with the key ID from the previous step.

<Callout type="warn" title="Important">
The `AllowRawBlobSigning` policy is required for LuxGo to sign messages. Without this policy, signing requests will be rejected.
</Callout>

### Associate Key with Role

Link your BLS key to the role you created:

```bash
cs role add-key --role-id <ROLE_ID> --key-id <KEY_ID>
```

### Generate Authentication Token

Create a token file that the sidecar will use to authenticate with CubeSigner:

```bash
cs token create --role-id <ROLE_ID> > token.json
```

This creates a JSON file containing authentication credentials. Keep this file secure.

<Callout type="error" title="Security Warning">
The `token.json` file grants access to your BLS signing key. Store it securely with restricted file permissions (`chmod 600 token.json`) and never commit it to version control. The sidecar refreshes this file automatically, so it must remain writable by the process.
</Callout>

## Step 2: Run the Sidecar

You can run the CubeSigner sidecar using Docker or as a standalone binary.

### Using Docker

Pull and run the official Docker image:

```bash
docker run -d \
  --name cube-signer-sidecar \
  -p 50051:50051 \
  -v $(pwd)/token.json:/token.json \
  -e SIGNER_ENDPOINT=https://gamma.signer.cubist.dev \
  -e KEY_ID=Key#BlsAvaIcm_0x... \
  -e TOKEN_FILE_PATH=/token.json \
  avaplatform/cube-signer-sidecar:0.0.0-rc9 start
```

Replace the `KEY_ID` value with your actual key ID from Step 1.

<Callout type="info">
Check [Docker Hub](https://hub.docker.com/r/avaplatform/cube-signer-sidecar/tags) for the latest available image tag. The `:latest` tag will be available once a stable release is published.
</Callout>

<Callout type="info">
Do not mount `token.json` as read-only; the sidecar writes refreshed session data back to this file. The default bind mount is read/write, which is required.
</Callout>

<Callout type="info">
The default CubeSigner endpoint for production is `https://gamma.signer.cubist.dev`. For testnet or development, CubeSigner may provide alternative endpoints.
</Callout>

### Running Locally

If you prefer to build from source:

```bash
# Clone the repository
git clone https://github.com/luxfi/cube-signer-sidecar.git
cd cube-signer-sidecar

# Build the binary
go build -o cube-signer-sidecar main/main.go

# Run the sidecar
export SIGNER_ENDPOINT=https://gamma.signer.cubist.dev
export KEY_ID=Key#BlsAvaIcm_0x...
export TOKEN_FILE_PATH=./token.json
./cube-signer-sidecar start
```

### Configuration Options

The sidecar supports configuration via command-line flags, environment variables, or a JSON config file:

| Option | Environment Variable | Required | Default | Description |
|--------|---------------------|----------|---------|-------------|
| `--token-file-path` | `TOKEN_FILE_PATH` | Yes | - | Path to the token JSON file |
| `--signer-endpoint` | `SIGNER_ENDPOINT` | Yes | - | CubeSigner API endpoint URL |
| `--key-id` | `KEY_ID` | Yes | - | BLS key identifier |
| `--port` | `PORT` | No | 50051 | gRPC server listening port |
| `--config-file` | `CONFIG_FILE` | No | - | Path to JSON configuration file |

**Example JSON Configuration:**

```json
{
  "token-file-path": "/path/to/token.json",
  "signer-endpoint": "https://gamma.signer.cubist.dev",
  "key-id": "Key#BlsAvaIcm_0x...",
  "port": 50051
}
```

Use with:

```bash
./cube-signer-sidecar start --config-file config.json
```

## Step 3: Configure LuxGo

Once the sidecar is running, configure LuxGo to use it for BLS signing.

### Add the Signer Endpoint Flag

Update your LuxGo startup command to include the `--staking-rpc-signer-endpoint` flag:

```bash
luxgo \
  --staking-rpc-signer-endpoint=127.0.0.1:50051 \
  [other flags...]
```

<Callout type="info">
If your sidecar is running on a different machine, replace `127.0.0.1` with the appropriate IP address. Ensure network connectivity and firewall rules allow gRPC traffic on port 50051.
</Callout>

### Using a Configuration File

Alternatively, add the setting to your LuxGo configuration JSON:

```json
{
  "staking-rpc-signer-endpoint": "127.0.0.1:50051"
}
```

### Using Systemd

If you run LuxGo as a systemd service, edit the service file:

```bash
sudo systemctl edit luxgo
```

Add the flag to the `ExecStart` line or add an environment variable:

```ini
[Service]
Environment="LUXGO_STAKING_RPC_SIGNER_ENDPOINT=127.0.0.1:50051"
```

Then restart the service:

```bash
sudo systemctl daemon-reload
sudo systemctl restart luxgo
```

## Verifying the Setup

After starting both the sidecar and LuxGo, verify the configuration is working correctly.

### Check Sidecar Logs

If running via Docker:

```bash
docker logs cube-signer-sidecar
```

You should see log messages indicating the gRPC server is running and receiving requests from LuxGo.

### Verify Node BLS Key

Call the LuxGo Info API to confirm your node is using the CubeSigner BLS key:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The response should include your NodeID and NodePOP (BLS public key and proof of possession):

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-...",
    "nodePOP": {
      "publicKey": "0x...",
      "proofOfPossession": "0x..."
    }
  },
  "id": 1
}
```

The `publicKey` value should match the BLS key you created in CubeSigner.

### Monitor Node Logs

Check LuxGo logs to ensure there are no signing errors:

```bash
sudo journalctl -u luxgo -f
```

Look for successful connection messages to the RPC signer endpoint. Any signing failures will appear as errors in these logs.

## Security Considerations

When using the CubeSigner sidecar, follow these security best practices:

### Token Management

- **Restrict File Permissions**: Set `token.json` to read-only for the user running the sidecar:
  ```bash
  chmod 600 token.json
  chown luxgo:luxgo token.json
  ```
- **Never Commit Tokens**: Add `token.json` to `.gitignore` to prevent accidental commits
- **Rotate Regularly**: Generate new tokens periodically and update your configuration
- **Monitor Usage**: Check CubeSigner logs for unauthorized signing attempts

### Network Security

- **Isolate the Sidecar**: Run the sidecar on the same machine as LuxGo or on a private network
- **Firewall Rules**: Restrict access to port 50051 to only the LuxGo process
- **TLS for Remote Connections**: The sidecar serves plaintext gRPC only; if you need TLS, place it behind a terminating reverse proxy or tunnel traffic over a private/secure network.

### Key Management

- **One Key Per Validator**: Each validator node should have its own unique BLS key
- **Backup Policies**: Document your CubeSigner role and key IDs for disaster recovery
- **Test First**: Always test the configuration on a testnet validator before deploying to mainnet

<Callout type="warn">
If someone gains access to your `token.json` file, they can sign messages on behalf of your validator. Treat this file with the same security as you would a private key.
</Callout>

## Troubleshooting

### Connection Refused Errors

**Problem**: LuxGo logs show "connection refused" when trying to reach the sidecar.

**Solution**:
- Verify the sidecar is running: `docker ps` or check the process
- Confirm the sidecar is listening on the correct port: `netstat -tlnp | grep 50051`
- Check firewall rules allow connections on port 50051

### Invalid Token Errors

**Problem**: Sidecar logs show authentication failures or invalid token errors.

**Solution**:
- Verify `token.json` contains valid JSON
- Ensure the token hasn't expired (tokens have a limited lifetime)
- Regenerate the token with `cs token create` and restart the sidecar

### Key Not Found Errors

**Problem**: Sidecar reports the key ID doesn't exist or isn't accessible.

**Solution**:
- Double-check the `KEY_ID` matches exactly what `cs keys create` returned
- Verify the key is associated with the role: `cs role keys --role-id <ROLE_ID>`
- Ensure the key has the `AllowRawBlobSigning` policy set

### Signing Policy Errors

**Problem**: Signing requests are rejected with policy errors.

**Solution**:
- Confirm the key policy allows raw blob signing:
  ```bash
  cs key set-policy --key-id <KEY_ID> --policy '"AllowRawBlobSigning"'
  ```
- Restart the sidecar after policy changes

### LuxGo Won't Start

**Problem**: LuxGo fails to start after adding the `--staking-rpc-signer-endpoint` flag.

**Solution**:
- Verify you're running LuxGo v1.13.4 or later: `luxgo --version`
- Remove any existing `signer.key` file (it conflicts with remote signing)
- Check the sidecar is reachable before starting LuxGo

## Migration from Local BLS Keys

If you're migrating an existing validator from local `signer.key` to CubeSigner, you have two options:

### Option 1: New BLS Key (Recommended for Testnet)

Generate a new BLS key in CubeSigner and update your validator registration. This is the cleanest approach but requires re-registering your validator.

### Option 2: Import Existing Key (Production Validators)

<Callout type="error" title="Contact CubeSigner Support">
Importing existing BLS keys into CubeSigner requires coordination with the CubeSigner team. This is typically only done for production validators with active stake. Contact [CubeSigner support](https://cubist.dev/contact) for assistance.
</Callout>

## Alternative: Local BLS Key Backup

If CubeSigner's remote signing doesn't fit your needs, consider traditional backup approaches for local BLS keys. See the [Backup and Restore](/docs/nodes/maintain/backup-restore) guide for instructions on backing up your `signer.key` file.

Traditional backups are simpler but lack the security benefits of hardware-backed signing.

## Next Steps

- [Monitor your node](/docs/nodes/maintain/monitoring) to ensure signing operations are working correctly
- [Upgrade LuxGo](/docs/nodes/maintain/upgrade) when new versions are released
- [Learn about Lux L1 validators](/docs/lux-l1s) if you're validating additional Subnets

## Resources

- [CubeSigner Documentation](https://docs.cubist.dev/)
- [CubeSigner for Validators](https://cubist.dev/cubesigner-hardware-backed-remote-signing-for-validator-infrastructure)
- [cube-signer-sidecar GitHub Repository](https://github.com/luxfi/cube-signer-sidecar)
- [LuxGo Release Notes (v1.13.4)](https://github.com/luxfi/luxgo/releases/tag/v1.13.4)


# Enroll in Lux Notify (/docs/nodes/maintain/enroll-in-avalanche-notify)

---
title: Enroll in Lux Notify
---

To receive email alerts if a validator becomes unresponsive or out-of-date, sign up with the Lux Notify tool: [http://notify.lux.network](http://notify.lux.network/).

Lux Notify is an active monitoring system that checks a validator's responsiveness each minute.

An email alert is sent if a validator is down for 5 consecutive checks and when a validator recovers (is responsive for 5 checks in a row).

<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
When signing up for email alerts, consider using a new, alias, or auto-forwarding email address to protect your privacy. Otherwise, it will be possible to link your NodeID to your email.
</Callout>

<Callout type="warn">
This tool is currently in BETA and validator alerts may erroneously be triggered, not triggered, or delayed. The best way to maximize the likelihood of earning staking rewards is to run redundant monitoring/alerting.
</Callout>


# Monitoring (/docs/nodes/maintain/monitoring)

---
title: Monitoring
description: Learn how to monitor an LuxGo node.
---

This tutorial demonstrates how to set up infrastructure to monitor an instance of [LuxGo](https://github.com/luxfi/luxgo). We will use:

- [Prometheus](https://prometheus.io/) to gather and store data
- [`node_exporter`](https://github.com/prometheus/node_exporter) to get information about the machine,
- LuxGo's [Metrics API](/docs/api-reference/metrics-api) to get information about the node
- [Grafana](https://grafana.com/) to visualize data on a dashboard.
- A set of pre-made [Lux dashboards](https://github.com/luxfi/lux-monitoring/tree/main/grafana/dashboards)

## Prerequisites:

- A running LuxGo node
- Shell access to the machine running the node
- Administrator privileges on the machine

This tutorial assumes you have Ubuntu 20.04 running on your node. Other Linux flavors that use `systemd` for running services and `apt-get` for package management might work but have not been tested. Community member has reported it works on Debian 10, might work on other Debian releases as well.

### Caveat: Security

The system as described here **should not** be opened to the public internet. Neither Prometheus nor Grafana as shown here is hardened against unauthorized access. Make sure that both of them are accessible only over a secured proxy, local network, or VPN. Setting that up is beyond the scope of this tutorial, but exercise caution. Bad security practices could lead to attackers gaining control over your node! It is your responsibility to follow proper security practices.

Monitoring Installer Script[​](#monitoring-installer-script "Direct link to heading")
-------------------------------------------------------------------------------------

In order to make node monitoring easier to install, we have made a script that does most of the work for you. To download and run the script, log into the machine the node runs on with a user that has administrator privileges and enter the following command:

```bash
wget -nd -m https://raw.githubusercontent.com/luxfi/lux-monitoring/main/grafana/monitoring-installer.sh ;\
chmod 755 monitoring-installer.sh;
```

This will download the script and make it executable.

Script itself is run multiple times with different arguments, each installing a different tool or part of the environment. To make sure it downloaded and set up correctly, begin by running:

```bash
./monitoring-installer.sh --help
```

It should display:

```bash
Usage: ./monitoring-installer.sh [--1|--2|--3|--4|--5|--help]

Options:
--help   Shows this message
--1      Step 1: Installs Prometheus
--2      Step 2: Installs Grafana
--3      Step 3: Installs node_exporter
--4      Step 4: Installs LuxGo Grafana dashboards
--5      Step 5: (Optional) Installs additional dashboards

Run without any options, script will download and install latest version of LuxGo dashboards.
```

Let's get to it.

Step 1: Set up Prometheus [​](#step-1-set-up-prometheus- "Direct link to heading")
----------------------------------------------------------------------------------

Run the script to execute the first step:

```bash
./monitoring-installer.sh --1
```

It should produce output something like this:

```bash
LuxGo monitoring installer
--------------------------------
STEP 1: Installing Prometheus

Checking environment...
Found arm64 architecture...
Prometheus install archive found:
https://github.com/prometheus/prometheus/releases/download/v2.31.0/prometheus-2.31.0.linux-arm64.tar.gz
Attempting to download:
https://github.com/prometheus/prometheus/releases/download/v2.31.0/prometheus-2.31.0.linux-arm64.tar.gz
prometheus.tar.gz                           100%[=========================================================================================>]  65.11M   123MB/s    in 0.5s
2021-11-05 14:16:11 URL:https://github-releases.githubusercontent.com/6838921/a215b0e7-df1f-402b-9541-a3ec9d431f76?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20211105%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211105T141610Z&X-Amz-Expires=300&X-Amz-Signature=72a8ae4c6b5cea962bb9cad242cb4478082594b484d6a519de58b8241b319d94&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=6838921&response-content-disposition=attachment%3B%20filename%3Dprometheus-2.31.0.linux-arm64.tar.gz&response-content-type=application%2Foctet-stream [68274531/68274531] -> "prometheus.tar.gz" [1]
...
```

You may be prompted to confirm additional package installs, do that if asked. Script run should end with instructions on how to check that Prometheus installed correctly. Let's do that, run:

```bash
sudo systemctl status prometheus
```

It should output something like:

```bash
● prometheus.service - Prometheus
Loaded: loaded (/etc/systemd/system/prometheus.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2021-11-12 11:38:32 UTC; 17min ago
Docs: https://prometheus.io/docs/introduction/overview/
Main PID: 548 (prometheus)
Tasks: 10 (limit: 9300)
Memory: 95.6M
CGroup: /system.slice/prometheus.service
└─548 /usr/local/bin/prometheus --config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/var/lib/prometheus --web.console.templates=/etc/prometheus/con>

Nov 12 11:38:33 ip-172-31-36-200 prometheus[548]: ts=2021-11-12T11:38:33.644Z caller=head.go:590 level=info component=tsdb msg="WAL segment loaded" segment=81 maxSegment=84
Nov 12 11:38:33 ip-172-31-36-200 prometheus[548]: ts=2021-11-12T11:38:33.773Z caller=head.go:590 level=info component=tsdb msg="WAL segment loaded" segment=82 maxSegment=84
```

Note the `active (running)` status (press `q` to exit). You can also check Prometheus web interface, available on `http://your-node-host-ip:9090/`

<Callout type="warn">
You may need to do `sudo ufw allow 9090/tcp` if the firewall is on, and/or adjust the security settings to allow connections to port 9090 if the node is running on a cloud instance. For AWS, you can look it up [here](/docs/nodes/run-a-node/on-third-party-services/amazon-web-services#create-a-security-group). If on public internet, make sure to only allow your IP to connect!
</Callout>

If everything is OK, let's move on.

Step 2: Install Grafana [​](#step-2-install-grafana- "Direct link to heading")
------------------------------------------------------------------------------

Run the script to execute the second step:

```bash
./monitoring-installer.sh --2
```

It should produce output something like this:

```bash
LuxGo monitoring installer
--------------------------------
STEP 2: Installing Grafana

OK
deb https://packages.grafana.com/oss/deb stable main
Hit:1 http://us-east-2.ec2.ports.ubuntu.com/ubuntu-ports focal InRelease
Get:2 http://us-east-2.ec2.ports.ubuntu.com/ubuntu-ports focal-updates InRelease [114 kB]
Get:3 http://us-east-2.ec2.ports.ubuntu.com/ubuntu-ports focal-backports InRelease [101 kB]
Hit:4 http://ppa.launchpad.net/longsleep/golang-backports/ubuntu focal InRelease
Get:5 http://ports.ubuntu.com/ubuntu-ports focal-security InRelease [114 kB]
Get:6 https://packages.grafana.com/oss/deb stable InRelease [12.1 kB]
...
```

To make sure it's running properly:

```bash
sudo systemctl status grafana-server
```

which should again show Grafana as `active`. Grafana should now be available at `http://your-node-host-ip:3000/` from your browser. Log in with username: admin, password: admin, and you will be prompted to set up a new, secure password. Do that.

<Callout type="warn">
You may need to do `sudo ufw allow 3000/tcp` if the firewall is on, and/or adjust the cloud instance settings to allow connections to port 3000. If on public internet, make sure to only allow your IP to connect!
</Callout>

Prometheus and Grafana are now installed, we're ready for the next step.

Step 3: Set up `node_exporter` [​](#step-3-set-up-node_exporter- "Direct link to heading")
------------------------------------------------------------------------------------------

In addition to metrics from LuxGo, let's set up monitoring of the machine itself, so we can check CPU, memory, network and disk usage and be aware of any anomalies. For that, we will use `node_exporter`, a Prometheus plugin.

Run the script to execute the third step:

```bash
./monitoring-installer.sh --3
```

The output should look something like this:

```bash
LuxGo monitoring installer
--------------------------------
STEP 3: Installing node_exporter

Checking environment...
Found arm64 architecture...
Downloading archive...
https://github.com/prometheus/node_exporter/releases/download/v1.2.2/node_exporter-1.2.2.linux-arm64.tar.gz
node_exporter.tar.gz                        100%[=========================================================================================>]   7.91M  --.-KB/s    in 0.1s
2021-11-05 14:57:25 URL:https://github-releases.githubusercontent.com/9524057/6dc22304-a1f5-419b-b296-906f6dd168dc?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20211105%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211105T145725Z&X-Amz-Expires=300&X-Amz-Signature=3890e09e58ea9d4180684d9286c9e791b96b0c411d8f8a494f77e99f260bdcbb&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=9524057&response-content-disposition=attachment%3B%20filename%3Dnode_exporter-1.2.2.linux-arm64.tar.gz&response-content-type=application%2Foctet-stream [8296266/8296266] -> "node_exporter.tar.gz" [1]
node_exporter-1.2.2.linux-arm64/LICENSE
```

Again, we check that the service is running correctly:

```bash
sudo systemctl status node_exporter
```

If the service is running, Prometheus, Grafana and `node_exporter` should all work together now. To check, in your browser visit Prometheus web interface on `http://your-node-host-ip:9090/targets`. You should see three targets enabled:

- Prometheus
- LuxGo
- `luxgo-machine`

Make sure that all of them have `State` as `UP`.

<Callout title="Note">
If you run your LuxGo node with TLS enabled on your API port, you will need to manually edit the `/etc/prometheus/prometheus.yml` file and change the `luxgo` job to look like this:

```yml
- job_name: "luxgo"
  metrics_path: "/ext/metrics"
  scheme: "https"
  tls_config:
    insecure_skip_verify: true
  static_configs:
    - targets: ["localhost:9650"]
```

Mind the spacing (leading spaces too)! You will need admin privileges to do that (use `sudo`). Restart Prometheus service afterwards with `sudo systemctl restart prometheus`.
</Callout>

All that's left to do now is to provision the data source and install the actual dashboards that will show us the data.

Step 4: Dashboards [​](#step-4-dashboards- "Direct link to heading")
--------------------------------------------------------------------

Run the script to install the dashboards:

```bash
./monitoring-installer.sh --4
```

It will produce output something like this:

```bash
LuxGo monitoring installer
--------------------------------

Downloading...
Last-modified header missing -- time-stamps turned off.
2021-11-05 14:57:47 URL:https://raw.githubusercontent.com/luxfi/lux-monitoring/master/grafana/dashboards/c_chain.json [50282/50282] -> "c_chain.json" [1]
FINISHED --2021-11-05 14:57:47--
Total wall clock time: 0.2s
Downloaded: 1 files, 49K in 0s (132 MB/s)
Last-modified header missing -- time-stamps turned off.
...
```

This will download the latest versions of the dashboards from GitHub and provision Grafana to load them, as well as defining Prometheus as a data source. It may take up to 30 seconds for the dashboards to show up. In your browser, go to: `http://your-node-host-ip:3000/dashboards`. You should see 7 Lux dashboards:

![Imported dashboards](/images/monitoring1.png)

Select 'Lux Main Dashboard' by clicking its title. It should load, and look similar to this:

![Main Dashboard](/images/monitoring2.png)

Some graphs may take some time to populate fully, as they need a series of data points in order to render correctly.

You can bookmark the main dashboard as it shows the most important information about the node at a glance. Every dashboard has a link to all the others as the first row, so you can move between them easily.

Step 5: Additional Dashboards (Optional)[​](#step-5-additional-dashboards-optional "Direct link to heading")
------------------------------------------------------------------------------------------------------------

Step 4 installs the basic set of dashboards that make sense to have on any node. Step 5 is for installing additional dashboards that may not be useful for every installation.

Currently, there is only one additional dashboard: Lux L1s. If your node is running any Lux L1s, you may want to add this as well. Do:

```bash
./monitoring-installer.sh --5
```

This will add the Lux L1s dashboard. It allows you to monitor operational data for any Lux L1 that is synced on the node. There is an Lux L1 switcher that allows you to switch between different Lux L1s. As there are many Lux L1s and not every node will have all of them, by default, it comes populated only with Spaces and WAGMI Lux L1s that exist on Testnet testnet:

![Lux L1s switcher](/images/monitoring3.png)

To configure the dashboard and add any Layer 1s that your node is syncing, you will need to edit the dashboard. Select the `dashboard settings` icon (image of a cog) in the upper right corner of the dashboard display and switch to `Variables` section and select the `subnet` variable. It should look something like this:

![Variables screen](/images/monitoring4.png)

The variable format is:

```bash
Subnet name:<BlockchainID>
```

and the separator between entries is a comma. Entries for Spaces and WAGMI look like:

```bash
Spaces (Testnet) : 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt, WAGMI (Testnet) : 2AM3vsuLoJdGBGqX2ibE8RGEq4Lg7g4bot6BT1Z7B9dH5corUD
```

After editing the values, press `Update` and then click `Save dashboard` button and confirm. Press the back arrow in the upper left corner to return to the dashboard. New values should now be selectable from the dropdown and data for the selected Lux L1 will be shown in the panels.

Updating[​](#updating "Direct link to heading")
-----------------------------------------------

Available node metrics are updated constantly, new ones are added and obsolete removed, so it is good a practice to update the dashboards from time to time, especially if you notice any missing data in panels. Updating the dashboards is easy, just run the script with no arguments, and it will refresh the dashboards with the latest available versions. Allow up to 30s for dashboards to update in Grafana.

If you added the optional extra dashboards (step 5), they will be updated as well.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Using the script to install node monitoring is easy, and it gives you insight into how your node is behaving and what's going on under the hood. Also, pretty graphs!

If you have feedback on this tutorial, problems with the script or following the steps, send us a message on [Discord](https://chat.avalabs.org/).


# Run Lux Node in Background (/docs/nodes/maintain/run-as-background-service)

---
title: Run Lux Node in Background
---

This page demonstrates how to set up a `luxgo.service` file to enable a manually deployed validator node to run in the background of a server instead of in the terminal directly.

Make sure that LuxGo is already installed on your machine.

Steps[​](#steps "Direct link to heading")
-----------------------------------------

### Testnet Testnet Config[​](#testnet-testnet-config "Direct link to heading")

Run this command in your terminal to create the `luxgo.service` file

```bash
sudo nano /etc/systemd/system/luxgo.service
```

Paste the following configuration into the `luxgo.service` file

Remember to modify the values of:

- _**user=**_
- _**group=**_
- _**WorkingDirectory=**_
- _**ExecStart=**_

For those that you have configured on your Server:

```toml
[Unit]
Description=Lux Node service
After=network.target

[Service]
User='YourUserHere'
Group='YourUserHere'
Restart=always
PrivateTmp=true
TimeoutStopSec=60s
TimeoutStartSec=10s
StartLimitInterval=120s
StartLimitBurst=5
WorkingDirectory=/Your/Path/To/luxgo
ExecStart=/Your/Path/To/luxgo/./luxgo \  
   --network-id=testnet \
   --api-metrics-enabled=true 

[Install]
WantedBy=multi-user.target
```

Press **Ctrl + X** then **Y** then **Enter** to save and exit.

Now, run:

```bash
sudo systemctl daemon-reload
```

### Mainnet Config[​](#mainnet-config "Direct link to heading")

Run this command in your terminal to create the `luxgo.service` file

```bash
sudo nano /etc/systemd/system/luxgo.service
```

Paste the following configuration into the `luxgo.service` file

```toml
[Unit]
Description=Lux Node service
After=network.target

[Service]
User='YourUserHere'
Group='YourUserHere'
Restart=always
PrivateTmp=true
TimeoutStopSec=60s
TimeoutStartSec=10s
StartLimitInterval=120s
StartLimitBurst=5
WorkingDirectory=/Your/Path/To/luxgo
ExecStart=/Your/Path/To/luxgo/./luxgo \
   --api-metrics-enabled=true

[Install]
WantedBy=multi-user.target
```

Press **Ctrl + X** then **Y** then **Enter** to save and exit.

Now, run:

```bash
sudo systemctl daemon-reload
```

Start the Node[​](#start-the-node "Direct link to heading")
-----------------------------------------------------------

This command makes your node start automatically in case of a reboot, run it:

```bash
sudo systemctl enable luxgo
```

To start the node, run:

```bash
sudo systemctl start luxgo
sudo systemctl status luxgo
```

Output:

```bash
socopower@lux-node-01:~$ sudo systemctl status luxgo
● luxgo.service - Lux Node service
     Loaded: loaded (/etc/systemd/system/luxgo.service; enabled; vendor p>
     Active: active (running) since Tue 2023-08-29 23:14:45 UTC; 5h 46min ago
   Main PID: 2226 (luxgo)
      Tasks: 27 (limit: 38489)
     Memory: 8.7G
        CPU: 5h 50min 31.165s
     CGroup: /system.slice/luxgo.service
             └─2226 /usr/local/bin/luxgo/./luxgo --network-id=testnet

Aug 30 03:02:50 lux-node-01 luxgo[2226]: INFO [08-30|03:02:50.685] >
Aug 30 03:02:51 lux-node-01 luxgo[2226]: INFO [08-30|03:02:51.185] >
Aug 30 03:03:09 lux-node-01 luxgo[2226]: [08-30|03:03:09.380] INFO >
Aug 30 03:03:23 lux-node-01 luxgo[2226]: [08-30|03:03:23.983] INFO >
Aug 30 03:05:15 lux-node-01 luxgo[2226]: [08-30|03:05:15.192] INFO >
Aug 30 03:05:15 lux-node-01 luxgo[2226]: [08-30|03:05:15.237] INFO >
Aug 30 03:05:15 lux-node-01 luxgo[2226]: [08-30|03:05:15.238] INFO >
Aug 30 03:05:19 lux-node-01 luxgo[2226]: [08-30|03:05:19.809] INFO >
Aug 30 03:05:19 lux-node-01 luxgo[2226]: [08-30|03:05:19.809] INFO >
Aug 30 05:00:47 lux-node-01 luxgo[2226]: [08-30|05:00:47.001] INFO
```

To see the synchronization process, you can run the following command:

```bash
sudo journalctl -fu luxgo
```


# Upgrade Your LuxGo Node (/docs/nodes/maintain/upgrade)

---
title: Upgrade Your LuxGo Node
---

Backup Your Node[​](#backup-your-node "Direct link to heading")
---------------------------------------------------------------

Before upgrading your node, it is recommended you backup your staker files which are used to identify your node on the network. In the default installation, you can copy them by running following commands:

```bash
cd
cp ~/.luxgo/staking/staker.crt .
cp ~/.luxgo/staking/staker.key .
```

Then download `staker.crt` and `staker.key` files and keep them somewhere safe and private. If anything happens to your node or the machine node runs on, these files can be used to fully recreate your node.

If you use your node for development purposes and have keystore users on your node, you should back up those too.

Node Installed Using the Installer Script[​](#node-installed-using-the-installer-script "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------

If you installed your node using the [installer script](/docs/nodes/run-a-node/using-install-script/installing-lux-go), to upgrade your node, just run the installer script again.

```bash
./luxgo-installer.sh
```

It will detect that you already have LuxGo installed:

```bash
LuxGo installer
---------------------
Preparing environment...
Found 64bit Intel/AMD architecture...
Found LuxGo systemd service already installed, switching to upgrade mode.
Stopping service...
```

It will then upgrade your node to the latest version, and after it's done, start the node back up, and print out the information about the latest version:

```bash
Node upgraded, starting service...
New node version:
lux/1.1.1 [network=mainnet, database=v1.0.0, commit=f76f1fd5f99736cf468413bbac158d6626f712d2]
Done!
```

And that is it, your node is upgraded to the latest version.

If you installed your node manually, proceed with the rest of the tutorial.

Stop the Old Node Version[​](#stop-the-old-node-version "Direct link to heading")
---------------------------------------------------------------------------------

After the backup is secured, you may start upgrading your node. Begin by stopping the currently running version.

### Node Running from Terminal[​](#node-running-from-terminal "Direct link to heading")

If your node is running in a terminal stop it by pressing `ctrl+c`.

### Node Running as a Service[​](#node-running-as-a-service "Direct link to heading")

If your node is running as a service, stop it by entering: `sudo systemctl stop luxgo.service`

(your service may be named differently, `lux.service`, or similar)

### Node Running in Background[​](#node-running-in-background "Direct link to heading")

If your node is running in the background (by running with `nohup`, for example) then find the process running the node by running `ps aux | grep lux`. This will produce output like:

```bash
ubuntu  6834  0.0  0.0   2828   676 pts/1    S+   19:54   0:00 grep lux
ubuntu  2630 26.1  9.4 2459236 753316 ?      Sl   Dec02 1220:52 /home/ubuntu/build/luxgo
```

In this example, second line shows information about your node. Note the process id, in this case, `2630`. Stop the node by running `kill -2 2630`.

Now we are ready to download the new version of the node. You can either download the source code and then build the binary program, or you can download the pre-built binary. You don't need to do both.

Downloading pre-built binary is easier and recommended if you're just looking to run your own node and stake on it.

Building the node [from source](/docs/nodes/maintain/upgrade#build-from-source) is recommended if you're a developer looking to experiment and build on Lux.

Download Pre-Built Binary[​](#download-pre-built-binary "Direct link to heading")
---------------------------------------------------------------------------------

If you want to download a pre-built binary instead of building it yourself, go to our [releases page](https://github.com/luxfi/luxgo/releases), and select the release you want (probably the latest one.)

<Callout title="Note">
If you have a node, you can subscribe to the [lux notify service](/docs/nodes/maintain/enroll-in-lux-notify) with your node ID to be notified about new releases.

In addition, or if you don't have a node ID, you can get release notifications from github. To do so, you can go to our [repository](https://github.com/luxfi/luxgo) and look on the top-right corner for the **Watch** option. After you click on it, select **Custom**, and then **Releases**. Press **Apply** and it is done.
</Callout>

Under `Assets`, select the appropriate file.

For MacOS:  
Download: `luxgo-macos-<VERSION>.zip`  
Unzip: `unzip luxgo-macos-<VERSION>.zip`  
The resulting folder, `luxgo-<VERSION>`, contains the binaries.

For Linux on PCs or cloud providers:  
Download: `luxgo-linux-amd64-<VERSION>.tar.gz`  
Unzip: `tar -xvf luxgo-linux-amd64-<VERSION>.tar.gz`  
The resulting folder, `luxgo-<VERSION>-linux`, contains the binaries.

For Linux on Arm64-based computers:  
Download: `luxgo-linux-arm64-<VERSION>.tar.gz`  
Unzip: `tar -xvf luxgo-linux-arm64-<VERSION>.tar.gz`  
The resulting folder, `luxgo-<VERSION>-linux`, contains the binaries.

You are now ready to run the new version of the node.

### Running the Node from Terminal[​](#running-the-node-from-terminal "Direct link to heading")

If you are using the pre-built binaries on MacOS:

```bash
./luxgo-<VERSION>/build/luxgo
```

If you are using the pre-built binaries on Linux:

```bash
./luxgo-<VERSION>-linux/luxgo
```

Add `nohup` at the start of the command if you want to run the node in the background.

### Running the Node as a Service[​](#running-the-node-as-a-service "Direct link to heading")

If you're running the node as a service, you need to replace the old binaries with the new ones.

```bash
cp -r luxgo-<VERSION>-linux/* <DIRECTORY_WITH_OLD_BINARIES>
```

and then restart the service with: `sudo systemctl start luxgo.service`.

Build from Source[​](#build-from-source "Direct link to heading")
-----------------------------------------------------------------

First clone our GitHub repo (you can skip this step if you've done this before):

```bash
git clone https://github.com/luxfi/luxgo.git
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:luxfi/luxgo.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

Then move to the LuxGo directory:

```bash
cd luxgo
```

Pull the latest code:

```bash
git pull
```

<Callout title="Note">
If the master branch has not been updated with the latest release tag, you can get to it directly via first running `git fetch --all --tags` and then `git checkout --force tags/<tag>` (where `<tag>` is the latest release tag; for example `v1.3.2`) instead of `git pull`.

Note that your local copy will be in a 'detached HEAD' state, which is not an issue if you do not make changes to the source that you want push back to the repository (in which case you should check out to a branch and to the ordinary merges).

Note also that the `--force` flag will disregard any local changes you might have.
</Callout>

Check that your local code is up to date. Do:

```bash
git rev-parse HEAD
```

and check that the first 7 characters printed match the Latest commit field on our [GitHub](https://github.com/luxfi/luxgo).

<Callout title="Note">
If you used the `git checkout tags/<tag>` then these first 7 characters should match commit hash of that tag.
</Callout>

Now build the binary: 
```bash
./scripts/build.sh
```

This should print: `Build Successful`

You can check what version you're running by doing:

```bash
./build/luxgo --version
```

You can run your node with:

```bash
./build/luxgo
```

# How to Stake (/docs/primary-network/validate/how-to-stake)

---
title: How to Stake
description: Learn how to stake on Lux.
---

Staking Parameters on Lux[​](#staking-parameters-on-lux "Direct link to heading")
---------------------------------------------------------------------------------------------

When a validator is done validating the [Primary Network](http://support.avalabs.org/en/articles/4135650-what-is-the-primary-network), it receives back the LUX tokens it staked. It may receive a reward for helping to secure the network. A validator only receives a [validation reward](http://support.avalabs.org/en/articles/4587396-what-are-validator-staking-rewards) if it is sufficiently responsive and correct during the time it validates. Read the [Lux token white paper](https://www.avalabs.org/whitepapers) to learn more about LUX and the mechanics of staking.

<Callout type="warn">
Staking rewards are sent to your wallet address at the end of the staking term **as long as all of these parameters are met**.
</Callout>

### Mainnet[​](#mainnet "Direct link to heading")

- The minimum amount that a validator must stake is 2,000 LUX
- The minimum amount that a delegator must delegate is 25 LUX
- The minimum amount of time one can stake funds for validation is 2 weeks
- The maximum amount of time one can stake funds for validation is 1 year
- The minimum amount of time one can stake funds for delegation is 2 weeks
- The maximum amount of time one can stake funds for delegation is 1 year
- The minimum delegation fee rate is 2%
- The maximum weight of a validator (their own stake + stake delegated to them) is the minimum of 3 million LUX and 5 times the amount the validator staked. For example, if you staked 2,000 LUX to become a validator, only 8000 LUX can be delegated to your node total (not per delegator)

A validator will receive a staking reward if they are online and response for more than 80% of their validation period, as measured by a majority of validators, weighted by stake. **You should aim for your validator be online and responsive 100% of the time.**

You can call API method `info.uptime` on your node to learn its weighted uptime and what percentage of the network currently thinks your node has an uptime high enough to receive a staking reward. See [here.](/docs/rpcs/other/info-rpc#infouptime) You can get another opinion on your node's uptime from Lux's [Validator Health dashboard](https://stats.lux.network/dashboard/validator-health-check/). If your reported uptime is not close to 100%, there may be something wrong with your node setup, which may jeopardize your staking reward. If this is the case, please see [here](#why-is-my-uptime-low) or contact us on [Discord](https://discord.gg/lux/) so we can help you find the issue. Note that only checking the uptime of your validator as measured by non-staking nodes, validators with small stake, or validators that have not been online for the full duration of your validation period can provide an inaccurate view of your node's true uptime.

### Testnet Testnet[​](#testnet-testnet "Direct link to heading")

On Testnet Testnet, all staking parameters are the same as those on Mainnet except the following ones:

- The minimum amount that a validator must stake is 1 LUX
- The minimum amount that a delegator must delegate is 1 LUX
- The minimum amount of time one can stake funds for validation is 24 hours
- The minimum amount of time one can stake funds for delegation is 24 hours

Validators[​](#validators "Direct link to heading")
---------------------------------------------------

**Validators** secure Lux, create new blocks, and process transactions. To achieve consensus, validators repeatedly sample each other. The probability that a given validator is sampled is proportional to its stake.

When you add a node to the validator set, you specify:

- Your node's ID
- Your node's BLS key and BLS signature
- When you want to start and stop validating
- How many LUX you are staking
- The address to send any rewards to
- Your delegation fee rate (see below)

<Callout title="Note">
The minimum amount that a validator must stake is 2,000 LUX.
</Callout>

<Callout type="warn">
Note that once you issue the transaction to add a node as a validator, there is no way to change the parameters. **You can't remove your stake early or change the stake amount, node ID, or reward address.**

Please make sure you're using the correct values in the API calls below. If you're not sure, ask for help on [Discord](https://discord.gg/lux/). If you want to add more tokens to your own validator, you can delegate the tokens to this node - but you cannot increase the base validation amount (so delegating to yourself goes against your delegation cap).
</Callout>

### Running a Validator[​](#running-a-validator "Direct link to heading")

If you're running a validator, it's important that your node is well connected to ensure that you receive a reward.

When you issue the transaction to add a validator, the staked tokens and transaction fee (which is 0) are deducted from the addresses you control. When you are done validating, the staked funds are returned to the addresses they came from. If you earned a reward, it is sent to the address you specified when you added yourself as a validator.

#### Allow API Calls[​](#allow-api-calls "Direct link to heading")

To make API calls to your node from remote machines, allow traffic on the API port (`9650` by default), and run your node with argument `--http-host=`

You should disable all APIs you will not use via command-line arguments. You should configure your network to only allow access to the API port from trusted machines (for example, your personal computer.)

#### Why Is My Uptime Low?[​](#why-is-my-uptime-low "Direct link to heading")

Every validator on Lux keeps track of the uptime of other validators. Every validator has a weight (that is the amount staked on it.) The more weight a validator has, the more influence they have when validators vote on whether your node should receive a staking reward. You can call API method `info.uptime` on your node to learn its weighted uptime and what percentage of the network stake currently thinks your node has an uptime high enough to receive a staking reward.

You can also see the connections a node has by calling `info.peers`, as well as the uptime of each connection. **This is only one node's point of view**. Other nodes may perceive the uptime of your node differently. Just because one node perceives your uptime as being low does not mean that you will not receive staking rewards.

If your node's uptime is low, make sure you're setting config option `--public-ip=[NODE'S PUBLIC IP]` and that your node can receive incoming TCP traffic on port 9651.

#### Secret Management[​](#secret-management "Direct link to heading")

The only secret that you need on your validating node is its Staking Key, the TLS key that determines your node's ID. The first time you start a node, the Staking Key is created and put in `$HOME/.luxgo/staking/staker.key`. You should back up this file (and `staker.crt`) somewhere secure. Losing your Staking Key could jeopardize your validation reward, as your node will have a new ID.

You do not need to have LUX funds on your validating node. In fact, it's best practice to **not** have a lot of funds on your node. Almost all of your funds should be in "cold" addresses whose private key is not on any computer.

#### Monitoring[​](#monitoring "Direct link to heading")

Follow this [tutorial](/docs/nodes/maintain/monitoring) to learn how to monitor your node's uptime, general health, etc.

### Reward Formula[​](#reward-formula "Direct link to heading")

Consider a validator which stakes a $Stake$ amount of Lux for $StakingPeriod$ seconds.

Assume that at the start of the staking period there is a $Supply$ amount of Lux in the Primary Network.

The maximum amount of Lux is $MaximumSupply$ . Then at the end of its staking period, a responsive validator receives a reward calculated as follows:

$$
Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{Staking Period}{Minting Period} \times EffectiveConsumptionRate
$$

where,

$$
EffectiveConsumptionRate = 
$$

$$
\frac{MinConsumptionRate}{PercentDenominator} \times \left(1- \frac{Staking Period}{Minting Period}\right) + \frac{MaxConsumptionRate}{PercentDenominator} \times \frac{Staking Period}{Minting Period}
$$

<Callout title="Note">
Note that $StakingPeriod$ is the staker's entire staking period, not just the staker's uptime, that is the aggregated time during which the staker has been responsive. The uptime comes into play only to decide whether a staker should be rewarded; to calculate the actual reward, only the staking period duration is taken into account.
</Callout>

$EffectiveConsumptionRate$ is a linear combination of $MinConsumptionRate$ and $MaxConsumptionRate$.
$MinConsumptionRate$ and $MaxConsumptionRate$ bound $EffectiveConsumptionRate$ because 

$$
MinConsumptionRate \leq EffectiveConsumptionRate \leq MaxConsumptionRate
$$

The larger $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MaxConsumptionRate$.

A staker achieves the maximum reward for its stake if $StakingPeriod$ = $Minting Period$.

The reward is:

$$
Max Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{MaxConsumptionRate}{PercentDenominator}
$$

Delegators[​](#delegators "Direct link to heading")
---------------------------------------------------

A delegator is a token holder, who wants to participate in staking, but chooses to trust an existing validating node through delegation.

When you delegate stake to a validator, you specify:

- The ID of the node you're delegating to
- When you want to start/stop delegating stake (must be while the validator is validating)
- How many LUX you are staking
- The address to send any rewards to

<Callout title="Note">
The minimum amount that a delegator must delegate is 25 LUX.
</Callout>

<Callout type="warn">
Note that once you issue the transaction to add your stake to a delegator, there is no way to change the parameters. **You can't remove your stake early or change the stake amount, node ID, or reward address.** If you're not sure, ask for help on [Discord](https://discord.gg/lux/).
</Callout>

### Delegator Rewards[​](#delegator-rewards "Direct link to heading")

If the validator that you delegate tokens to is sufficiently correct and responsive, you will receive a reward when you are done delegating. Delegators are rewarded according to the same function as validators. However, the validator that you delegate to keeps a portion of your reward specified by the validator's delegation fee rate.

When you issue the transaction to delegate tokens, the staked tokens and transaction fee are deducted from the addresses you control. When you are done delegating, the staked tokens are returned to your address. If you earned a reward, it is sent to the address you specified when you delegated tokens. Rewards are sent to delegators right after the delegation ends with the return of staked tokens, and before the validation period of the node they're delegating to is complete.

FAQ[​](#faq "Direct link to heading")
-------------------------------------

### Is There a Tool to Check the Health of a Validator?[​](#is-there-a-tool-to-check-the-health-of-a-validator "Direct link to heading")

Yes, just enter your node's ID in the Lux Stats [Validator Health Dashboard](https://stats.lux.network/dashboard/validator-health-check/?nodeid=NodeID-Jp4dLMTHd6huttS1jZhqNnBN9ZMNmTmWC).

### How Is It Determined Whether a Validator Receives a Staking Reward?[​](#how-is-it-determined-whether-a-validator-receives-a-staking-reward "Direct link to heading")

When a node leaves the validator set, the validators vote on whether the leaving node should receive a staking reward or not. If a validator calculates that the leaving node was responsive for more than the required uptime (currently 80%), the validator will vote for the leaving node to receive a staking reward. Otherwise, the validator will vote that the leaving node should not receive a staking reward. The result of this vote, which is weighted by stake, determines whether the leaving node receives a reward or not.

Each validator only votes "yes" or "no." It does not share its data such as the leaving node's uptime.

Each validation period is considered separately. That is, suppose a node joins the validator set, and then leaves. Then it joins and leaves again. The node's uptime during its first period in the validator set does not affect the uptime calculation in the second period, hence, has no impact on whether the node receives a staking reward for its second period in the validator set.

### How Are Delegation Fees Distributed To Validators?[​](#how-are-delegation-fees-distributed-to-validators "Direct link to heading")

If a validator is online for 80% of a delegation period, they receive a % of the reward (the fee) earned by the delegator. The Platform-Chain used to distribute this fee as a separate UTXO per delegation period. After the [Cortina Activation](https://medium.com/luxlux/cortina-x-chain-linearization-a1d9305553f6), instead of sending a fee UTXO for each successful delegation period, fees are now batched during a node's entire validation period and are distributed when it is unstaked.

### Error: Couldn't Issue TX: Validator Would Be Over Delegated[​](#error-couldnt-issue-tx-validator-would-be-over-delegated "Direct link to heading")

This error occurs whenever the delegator can not delegate to the named validator. This can be caused by the following.

- The delegator `startTime` is before the validator `startTime`
- The delegator `endTime` is after the validator `endTime`
- The delegator weight would result in the validator total weight exceeding its maximum weight

# Turn Node Into Validator (/docs/primary-network/validate/node-validator)

---
title: Turn Node Into Validator
description: This tutorial will show you how to add a node to the validator set of Primary Network on Lux.
---

## Introduction

The [Primary Network](/docs/primary-network)
is inherent to the Lux platform and validates Lux's built-in
blockchains. In this
tutorial, we'll add a node to the Primary Network on Lux.

The Platform-Chain manages metadata on Lux. This includes tracking which nodes
are in which Lux L1s, which blockchains exist, and which Lux L1s are validating
which blockchains. To add a validator, we'll issue
[transactions](http://support.avalabs.org/en/articles/4587384-what-is-a-transaction)
to the Platform-Chain.

<Callout type="warn">
Note that once you issue the transaction to add a node as a validator, there is
no way to change the parameters. **You can't remove your stake early or change
the stake amount, node ID, or reward address.** Please make sure you're using
the correct values in the API calls below. If you're not sure, feel free to join
our [Discord](https://chat.avalabs.org/) to ask questions.
</Callout>

## Requirements

You've completed [Run an Lux Node](/docs/nodes/run-a-node/from-source) and are familiar with
[Lux's architecture](/docs/primary-network). In this
tutorial, we use [LuxJS](/docs/tooling/lux-sdk) and
[Lux's Postman collection](/docs/tooling/lux-postman) 
to help us make API calls.

In order to ensure your node is well-connected, make sure that your node can
receive and send TCP traffic on the staking port (`9651` by default) and your node
has a public IP address(it's optional to set --public-ip=[YOUR NODE'S PUBLIC IP HERE]
when executing the LuxGo binary, as by default, the node will attempt to perform
NAT traversal to get the node's IP according to its router). Failing to do either of
these may jeopardize your staking reward.

## Add a Validator with Core extension

First, we show you how to add your node as a validator by using [Core web](https://core.app).

### Retrieve the Node ID, the BLS signature and the BLS key

Get this info by calling [`info.getNodeID`](/docs/rpcs/other/info-rpc#infogetnodeid):

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json' 127.0.0.1:9650/ext/info
```

The response has your node's ID, the BLS key (public key) and the BLS signature (proof of possession):

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
    "nodePOP": {
      "publicKey": "0x8f95423f7142d00a48e1014a3de8d28907d420dc33b3052a6dee03a3f2941a393c2351e354704ca66a3fc29870282e15",
      "proofOfPossession": "0x86a3ab4c45cfe31cae34c1d06f212434ac71b1be6cfe046c80c162e057614a94a5bc9f1ded1a7029deb0ba4ca7c9b71411e293438691be79c2dbf19d1ca7c3eadb9c756246fc5de5b7b89511c7d7302ae051d9e03d7991138299b5ed6a570a98"
    }
  },
  "id": 1
}
```

### Add as a Validator

Connect [Core extension](https://core.app) to [Core web](https://core.app), and go the 'Staking' tab. 
Here, choose 'Validate' from the menu.

Fill out the staking parameters. They are explained in more detail in [this doc](/docs/primary-network/validate/how-to-stake). When you've 
filled in all the staking parameters and double-checked them, click `Submit Validation`. Make sure the staking period is at
least 2 weeks, the delegation fee rate is at least 2%, and you're staking at
least 2,000 LUX on Mainnet (1 LUX on Testnet Testnet). A full guide about this can be found 
[here](https://support.lux.network/en/articles/8117267-core-web-how-do-i-validate-in-core-stake).

You should see a success message, and your balance should be updated.

Go back to the `Stake` tab, and you'll see here an overview of your validation,
with information like the amount staked, staking time, and more.

![Staking Overview](/images/node-validator.png)

Calling
[`platform.getPendingValidators`](/docs/rpcs/p-chain#platformgetpendingvalidators)
verifies that your transaction was accepted. Note that this API call should be
made before your node's validation start time, otherwise, the return will not
include your node's id as it is no longer pending.

You can also call
[`platform.getCurrentValidators`](/docs/rpcs/p-chain#platformgetcurrentvalidators)
to check that your node's id is included in the response.

That's it!

## Add a Validator with LuxJS

We can also add a node to the validator set using [LuxJS](/docs/tooling/lux-sdk).

### Install LuxJS

To use LuxJS, you can clone the repo:

```bash
git clone https://github.com/luxfi/luxjs.git
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:luxfi/luxjs.git`

You can find more about SSH and how to use it
[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

or add it to an existing project:

```bash
yarn add @luxfi/luxjs
```

For this tutorial we will use [`ts-node`](https://www.npmjs.com/package/ts-node)
to run the example scripts directly from an LuxJS directory.

### Testnet Workflow

In this section, we will use Testnet Testnet to show how to add a node to the validator set.

Open your LuxJS directory and select the
[**`examples/p-chain`**](https://github.com/luxfi/luxjs/tree/master/examples/p-chain)
folder to view the source code for the examples scripts.

We will use the
[**`validate.ts`**](https://github.com/luxfi/luxjs/blob/master/examples/p-chain/validate.ts)
script to add a validator.

#### Add Necessary Environment Variables

Locate the `.env.example` file at the root of LuxJS, and remove `.example`
from the title. Now, this will be the `.env` file for global variables.

Add the private key and the Platform-Chain address associated with it.
The API URL is already set to Testnet (`https://api.lux-test.network/`).

![env Variables](/images/validator-luxjs-1.png)

#### Retrieve the Node ID, the BLS signature and the BLS key

Get this info by calling [`info.getNodeID`](/docs/rpcs/other/info-rpc#infogetnodeid):

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json' 127.0.0.1:9650/ext/info
```

The response has your node's ID, the BLS key (public key) and the BLS signature (proof of possession):

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-JXJNyJXhgXzvVGisLkrDiZvF938zJxnT5",
    "nodePOP": {
      "publicKey": "0xb982b485916c1d74e3b749e7ce49730ac0e52d28279ce4c5c989d75a43256d3012e04b1de0561276631ea6c2c8dc4429",
      "proofOfPossession": "0xb6cdf3927783dba3245565bd9451b0c2a39af2087fdf401956489b42461452ec7639b9082195b7181907177b1ea09a6200a0d32ebbc668d9c1e9156872633cfb7e161fbd0e75943034d28b25ec9d9cdf2edad4aaf010adf804af8f6d0d5440c5"
    }
  },
  "id": 1
}
```

#### Fill in the Node ID, the BLS signature and the BLS key

After retrieving this data, go to `examples/p-chain/validate.ts`.

Replace the `nodeID`, `blsPublicKey` and `blsSignature` with your 
own node's values.

![Replaced values](/images/validator-luxjs-2.png)

#### Settings for Validation

Next we need to specify the node's validation period and delegation fee.

#### Validation Period

The validation period is set by default to 21 days, the start date
being the date and time the transaction is issued. The start date
cannot be modified.

The end date can be adjusted in the code.

Let's say we want the validation period to end after 50 days.
You can achieve this by adding the number of desired days to
`endTime.getDate()`, in this case `50`.

```ts
// move ending date 50 days into the future
endTime.setDate(endTime.getDate() + 50);
```

Now let's say you want the staking period to end on a specific 
date and time, for example May 15, 2024, at 11:20 AM.
It can be achieved as shown in the code below.

```ts
const startTime = await new PVMApi().getTimestamp();
const startDate = new Date(startTime.timestamp);
const start = BigInt(startDate.getTime() / 1000);

// Set the end time to a specific date and time
const endTime = new Date('2024-05-15T11:20:00'); // May 15, 2024, at 11:20 AM
const end = BigInt(endTime.getTime() / 1000);
```

#### Delegation Fee Rate

Lux allows for delegation of stake. This parameter is the percent fee this
validator charges when others delegate stake to them. For example, if
`delegationFeeRate` is `10` and someone delegates to this validator, then when
the delegation period is over, 10% of the reward goes to the validator and the
rest goes to the delegator, if this node meets the validation reward
requirements.

The delegation fee on LuxJS is set `20`. To change this, you need
to provide the desired fee percent as a parameter to `newAddPermissionlessValidatorTx`,
which is by default `1e4 * 20`.

For example, if you'd want it to be `10`, the updated code would look like this:

```ts
const tx = newAddPermissionlessValidatorTx(
  context,
  utxos,
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  nodeID,
  PrimaryNetworkID.toString(),
  start,
  end,
  BigInt(1e9),
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  1e4 * 10, // delegation fee, replaced 20 with 10
  undefined,
  1,
  0n,
  blsPublicKey,
  blsSignature,
);
```

#### Stake Amount

Set the amount being locked for validation when calling
`newAddPermissionlessValidatorTx` by replacing `weight` with a number
in the unit of nLUX. For example, `2 LUX` would be `2e9 nLUX`.

```ts
const tx = newAddPermissionlessValidatorTx(
  context,
  utxos,
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  nodeID,
  PrimaryNetworkID.toString(),
  start,
  end,
  BigInt(2e9), // the amount to stake
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  1e4 * 10,
  undefined,
  1,
  0n,
  blsPublicKey,
  blsSignature,
);
```

#### Execute the Code

Now that we have made all of the necessary changes to the example script, it's
time to add a validator to the Testnet Network.

Run the command:

```bash
node --loader ts-node/esm examples/p-chain/validate.ts
```

The response:

```bash
laviniatalpas@Lavinias-MacBook-Pro luxjs % node --loader ts-node/esm examples/p-chain/validate.ts
(node:87616) ExperimentalWarning: `--experimental-loader` may be removed in the future; instead use `register()`:
--import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("ts-node/esm", pathToFileURL("./"));'
(Use `node --trace-warnings ...` to show where the warning was created)
{ txID: 'RVe3CFRieRbBvKXKPu24Zbt1QehdyGVT6X4tPWVBeLPX3Ab8' }
```

We can check the transaction's status by running the example script with
[`platform.getTxStatus`](/docs/rpcs/p-chain#platformgettxstatus)
or looking up the validator directly on the 
[explorer](https://subnets-test.lux.network/validators/NodeID-JXJNyJXhgXzvVGisLkrDiZvF938zJxnT5).

![Added Validator](/images/validator-luxjs-3.png)

### Mainnet Workflow

The Testnet workflow above can be adapted to Mainnet with the following modifications:

- `LUX_PUBLIC_URL` should be `https://api.lux.network/`.
- `P_CHAIN_ADDRESS` should be the Mainnet Platform-Chain address.
- Set the correct amount to stake.
- The `blsPublicKey`, `blsSignature` and `nodeID` need to be the ones for your Mainnet Node.


# Rewards Formula (/docs/primary-network/validate/rewards-formula)

---
title: Rewards Formula
description: Learn about the rewards formula for the Lux Primary Network validator
---

## Primary Network Validator Rewards

Consider a Primary Network validator which stakes a $Stake$ amount of `LUX` for $StakingPeriod$ seconds.

The potential reward is calculated **at the beginning of the staking period**. At the beginning of the staking period there is a $Supply$ amount of `LUX` in the network. The maximum amount of `LUX` is $MaximumSupply$. At the end of its staking period, a responsive Primary Network validator receives a reward.

$$
Potential Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{Staking Period}{Minting Period} \times EffectiveConsumptionRate
$$

where,

$$
MaximumSupply - Supply = \text{the number of LUX tokens left to emit in the network}
$$

$$
\frac{Stake}{Supply} = \text{the individual's stake as a percentage of all available LUX tokens in the network}
$$

$$
\frac{StakingPeriod}{MintingPeriod} = \text{time tokens are locked up divided by the $MintingPeriod$}
$$

$$
\text{$MintingPeriod$ is one year as configured by the network).}
$$

$$
EffectiveConsumptionRate =
$$

$$
\frac{MinConsumptionRate}{PercentDenominator} \times \left(1- \frac{Staking Period}{Minting Period}\right) + \frac{MaxConsumptionRate}{PercentDenominator} \times \frac{Staking Period}{Minting Period}
$$

Note that $StakingPeriod$ is the staker's entire staking period, not just the staker's uptime, that is the aggregated time during which the staker has been responsive. The uptime comes into play only to decide whether a staker should be rewarded; to calculate the actual reward only the staking period duration is taken into account.

$EffectiveConsumptionRate$ is the rate at which the Primary Network validator is rewarded based on $StakingPeriod$ selection.

$MinConsumptionRate$ and $MaxConsumptionRate$ bound $EffectiveConsumptionRate$:

$$
MinConsumptionRate \leq EffectiveConsumptionRate \leq MaxConsumptionRate
$$

The larger $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MaxConsumptionRate$. The smaller $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MinConsumptionRate$.

A staker achieves the maximum reward for its stake if $StakingPeriod$ = $Minting Period$. The reward is:

$$
Max Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{MaxConsumptionRate}{PercentDenominator}
$$

Note that this formula is the same as the reward formula at the top of this section because $EffectiveConsumptionRate$ = $MaxConsumptionRate$.

For reference, you can find all the Primary network parameters in [the section below](#primary-network-parameters-on-mainnet).

## Delegators Weight Checks

There are bounds set of the maximum amount of delegators' stake that a validator can receive.

The maximum weight $MaxWeight$ a validator $Validator$ can have is:

$$
MaxWeight = \min(Validator.Weight \times MaxValidatorWeightFactor, MaxValidatorStake)
$$

where $MaxValidatorWeightFactor$ and $MaxValidatorStake$ are the Primary Network Parameters described above.

A delegator won't be added to a validator if the combination of their weights and all other validator's delegators' weight is larger than $MaxWeight$. Note that this must be true at any point in time.

Note that setting $MaxValidatorWeightFactor$ to 1 disables delegation since the $MaxWeight = Validator.Weight$.

## Notes on Percentages

`PercentDenominator = 1_000_000` is the denominator used to calculate percentages.

It allows you to specify percentages up to 4 digital positions. To denominate your percentage in `PercentDenominator` just multiply it by `10_000`. For example:

- `100%` corresponds to `100 * 10_000 = 1_000_000`
- `1%` corresponds to `1* 10_000 = 10_000`
- `0.02%` corresponds to `0.002 * 10_000 = 200`
- `0.0007%` corresponds to `0.0007 * 10_000 = 7`

## Primary Network Parameters on Mainnet

For reference we list below the Primary Network parameters on Mainnet:

- `AssetID = Lux`
- `InitialSupply = 240_000_000 Lux`
- `MaximumSupply = 720_000_000 Lux`.
- `MinConsumptionRate = 0.10 * reward.PercentDenominator`.
- `MaxConsumptionRate = 0.12 * reward.PercentDenominator`.
- `Minting Period = 365 * 24 * time.Hour`.
- `MinValidatorStake = 2_000 Lux`.
- `MaxValidatorStake = 3_000_000 Lux`.
- `MinStakeDuration = 2 * 7 * 24 * time.Hour`.
- `MaxStakeDuration = 365 * 24 * time.Hour`.
- `MinDelegationFee = 20000`, that is `2%`.
- `MinDelegatorStake = 25 Lux`.
- `MaxValidatorWeightFactor = 5`. This is a platformVM parameter rather than a genesis one, so it's shared across networks.
- `UptimeRequirement = 0.8`, that is `80%`.

### Interactive Graph

The graph below demonstrates the reward as a function of the length of time
staked. The x-axis depicts $\frac{StakingPeriod}{MintingPeriod}$ as a percentage
while the y-axis depicts $Reward$ as a percentage of $MaximumSupply - Supply$,
the amount of tokens left to be emitted.

Graph variables correspond to those defined above:

- `h` (high) = $MaxConsumptionRate$
- `l` (low) = $MinConsumptionRate$
- `s` = $\frac{Stake}{Supply}$

<iframe src="https://www.desmos.com/calculator/uqtank2gcn" width="100%" height="400px"></iframe>



# Validate vs. Delegate (/docs/primary-network/validate/validate-vs-delegate)

---
title: Validate vs. Delegate
description: Understand the difference between validation and delegation.
---

Validation[​](#validation "Direct link to heading")
---------------------------------------------------

Validation in the context of staking refers to the act of running a node on the blockchain network to validate transactions and secure the network.

- **Stake Requirement**: To become a validator on the Lux network, one must stake a minimum amount of 2,000 LUX tokens on the Mainnet (1 LUX on the Testnet Testnet).
- **Process**: Validators participate in achieving consensus by repeatedly sampling other validators. The probability of being sampled is proportional to the validator's stake, meaning the more tokens a validator stakes, the more influential they are in the consensus process.
- **Rewards**: Validators are eligible to receive rewards for their efforts in securing the network. To receive rewards, a validator must be online and responsive for more than 80% of their validation period.

Delegation[​](#delegation "Direct link to heading")
---------------------------------------------------

Delegation allows token holders who do not wish to run their own validator node to still participate in staking by "delegating" their tokens to an existing validator node.

- **Stake Requirement**: To delegate on the Lux network, a minimum of 25 LUX tokens is required on the Mainnet (1 LUX on the Testnet Testnet).
- **Process**: Delegators choose a specific validator node to delegate their tokens to, trusting that the validator will behave correctly and help secure the network on their behalf.
- **Rewards**: Delegators are also eligible to receive rewards for their stake. The validator they delegate to shares a portion of the reward with them, according to the validator's delegation fee rate.

Key Differences[​](#key-differences "Direct link to heading")
-------------------------------------------------------------

- **Responsibilities**: Validators actively run a node, validate transactions, and actively participate in securing the network. Delegators, on the other hand, do not run a node themselves but entrust their tokens to a validator to participate on their behalf.
- **Stake Requirement**: Validators have a higher minimum stake requirement compared to delegators, as they take on more responsibility in the network.
- **Rewards Distribution**: Validators receive rewards directly for their validation efforts. Delegators receive rewards indirectly through the validator they delegate to, sharing a portion of the validator's reward.

In summary, validation involves actively participating in securing the network by running a node, while delegation allows token holders to participate passively by trusting their stake to a chosen validator. Both validators and delegators can earn rewards, but validators have higher stakes and more direct involvement in the Lux network.

# What Is Staking? (/docs/primary-network/validate/what-is-staking)

---
title: What Is Staking?
description: Learn about staking and how it works in Lux.
---

Staking is the process where users lock up their tokens to support a blockchain network and, in return, receive rewards. It is an essential part of proof-of-stake (PoS) consensus mechanisms used by many blockchain networks, including Lux. PoS systems require participants to stake a certain amount of tokens as collateral to participate in the network and validate transactions.

How Does Proof-of-Stake Work?[​](#how-does-proof-of-stake-work "Direct link to heading")
----------------------------------------------------------------------------------------

To resist [sybil attacks](https://support.avalabs.org/en/articles/4064853-what-is-a-sybil-attack), a decentralized network must require that network influence is paid with a scarce resource. This makes it infeasibly expensive for an attacker to gain enough influence over the network to compromise its security. On Lux, the scarce resource is the native token, [LUX](/docs/primary-network/lux-token). For a node to validate a blockchain on Lux, it must stake LUX.

# Chain State Management (/docs/nodes/node-storage/chain-state-management)

---
title: Chain State Management
description: Understanding active state vs archival state in EVM chains, and node configuration options.
---

When running an EVM-based blockchain (LUExchange-Chain or Subnet-EVM L1s), your node stores blockchain state
on disk. Understanding the difference between **active state** and **archival state** is crucial for
choosing the right configuration.

## State Sync

State sync is a method of bootstrapping a node by syncing from a state sync snapshot instead of full
replay of all historical blocks. This means instead of downloading and replaying all transactions of
all blocks since genesis, the node downloads only a latest result of these transactions from the
other validators.

This is a faster way to bootstrap a node and is recommended for new validator nodes that do not require archival state.

State sync is enabled by default for the LUExchange-Chain. For Lux L1s, you can configure it per-chain:

- **LUExchange-Chain configuration**: See [LUExchange-Chain Config](/docs/nodes/chain-configs/primary-network/c-chain#state-sync-enabled)
- **Lux L1 configuration**: See [Subnet-EVM
  Config](/docs/nodes/chain-configs/lux-l1s/subnet-evm#state-sync-enabled)

To provide this feature, the all Lux nodes need to store state sync snapshots every 4000 blocks. This
requires additional disk space. 

## State Types

Your node's storage requirements depend on which type of state you're maintaining:

| Property | Active State | Active State with Snapshots | Archival State |
|----------|--------------|------------------------------|----------------|
| **Size (LUExchange-Chain)** | ~500 GB | ~750 GB - 1 TB | ~13 TB+ (and growing) |
| **Contents** | Current account balances, contract storage, code | Active state + state sync snapshots for serving peers | Complete state history at every block |
| **Required for** | Validating, sending transactions, reading current state | Same as Active State, helps other nodes bootstrap | Historical queries at any block height, block explorers, analytics |
| **Sync method** | State sync (fast, hours) | State sync, then grows over time | Full sync from genesis (slow, days) |
| **Maintenance** | Periodic state sync snapshot deletion or resync recommended | Periodic pruning or resync recommended | None needed (intentional full history) |

![State Growth Visualization](/images/State_growth_visualization.png)

### Archival State (gray line)

The **archival state** includes the complete history of all state changes since genesis. This allows
querying historical state at any block height (e.g., "What was this account's balance at block
1,000,000?"). By default Archive nodes are typically only required for block explorers, indexers, and
specialized analytics applications. Their disk usage will grow fastest over time.

<Callout>
Most validators and RPC nodes only need **active state**. Archive nodes are specialized infrastructure for historical data access.
</Callout>

### Active State (black line)

The **active state** represents the current state of the blockchain: all account balances, contract
storage, and code as of the latest block. This is what your node needs to validate new transactions
and participate in consensus. When you bootstrap with state sync, you start with just the active
state. Freshly state-synced nodes will only have the active state.

### Active State with State Sync Snapshots (red line)

Nodes with the configuration `pruning-enabled: true` accumulate not the full historical state but
only the active state and state sync snapshots over time after starting with active state. As blocks
are processed, state sync snapshots are retained every 4000 blocks for serving other
nodes that want to bootstrap via state sync. This causes disk usage to grow beyond the active state
size. Most long-running validators operate in this state.

<Callout title="Future Improvement: Firewood">
[Firewood](https://github.com/luxfi/firewood) is an upcoming database upgrade that will address the issue of state growing too large. This next-generation storage layer is designed to efficiently manage state growth and reduce disk space requirements for node operators.
</Callout>

### Active State with periodic snapshot deletion (green line)

Nodes that manually perform some maintenance can reduce their storage requirements by deleting state
sync snapshots. This can be achieved by periodically deteleting the state sync snapshots or
replacing the node with a freshly-state-synced node.

## Monitoring Disk Usage

Track your node's disk usage over time to plan maintenance:

```bash
# Check database size
du -sh ~/.luxgo/db

# Check available disk space
df -h /
```

Consider setting up alerts when disk usage exceeds 80% to give yourself time to plan maintenance.

## State Growth Rates

Even with the same configuration, different types of state grow at different rates:

| Growth Type | Rate | Description |
|-------------|------|-------------|
| Archival state | ~[TBD] GB/month | Complete history stored at every block |
| Active state + snapshots | ~[TBD] GB/month | Active state + Snapshots every 4000 blocks for serving peers |
| Active state | ~[TBD] GB/month | Current blockchain state only |

<Callout title="Note">
State sync snapshots are retained to help other nodes bootstrap. Even if you don't need archival state, these snapshots accumulate over time and increase disk usage.
</Callout>

## Node Configuration Matrix

Your node's final state depends on two factors: **how you bootstrap** and **whether pruning is enabled**.

| Bootstrap Method | Pruning Disabled | Pruning Enabled |
|------------------|------------------|-----------------|
| **State Sync** | Active + Snapshots (~1TB)  <br/> To get full archival state, you must <br/> do a **full sync from genesis**. | Active State only (~500GB) |
| **Full Sync** | Full Archival (~13TB+) | N/A |


## Choosing Your Configuration

| Use Case | Bootstrap | Pruning | Result | Disk Size |
|----------|-----------|---------|--------|-----------|
| Validator | State Sync | Periodic | Active state, minimal disk | ~500 GB |
| Standard RPC | State Sync | Optional | Current state queries | ~500 GB - 1 TB |
| Archival RPC | State Sync | Disabled | Full state after sync point | ~750 GB - 1 TB |
| Block Explorer / Indexer | Full Sync | Disabled | Complete archival history | ~12.5 TB+ |

<Callout>
**Archival RPC vs Block Explorer**: An archival RPC started via state sync can answer queries from the sync point forward. For complete historical queries from genesis, you need a full sync.
</Callout>

# Periodic State Sync (/docs/nodes/node-storage/periodic-state-sync)

---
title: Periodic State Sync
description: Instructions for performing a periodic state sync.
---

By bootstrapping a new node via state sync and transfering your validator identity you can reduce
disk usage with zero downtime.

| Pros | Cons |
|------|------|
| No downtime for validator | Needs separate machine to bootstrap |
| Fresh, clean database | Network bandwidth for sync |
| No bloom filter disk overhead | More complex multi-step process |

<Callout>
If you don't have access to a separate machine, you can also do a [state sync snapshot deletion](/docs/nodes/node-storage/state-sync-snapshot-deletion) instead.
</Callout>

### How It Works

This works because your validator identity is determined by cryptographic keys in the staking directory, not the database.

Your validator identity consists of three key files in `~/.luxgo/staking/`:
- **staker.crt** - TLS certificate (determines your Node ID)
- **staker.key** - TLS private key (for encrypted P2P communication)
- **signer.key** - BLS signing key (for consensus signatures)

These files define your validator identity. The Node ID shown on the Platform-Chain is cryptographically derived from `staker.crt`, so copying these files transfers your complete validator identity.

![Node Replacement Process](/images/State_sync_new_node.png)

The diagram shows the process: stop the old node, let a new node state sync, then transfer the
staking keys to continue validating with a fresh database.

![Frequent Pruning Pattern](/images/State_sync_frequent_pruning.png)

### Step-by-Step Process

<Steps>

<Step>
## Save the Node ID of the old validator

To verify that the Node ID of the old validator matches the Node ID of the new validator note down
the node ID of the old validator:

```bash
# On old validator
curl -X POST --data '{
   "jsonrpc":"2.0",
   "id"     :1,
   "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```
</Step>

<Step>
## Provision a new server with the same or better specs than your current validator

Don't copy the database at `~/.luxgo/db/`. The new node sync a smaller fresh, synced database
from the other nodes.
</Step>

<Step>
## Install and configure LuxGo

Follow the instructions to set up a new node. If you have custom configuration in
`~/.luxgo/configs/`, copy those as well to maintain the same node behavior. Make sure that you
are not manually deactivating state sync in that config file.
</Step>

<Step>
## Start and monitor the node state sync

Start the node according to the instructions. State sync is enabled by default in the node
configuration. You can monitor the sync progress by checking the `info.isBootstrapped` RPC endpoint:

```bash
# Monitor sync progress (wait until fully synced)
# This may take several hours
curl -X POST --data '{
   "jsonrpc":"2.0",
   "id"     :1,
   "method" :"info.isBootstrapped",
   "params": {
      "chain":"C"
   }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```
</Step>

<Step>
## Stop both nodes 

Once the state sync has completed, stop both nodes to prepare for the identity transfer. The entire
stop → transfer → restart process typically takes 5-15 minutes. Your validator will miss some blocks
during this window, but won't be penalized as long as you're back online before your uptime drops below 80%.
</Step>

<Step>
## Backup the new server's auto-generated keys

Backup the new server's auto-generated keys (optional but recommended):
```bash
# On new server
mv ~/.luxgo/staking ~/.luxgo/staking.backup
```
</Step>

<Step>
## Transfer the staking keys

Copy the staking directory from your old validator to the new server

```bash
# From your old validator, copy to new server
scp -r ~/.luxgo/staking/ user@new-server:~/.luxgo/

# Or use rsync for better control:
rsync -avz ~/.luxgo/staking/ user@new-server:~/.luxgo/staking/
```
</Step>

<Step>
## Verify file permissions on the new server

```bash
# On new server
chmod 700 ~/.luxgo/staking
chmod 400 ~/.luxgo/staking/staker.key
chmod 400 ~/.luxgo/staking/staker.crt
chmod 400 ~/.luxgo/staking/signer.key
chown -R lux:lux ~/.luxgo/staking  # If using lux user
```
</Step>

<Step>
## Start the new node with your validator identity

**Don't run both nodes simultaneously**: Running two nodes with the same staking keys simultaneously can cause network issues and potential penalties. Always stop the old node before starting the new one.
</Step>

<Step>
## Verify the Node ID matches

   ```bash
   # On new server - confirm this matches your registered validator Node ID
   curl -X POST --data '{
     "jsonrpc":"2.0",
     "id"     :1,
     "method" :"info.getNodeID"
   }' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
   ```
</Step>

<Step>
## Monitor for successful validation

    ```bash
    # Check if you're validating
    curl -X POST --data '{
      "jsonrpc":"2.0",
      "id"     :1,
      "method" :"platform.getCurrentValidators",
      "params": {
        "subnetID": null
      }
    }' -H 'content-type:application/json;' 127.0.0.1:9650/ext/P
    ```
</Step>
</Steps>


# State Sync Snapshot Deletion (Offline Pruning) (/docs/nodes/node-storage/state-sync-snapshot-deletion)

---
title: State Sync Snapshot Deletion (Offline Pruning)
description: Options for reducing disk usage on non-archival nodes through offline pruning or fresh state sync.
---

Removes accumulated state sync snapshots while keeping your database intact.

| Pros | Cons |
|------|------|
| Only need a single node | Need to stop the node |
| Preserves transaction index | Downtime required (duration varies) |
| No network bandwidth required | Requires temporary disk space for bloom filter |

<Callout>
The duration of offline pruning depends on how many state sync snapshots have accumulated since the
last pruning. A node pruned regularly may complete quickly, while one never pruned could take
significantly longer. If you don't prune regularly, consider doing a [fresh state sync](/docs/nodes/node-storage/periodic-state-sync) instead.
</Callout>

![State Growth Visualization](/images/State_growth_visualization.png)

The green line shows a node performing periodic offline pruning. Each black vertical drop represents a pruning event: the node's state drops from "Active + Snapshots" back to just "Active State". Frequent pruning is recommended: it keeps disk usage low and each pruning operation completes faster since there are fewer snapshots to remove.

### How Offline Pruning Works

Offline Pruning is ported from `go-ethereum` to reduce the amount of disk space taken up by the TrieDB (storage for the Merkle Forest).

Offline pruning creates a bloom filter and adds all trie nodes in the active state to the bloom filter to mark the data as protected. This ensures that any part of the active state will not be removed during offline pruning.

After generating the bloom filter, offline pruning iterates over the database and searches for trie nodes that are safe to be removed from disk.

A bloom filter is a probabilistic data structure that reports whether an item is definitely not in a set or possibly in a set. Therefore, for each key we iterate, we check if it is in the bloom filter. If the key is definitely not in the bloom filter, then it is not in the active state and we can safely delete it. If the key is possibly in the set, then we skip over it to ensure we do not delete any active state.

During iteration, the underlying database (LevelDB) writes deletion markers, causing a temporary increase in disk usage.

After iterating over the database and deleting any old trie nodes that it can, offline pruning then
runs compaction to minimize the DB size after the potentially large number of delete operations.

<Steps>
<Step>
## Stopping the Node

In order to enable offline pruning, you need to stop the node.
</Step>

<Step>
## Finding the LUExchange-Chain Config File

In order to enable offline pruning, you need to update the LUExchange-Chain config file to include the parameters `offline-pruning-enabled` and `offline-pruning-data-directory`.

The default location of the LUExchange-Chain config file is `~/.luxgo/configs/chains/C/config.json`.
**Please note that by default, this file does not exist. You would need to create it manually.** 
</Step>

<Step>
## Configure Offline Pruning

In order to enable offline pruning, update the LUExchange-Chain config file to include the following parameters:

```json
{
  "offline-pruning-enabled": true,
  "offline-pruning-data-directory": "/home/ubuntu/offline-pruning"
}
```

This will set `/home/ubuntu/offline-pruning` as the directory to be used by the offline pruner. Offline pruning will store the bloom filter in this location, so you must ensure that the path exists.

</Step>
<Step>
## Restart the Node

Now that the LUExchange-Chain config file has been updated, you can restart your node.

Once LuxGo starts the LUExchange-Chain, you can expect to see update logs from the offline pruner:

```bash
INFO [02-09|00:20:15.625] Iterating state snapshot                 accounts=297,231 slots=6,669,708 elapsed=16.001s eta=1m29.03s
INFO [02-09|00:20:23.626] Iterating state snapshot                 accounts=401,907 slots=10,698,094 elapsed=24.001s eta=1m32.522s
INFO [02-09|00:20:31.626] Iterating state snapshot                 accounts=606,544 slots=13,891,948 elapsed=32.002s eta=1m10.927s
...
INFO [02-09|00:21:47.342] Iterated snapshot                        accounts=1,950,875 slots=49,667,870 elapsed=1m47.718s
INFO [02-09|00:21:47.351] Writing state bloom to disk              name=/home/ubuntu/offline-pruning/statebloom.0xd6fca36db4b60b34330377040ef6566f6033ed8464731cbb06dc35c8401fa38e.bf.gz
INFO [02-09|00:23:04.421] State bloom filter committed             name=/home/ubuntu/offline-pruning/statebloom.0xd6fca36db4b60b34330377040ef6566f6033ed8464731cbb06dc35c8401fa38e.bf.gz
```

The bloom filter should be populated and committed to disk after about 5 minutes. At this point, if
the node shuts down, it will resume the offline pruning session when it restarts (note: this
operation cannot be cancelled).

</Step>
<Step>
## Disable Offline Pruning

In order to ensure that users do not mistakenly leave offline pruning enabled for the long term (which could result in an hour of downtime on each restart), we have added a manual protection which requires that after an offline pruning session, the node must be started with offline pruning disabled at least once before it will start with offline pruning enabled again. Therefore, once the bloom filter has been committed to disk, you should update the LUExchange-Chain config file to include the following parameters:

```json
{
  "offline-pruning-enabled": false,
  "offline-pruning-data-directory": "/home/ubuntu/offline-pruning"
}
```

It is important to keep the same data directory in the config file, so that the node knows where to look for the bloom filter on a restart if offline pruning has not finished.

Now if your node restarts, it will be marked as having correctly disabled offline pruning after the
run and be allowed to resume normal operation once offline pruning has finished running.

</Step>
<Step>
## Monitor Offline Pruning Progress

You will see progress logs throughout the offline pruning run which will indicate the session's progress:

```bash
INFO [02-09|00:31:51.920] Pruning state data                       nodes=40,116,759 size=10.08GiB  elapsed=8m47.499s eta=12m50.961s
INFO [02-09|00:31:59.921] Pruning state data                       nodes=41,659,059 size=10.47GiB  elapsed=8m55.499s eta=12m13.822s
...
INFO [02-09|00:42:45.359] Pruned state data                        nodes=98,744,430 size=24.82GiB  elapsed=19m40.938s
INFO [02-09|00:42:45.360] Compacting database                      range=0x00-0x10 elapsed="2.157µs"
...
INFO [02-09|00:59:34.367] Database compaction finished             elapsed=16m49.006s
INFO [02-09|00:59:34.367] State pruning successful                 pruned=24.82GiB elapsed=39m34.749s
INFO [02-09|00:59:34.367] Completed offline pruning. Re-initializing blockchain.
```

At this point, the node will go into bootstrapping and (once bootstrapping completes) resume
consensus and operate as normal.
</Step>
</Steps>

### Disk Space Considerations

To ensure the node does not enter an inconsistent state, the bloom filter used for pruning is persisted to `offline-pruning-data-directory` for the duration of the operation. This directory should have `offline-pruning-bloom-filter-size` available in disk space (default 512 MB).

The underlying database (LevelDB) uses deletion markers (tombstones) to identify newly deleted keys. These markers are temporarily persisted to disk until they are removed during a process known as compaction. This will lead to an increase in disk usage during pruning. If your node runs out of disk space during pruning, you may safely restart the pruning operation. This may succeed as restarting the node triggers compaction.

If restarting the pruning operation does not succeed, additional disk space should be provisioned.

# Lux L1 Nodes (/docs/nodes/run-a-node/avalanche-l1-nodes)

---
title: Lux L1 Nodes
description: Learn how to run an Lux node that tracks an Lux L1.
---

This article describes how to run a node that tracks an Lux L1. It requires building LuxGo, adding Virtual Machine binaries as plugins to your local data directory, and running LuxGo to track these binaries.

This tutorial specifically covers tracking an Lux L1 built with Lux's [Subnet-EVM](https://github.com/luxfi/subnet-evm), the default [Virtual Machine](/docs/primary-network/virtual-machines) run by Lux L1s on Lux.

## Build LuxGo

It is recommended that you must complete [this comprehensive guide](/docs/nodes/run-a-node/from-source) which demonstrates how to build and run a basic Lux node from source.

## Build Lux L1 Binaries

After building LuxGo successfully,

<Steps>
<Step>
Clone [Subnet-EVM](https://github.com/luxfi/subnet-evm):

```bash
cd $GOPATH/src/github.com/luxfi
git clone https://github.com/luxfi/subnet-evm.git
```
</Step>

<Step>
In the Subnet-EVM directory, run the build script, and save it in the `plugins` folder of your `.luxgo` data directory. Name the plugin after the `VMID` of the Lux L1 you wish to track. The `VMID` of the WAGMI Lux L1 is the value beginning with **srEX...**

```bash
cd $GOPATH/src/github.com/luxfi/subnet-evm
./scripts/build.sh ~/.luxgo/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
```

<Accordions>
<Accordion title="Where can I find Lux L1 parameters like VMID?">
VMID, Lux L1 ID (SubnetID), ChainID, and all other parameters can be found in the "Chain Info" section of the Lux L1 Explorer.

- [Lux Mainnet](https://subnets.lux.network/c-chain)
- [Testnet Testnet](https://subnets-test.lux.network/c-chain)
</Accordion>
</Accordions>
</Step>

<Step>
Create a file named `config.json` and add a `track-subnets` field that is populated with the `SubnetID` you wish to track. The `SubnetID` of the WAGMI Lux L1 is the value beginning with **28nr...**

```bash
cd ~/.luxgo
echo '{"track-subnets": "28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY"}' > config.json
```
</Step>
</Steps>

## Run the Node

Run LuxGo with the `—config-file` flag to start your node and ensure it tracks the Lux L1s included in the configuration file.

```bash
cd $GOPATH/src/github.com/luxfi/luxgo
./build/luxgo --config-file ~/.luxgo/config.json --network-id=testnet
```

<Callout title="Note">
Note: The above command includes the `--network-id=testnet` command because the WAGMI Lux L1 is deployed on Testnet Testnet.
</Callout>

<Accordions>
<Accordion title="Run L1 Node Without The Config File">
If you would prefer to track Lux L1s using a command line flag, you can instead use the `--track-subnets` flag. For example:

```bash
./build/luxgo --track-subnets 28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY --network-id=testnet
```
</Accordion>
</Accordions>

You should now see terminal filled with logs and information to suggest the node is properly running and has began bootstrapping to the network.

## Bootstrapping and RPC Details

It may take a few hours for the node to fully [bootstrap](/docs/nodes/run-a-node/from-source#bootstrapping) to the Lux Primary Network and tracked Lux L1s.

When finished bootstrapping, the endpoint will be:

```bash
localhost:9650/ext/bc/<BlockchainID>/rpc
```

if run locally, or:

```bash
XXX.XX.XX.XXX:9650/ext/bc/<BlockchainID>/rpc
```

if run on a cloud provider. The “X”s should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the [Subnet-EVM API Reference](/docs/rpcs/subnet-evm) documentation.

Because each node is also tracking the Primary Network, those [RPC endpoints](/docs/nodes/run-a-node/from-source#rpc) are available as well.


# Common Errors (/docs/nodes/run-a-node/common-errors)

---
title: Common Errors
description: Common errors while running a node and their solutions.
---

If you experience any issues running your node, here are common errors and their solutions.

## Bootstrap and Initialization Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `failed to connect to bootstrap nodes` | • No internet access<br/>• NodeID already in use<br/>• Old instance still running<br/>• Firewall blocking outbound connections | • Check internet connection<br/>• Ensure only one node instance is running<br/>• Verify firewall allows outbound connections<br/>• Confirm staking port (9651) is configured |
| `subnets not bootstrapped` | • Node still syncing with network<br/>• Health checks called too early<br/>• Network connectivity issues | • Wait for bootstrap to complete (can take hours)<br/>• Monitor `/api/health` endpoint<br/>• Ensure stable network connection<br/>• Check logs for progress |
| `db contains invalid genesis hash` | • Database from different network<br/>• Database corruption<br/>• Incompatible database | • Delete database and resync from scratch<br/>• Verify correct network connection<br/>• Check `--network-id` flag matches database |

## Network and Connectivity Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `cannot query unfinalized data` | • Not connected to other validators<br/>• Wrong public IP configured<br/>• Port 9651 closed/blocked<br/>• Insufficient validator connections | • Configure public IP with `--public-ip`<br/>• Open port 9651 to internet<br/>• Allow inbound connections in firewall<br/>• Set up port forwarding if behind NAT<br/>• Verify peers: `curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"info.peers"}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/info` |
| `primary network validator has no inbound connections` | • Firewall blocking inbound traffic<br/>• NAT/router not configured<br/>• Wrong public IP advertised<br/>• ISP blocking connections | • Configure port forwarding for 9651<br/>• Verify firewall allows inbound<br/>• Check public IP: `curl ifconfig.me`<br/>• Test port with online checkers<br/>• Use VPS if ISP blocks ports |
| `not connected to enough stake` | • Insufficient validator connections<br/>• Network partitioning<br/>• Node isolated from network<br/>• Bootstrap incomplete | • Check network connectivity<br/>• Verify firewall rules<br/>• Wait for more connections<br/>• Synchronize system time (NTP) |
| `throttled` (Code: -4) | • Too many connection attempts<br/>• Rate limiting by peers<br/>• Network congestion | • Wait before retrying<br/>• Check for connection loops<br/>• Reduce connection rate |

## Database and Storage Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `closed` | • Database accessed after shutdown<br/>• Ungraceful termination<br/>• Connection lost | • Restart the node<br/>• Check for disk errors or full disk<br/>• Verify database files not corrupted |
| `blockdb: unrecoverable corruption detected` | • Ungraceful shutdown (power loss, kill -9)<br/>• Disk errors during writes<br/>• Hardware failure | • Delete database and resync<br/>• Run SMART diagnostics on disk<br/>• Ensure 10+ GiB free space<br/>• Use UPS for power protection<br/>• Maintain regular backups |
| Disk space warnings | • Usage exceeds threshold<br/>• Database growth without cleanup<br/>• Log accumulation | • Keep at least 10 GiB free (20+ GiB recommended)<br/>• Monitor disk usage regularly<br/>• Clean up old logs<br/>• Set up low-space alerts |
| `blockdb: invalid block height` | • Database corruption<br/>• Querying non-existent block<br/>• Index corruption | • Verify block height is valid<br/>• Resync if corrupted<br/>• Check database integrity |

## Configuration Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `invalid TLS key` | • TLS key without certificate<br/>• Certificate without key<br/>• Invalid key format<br/>• Corrupted certificate files | • Provide both key and certificate together<br/>• Regenerate credentials if corrupted<br/>• Verify file permissions<br/>• Check certificate format |
| `minimum validator stake can't be greater than maximum` | • Invalid stake configuration<br/>• Conflicting parameters<br/>• Configuration typos | • Review configuration file<br/>• Ensure min < max stake<br/>• Check for typos |
| `uptime requirement must be in the range [0, 1]` | • Out-of-range uptime value | • Set uptime requirement between 0 and 1 |
| `delegation fee must be in the range [0, 1,000,000]` | • Invalid delegation fee | • Set fee between 0 and 1,000,000 |
| `min stake duration must be > 0` | • Invalid stake duration<br/>• Min > max duration | • Set min duration > 0 and < max |
| `sybil protection disabled on public network` | • Disabling protection on mainnet/testnet<br/>• Security misconfiguration | • Only disable on private networks<br/>• Verify network configuration<br/>• Remove override for public networks |
| `plugin dir is not a directory` | • Path points to file not directory<br/>• Directory doesn't exist<br/>• Permission issues | • Create plugin directory<br/>• Verify path points to directory<br/>• Check read/execute permissions |

## Resource and Capacity Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `insufficient funds` | • Insufficient balance for fees<br/>• Transaction exceeds balance<br/>• Gas estimation too low | • Ensure sufficient balance<br/>• Account for transaction fees<br/>• Verify balance before submitting |
| `insufficient gas capacity to build block` | • Mempool exceeds block gas limit<br/>• Complex transactions<br/>• Network congestion | • Wait for congestion to clear<br/>• Break into smaller transactions<br/>• Increase gas limits if possible |
| `insufficient history to generate proof` | • Partial sync mode<br/>• Pruned historical data<br/>• Incomplete state sync | • Use full sync for complete history<br/>• Wait for state sync to finish<br/>• Use archival node for historical data |

## Validator and Consensus Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `not a validator` (Code: -3) | • Validator-only operation on non-validator<br/>• Stake expired or not active<br/>• Not registered as validator | • Verify registration status<br/>• Check stake is active<br/>• Wait for validation period<br/>• Use correct API for node type |
| `unknown validator` | • Not in current validator set<br/>• NodeID mismatch<br/>• Validator expired/removed | • Verify validator is active<br/>• Check end time hasn't passed<br/>• Confirm correct NodeID<br/>• Query validator set |

## Version and Upgrade Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `unknown network upgrade detected` | • Outdated node version<br/>• Network upgrade scheduled/active<br/>• Incompatible protocol | • **Update immediately** to latest version<br/>• Monitor upgrade announcements<br/>• Enable automatic updates<br/>• Check version: `luxgo --version` |
| `unknown network upgrade - update as soon as possible` | • Network upgrade approaching<br/>• Node version outdated | • Update within the day<br/>• Check GitHub releases<br/>• Plan for maintenance window |
| `imminent network upgrade - update immediately` | • Network upgrade imminent (within hour) | • **Critical: Update immediately**<br/>• Risk of network disconnection |
| `invalid upgrade configuration` | • Upgrade times not chronological<br/>• Conflicting schedules<br/>• Invalid precompile config | • Review upgrade config files<br/>• Ensure sequential timing<br/>• Validate precompile settings<br/>• Consult upgrade documentation |

## API and RPC Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Health check: `not yet run` | • Node still initializing<br/>• Bootstrap incomplete<br/>• Subnet sync in progress<br/>• Network issues | • Wait for initialization<br/>• Monitor `/api/health` for updates<br/>• Check individual health checks<br/>• Ensure subnets are synced |
| `timed out` (Code: -1) | • Request exceeded timeout<br/>• Node overloaded<br/>• Network latency | • Increase timeout settings<br/>• Check resource usage (CPU/memory/disk)<br/>• Reduce request complexity<br/>• Use retry with exponential backoff |
| Invalid content-type | • Wrong Content-Type header<br/>• Missing header | • Add `Content-Type: application/json`<br/>• Verify API client config<br/>• Example: `curl -H 'content-type:application/json;' ...` |

## State Sync Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `proof obtained an invalid root ID` | • State changed during sync<br/>• Corrupted merkle proof<br/>• Network issues | • Restart state sync<br/>• Ensure stable connection<br/>• Wait for state to stabilize |
| `vm does not implement StateSyncableVM interface` | • Unsupported VM<br/>• Outdated VM version | • Update VM to support state sync<br/>• Use full bootstrap instead<br/>• Check VM compatibility docs |

---

## Monitoring and Prevention

### Key Metrics to Monitor

| Metric | Threshold | How to Check |
|--------|-----------|--------------|
| **Disk Space** | Keep 10+ GiB free (20+ GiB recommended) | `df -h` |
| **Network Connectivity** | Inbound/outbound connections active | Check firewall, use port scanners |
| **Bootstrap Status** | Should be `bootstrapped` | `/api/health` |
| **Validator Connections** | Connected to sufficient stake | `/ext/info` API, check peer count |
| **Database Health** | No corruption warnings in logs | Monitor `~/.luxgo/logs/` |
| **Node Version** | Current with latest release | `luxgo --version` |

### Best Practices

| Practice | Benefit |
|----------|---------|
| Use UPS (uninterruptible power supply) | Prevents database corruption from power loss |
| Enable automatic updates | Stay current with security patches |
| Monitor logs regularly | Early detection of issues |
| Keep adequate disk space | Prevent database write failures |
| Configure port forwarding properly | Ensure validator connectivity |
| Synchronize system time with NTP | Prevent consensus issues |
| Backup critical files | Quick recovery from failures |
| Test changes on testnet first | Avoid production issues |

### Health Check Endpoints

| Endpoint | Purpose | What It Checks |
|----------|---------|----------------|
| `/ext/health/liveness` | Basic process health | Is the node process running? |
| `/ext/health/readiness` | Ready to serve traffic | Is bootstrapping complete? |
| `/ext/health` | Comprehensive status | All health checks and details |

### Getting Help

If you encounter errors not listed here:

1. **Check Logs**: Review `~/.luxgo/logs/` for detailed error messages
2. **Search Forum**: [Lux Forum](https://forum.lux.network/)
3. **Join Discord**: [Lux Discord](https://chat.lux.network/)
4. **GitHub Issues**: [Review existing issues](https://github.com/luxfi/luxgo/issues)
5. **Provide Context**: Include specific error messages, logs, and configuration when asking for help

### Quick Diagnostic Commands

```bash
# Check node version
luxgo --version

# Check disk space
df -h

# Check if port 9651 is open
nc -zv <your-public-ip> 9651

# Check node health
curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"health.health"}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/health

# Check peers
curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"info.peers"}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/info

# Check bootstrap status
curl -X POST --data '{"jsonrpc":"2.0","id":1,"method":"info.isBootstrapped","params":{"chain":"X"}}' -H 'content-type:application/json;' http://127.0.0.1:9650/ext/info
```

# Using Source Code (/docs/nodes/run-a-node/from-source)

---
title: Using Source Code
description: Learn how to run an Lux node from LuxGo Source code.
---

The following steps walk through downloading the LuxGo source code and locally building the binary program. If you would like to run your node using a pre-built binary, follow [this](/docs/nodes/run-a-node/using-binary) guide.

## Install Dependencies

- Install [gcc](https://gcc.gnu.org/)
- Install [go](https://go.dev/doc/install)

## Build the Node Binary

<Steps>
<Step>Set the `$GOPATH`. You can follow [this](https://github.com/golang/go/wiki/SettingGOPATH) guide.</Step>
 
<Step>
Create a directory in your `$GOPATH`:

```bash
mkdir -p $GOPATH/src/github.com/luxfi
```
</Step>

<Step>
In the `$GOPATH`, clone [LuxGo](https://github.com/luxfi/luxgo), the consensus engine and node implementation that is the core of the Lux Network.

```bash
cd $GOPATH/src/github.com/luxfi
git clone https://github.com/luxfi/luxgo.git
```
</Step>

<Step>
From the `luxgo` directory, run the build script:

```bash
cd $GOPATH/src/github.com/luxfi/luxgo
./scripts/build.sh
```
</Step>
</Steps>

## Start the Node

<Callout title="Note">
To be able to make API calls to your node from other machines, include the argument `--http-host=` when starting the node.
</Callout>

For running a node on the Lux Mainnet:

```bash
cd $GOPATH/src/github.com/luxfi/luxgo
./build/luxgo
```

For running a node on the Testnet Testnet:

```bash
cd $GOPATH/src/github.com/luxfi/luxgo
./build/luxgo --network-id=testnet
```

<Callout title="Note">
To kill the node, press `Ctrl + C`.
</Callout>

## Bootstrapping

A new node needs to catch up to the latest network state before it can participate in consensus and serve API calls. This process (called bootstrapping) currently takes several days for a new node connected to Mainnet, and a day or so for a new node connected to Testnet Testnet. When a given chain is done bootstrapping, it will print logs like this:

```bash
[09-09|17:01:45.295] INFO <C Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2qaFwDJtmCCbMKP4jRpJwH8EFws82Q2yC1HhWgAiy3tGrpGFeb"}
[09-09|17:01:46.199] INFO <P Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2ofmPJuWZbdroCPEMv6aHGvZ45oa8SBp2reEm9gNxvFjnfSGFP"}
[09-09|17:01:51.628] INFO <X Chain> snowman/transitive.go:334 consensus starting {"lenFrontier": 1}
```

### Check Bootstrapping Progress[​](#check-bootstrapping-progress "Direct link to heading")

To check if a given chain is done bootstrapping, in another terminal window call [`info.isBootstrapped`](/docs/rpcs/other/info-rpc#infoisbootstrapped) by copying and pasting the following command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If this returns `true`, the chain is bootstrapped; otherwise, it returns `false`. If you make other API calls to a chain that is not done bootstrapping, it will return `API call rejected because chain is not done bootstrapping`. If you are still experiencing issues please contact us on [Discord.](https://chat.avalabs.org/)

<Callout title="Note">
The 3 chains will bootstrap in the following order: P-chain, X-chain, C-chain.
</Callout>

Learn more about bootstrapping [here](/docs/nodes/maintain/bootstrapping).

## RPC

When finished bootstrapping, the X, P, and LUExchange-Chain RPC endpoints will be:

```bash
localhost:9650/ext/bc/P
localhost:9650/ext/bc/X
localhost:9650/ext/bc/C/rpc
```

if run locally, or

```bash
XXX.XX.XX.XXX:9650/ext/bc/P
XXX.XX.XX.XXX:9650/ext/bc/X
XXX.XX.XX.XXX:9650/ext/bc/C/rpc
```

if run on a cloud provider. The “XXX.XX.XX.XXX" should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the [LuxGo API Reference](/docs/rpcs/p-chain) documentation.

## Going Further

Your Lux node will perform consensus on its own, but it is not yet a validator on the network. This means that the rest of the network will not query your node when sampling the network during consensus. If you want to add your node as a validator, check out [Add a Validator](/docs/primary-network/validate/node-validator) to take it a step further.

Also check out the [Maintain](/docs/nodes/maintain/bootstrapping) section to learn about how to maintain and customize your node to fit your needs.

To track an Lux L1 with your node, head to the [Lux L1 Node](/docs/nodes/run-a-node/lux-l1-nodes) tutorial.

# Using Pre-Built Binary (/docs/nodes/run-a-node/using-binary)

---
title: Using Pre-Built Binary
description: Learn how to run an Lux node from a pre-built binary program.
---

## Download Binary

To download a pre-built binary instead of building from source code, go to the official [LuxGo releases page](https://github.com/luxfi/luxgo/releases), and select the desired version.

Scroll down to the **Assets** section, and select the appropriate file. You can follow below rules to find out the right binary.

### For MacOS

Download the `luxgo-macos-<VERSION>.zip` file and unzip using the below command:

```bash
unzip luxgo-macos-<VERSION>.zip
```

The resulting folder, `luxgo-<VERSION>`, contains the binaries.

### Linux (PCs or Cloud Providers)

Download the `luxgo-linux-amd64-<VERSION>.tar.gz` file and unzip using the below command:

```bash
tar -xvf luxgo-linux-amd64-<VERSION>.tar.gz
```

The resulting folder, `luxgo-<VERSION>-linux`, contains the binaries.

### Linux (Arm64)

Download the `luxgo-linux-arm64-<VERSION>.tar.gz` file and unzip using the below command:

```bash
tar -xvf luxgo-linux-arm64-<VERSION>.tar.gz
```

The resulting folder, `luxgo-<VERSION>-linux`, contains the binaries.

## Start the Node

<Callout title="Note">
To be able to make API calls to your node from other machines, include the argument `--http-host=` when starting the node.
</Callout>

### MacOS

For running a node on the Lux Mainnet:

```bash
./luxgo-<VERSION>/build/luxgo
```

For running a node on the Testnet Testnet:

```bash
./luxgo-<VERSION>/build/luxgo --network-id=testnet
```

### Linux

For running a node on the Lux Mainnet:

```bash
./luxgo-<VERSION>-linux/luxgo
```

For running a node on the Testnet Testnet:

```bash
./luxgo-<VERSION>-linux/luxgo --network-id=testnet
```

## Bootstrapping

A new node needs to catch up to the latest network state before it can participate in consensus and serve API calls. This process (called bootstrapping) currently takes several days for a new node connected to Mainnet, and a day or so for a new node connected to Testnet Testnet. When a given chain is done bootstrapping, it will print logs like this:

```bash
[09-09|17:01:45.295] INFO <C Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2qaFwDJtmCCbMKP4jRpJwH8EFws82Q2yC1HhWgAiy3tGrpGFeb"}
[09-09|17:01:46.199] INFO <P Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2ofmPJuWZbdroCPEMv6aHGvZ45oa8SBp2reEm9gNxvFjnfSGFP"}
[09-09|17:01:51.628] INFO <X Chain> snowman/transitive.go:334 consensus starting {"lenFrontier": 1}
```

### Check Bootstrapping Progress[​](#check-bootstrapping-progress "Direct link to heading")

To check if a given chain is done bootstrapping, in another terminal window call [`info.isBootstrapped`](/docs/rpcs/other/info-rpc#infoisbootstrapped) by copying and pasting the following command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If this returns `true`, the chain is bootstrapped; otherwise, it returns `false`. If you make other API calls to a chain that is not done bootstrapping, it will return `API call rejected because chain is not done bootstrapping`. If you are still experiencing issues please contact us on [Discord.](https://chat.avalabs.org/)

<Callout title="Note">
The 3 chains will bootstrap in the following order: P-chain, X-chain, C-chain.
</Callout>

Learn more about bootstrapping [here](/docs/nodes/maintain/bootstrapping).

## RPC

When finished bootstrapping, the X, P, and LUExchange-Chain RPC endpoints will be:

```bash
localhost:9650/ext/bc/P
localhost:9650/ext/bc/X
localhost:9650/ext/bc/C/rpc
```

if run locally, or

```bash
XXX.XX.XX.XXX:9650/ext/bc/P
XXX.XX.XX.XXX:9650/ext/bc/X
XXX.XX.XX.XXX:9650/ext/bc/C/rpc
```

if run on a cloud provider. The “XXX.XX.XX.XXX" should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the [LuxGo API Reference](/docs/rpcs/p-chain) documentation.

## Going Further

Your Lux node will perform consensus on its own, but it is not yet a validator on the network. This means that the rest of the network will not query your node when sampling the network during consensus. If you want to add your node as a validator, check out [Add a Validator](/docs/primary-network/validate/node-validator) to take it a step further.

Also check out the [Maintain](/docs/nodes/maintain/bootstrapping) section to learn about how to maintain and customize your node to fit your needs.

To track an Lux L1 with your node, head to the [Lux L1 Node](/docs/nodes/run-a-node/lux-l1-nodes) tutorial.

# Build LuxGo Docker Image (/docs/nodes/run-a-node/using-docker)

---
title: Build LuxGo Docker Image
description: Learn how to build a Docker image for LuxGo.
---

<Callout type="info">
For an easier way to set up and run a node, try the [Lux Console Node Setup Tool](/console/primary-network/node-setup).
</Callout>

## Prerequisites

Before beginning, you must ensure that:
- Docker is installed on your system
- You need to clone the [LuxGo repository](https://github.com/luxfi/luxgo)
- You need to install [GCC](https://gcc.gnu.org/) and [Go](https://go.dev/doc/install)
- Docker daemon is running on your machine

You can verify your Docker installation by running:
```bash
docker --version
```

## Building the Docker Image

To build the Docker image for the latest `luxgo` branch:

1. Navigate to the project directory
2. Execute the build script:
   ```bash
   ./scripts/build_image.sh
   ```

This script will create a Docker image containing the latest version of LuxGo.

## Verifying the Build

After the build completes, verify the image was created successfully:

```bash
docker image ls
```

You should see an image with:
- Repository: `avaplatform/luxgo`
- Tag: `xxxxxxxx` (where `xxxxxxxx` is the shortened commit hash of the source code used for the build)

## Running LuxGo Node

To start an LuxGo node, run the following command:

```bash
docker run -ti -p 9650:9650 -p 9651:9651 avaplatform/luxgo:xxxxxxxx /luxgo/build/luxgo
```

This command:
- Creates an interactive container (`-ti`)
- Maps the following ports:
  - `9650`: HTTP API port
  - `9651`: P2P networking port
- Uses the built LuxGo image
- Executes the LuxGo binary inside the container

## Port Configuration

The default ports used by LuxGo are:
- `9650`: HTTP API
- `9651`: P2P networking

Ensure these ports are available on your host machine and not blocked by firewalls.


# LUExchange-Chain API (/docs/rpcs/c-chain/api)

---
title: "LUExchange-Chain API"
description: "This page is an overview of the LUExchange-Chain API associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/graft/coreth/plugin/evm/api.md
---

<Callout title="Note">
Ethereum has its own notion of `networkID` and `chainID`. These have no relationship to Lux's view of networkID and chainID and are purely internal to the [LUExchange-Chain](https://github.com/docs/primary-network#c-chain). On Mainnet, the LUExchange-Chain uses `1` and `43114` for these values. On the Testnet Testnet, it uses `1` and `43113` for these values. `networkID` and `chainID` can also be obtained using the `net_version` and `eth_chainId` methods.
</Callout>

## Ethereum APIs

### Endpoints

#### JSON-RPC Endpoints

To interact with LUExchange-Chain via the JSON-RPC endpoint:

```sh
/ext/bc/C/rpc
```

To interact with other instances of the EVM via the JSON-RPC endpoint:

```sh
/ext/bc/blockchainID/rpc
```

where `blockchainID` is the ID of the blockchain running the EVM.

#### WebSocket Endpoints

<Callout title="info">
On the [public API node](https://github.com/docs/rpcs), it only supports LUExchange-Chain
websocket API calls for API methods that don't exist on the LUExchange-Chain's HTTP API
</Callout>

To interact with LUExchange-Chain via the websocket endpoint:

```sh
/ext/bc/C/ws
```

For example, to interact with the LUExchange-Chain's Ethereum APIs via websocket on localhost, you can use:

```sh
ws://127.0.0.1:9650/ext/bc/C/ws
```

<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
On localhost, use `ws://`. When using the [Public API](https://github.com/docs/rpcs) or another
host that supports encryption, use `wss://`.
</Callout>

To interact with other instances of the EVM via the websocket endpoint:

```sh
/ext/bc/blockchainID/ws
```

where `blockchainID` is the ID of the blockchain running the EVM.

### Standard Ethereum APIs

Lux offers an API interface identical to Geth's API except that it only supports the following
services:

- `web3_`
- `net_`
- `eth_`
- `personal_`
- `txpool_`
- `debug_` (note: this is turned off on the public API node.)

You can interact with these services the same exact way you'd interact with Geth (see exceptions below). See the
[Ethereum Wiki's JSON-RPC Documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/)
and [Geth's JSON-RPC Documentation](https://geth.ethereum.org/docs/rpc/server)
for a full description of this API.

<Callout title="info">
For batched requests on the [public API node](https://github.com/docs/rpcs) , the maximum
number of items is 40.
</Callout>

#### Exceptions

Starting with release [`v0.12.2`](https://github.com/luxfi/luxgo/releases/tag/v1.12.2), `eth_getProof` has a different behavior compared to geth:

- On archival nodes (nodes with`pruning-enabled` set to `false`), queries for state proofs older than 24 hours preceding the last accepted block will be rejected by default. This can be adjusted with `historical-proof-query-window`, which defines the number of blocks before the last accepted block that can be queried for state proofs. Set this option to `0` to accept a state query for any block number.
- On pruning nodes (nodes with `pruning-enabled` set to `true`), queries for state proofs outside the 32 block window after the last accepted block are always rejected.

### Lux - Ethereum APIs

In addition to the standard Ethereum APIs, Lux offers `eth_baseFee`,
`eth_maxPriorityFeePerGas`, and `eth_getChainConfig`.

They use the same endpoint as standard Ethereum APIs:

```sh
/ext/bc/C/rpc
```

#### `eth_baseFee`

Get the base fee for the next block.

**Signature:**

```sh
eth_baseFee() -> {}
```

`result` is the hex value of the base fee for the next block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_baseFee",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x34630b8a00"
}
```

#### `eth_maxPriorityFeePerGas`

Get the priority fee needed to be included in a block.

**Signature:**

```sh
eth_maxPriorityFeePerGas() -> {}
```

`result` is hex value of the priority fee needed to be included in a block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_maxPriorityFeePerGas",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2540be400"
}
```

For more information on dynamic fees see the [LUExchange-Chain section of the transaction fee
documentation](https://github.com/docs/rpcs/other/guides/txn-fees#c-chain-fees).

## Admin APIs

The Admin API provides administrative functionality for the EVM.

### Endpoint

```sh
/ext/bc/C/admin
```

### Methods

#### `admin_startCPUProfiler`

Starts a CPU profile that writes to the specified file.

**Signature:**

```sh
admin_startCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_startCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_stopCPUProfiler`

Stops the CPU profile.

**Signature:**

```sh
admin_stopCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_stopCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_memoryProfile`

Runs a memory profile writing to the specified file.

**Signature:**

```sh
admin_memoryProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_memoryProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_lockProfile`

Runs a mutex profile writing to the specified file.

**Signature:**

```sh
admin_lockProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_lockProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_setLogLevel`

Sets the log level for the EVM.

**Signature:**

```sh
admin_setLogLevel({
    level: string
}) -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_setLogLevel",
    "params" :[{
        "level": "debug"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_getVMConfig`

Returns the current VM configuration.

**Signature:**

```sh
admin_getVMConfig() -> {
    config: {
        // VM configuration fields
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_getVMConfig",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

## Lux-Specific APIs

### Endpoint

```sh
/ext/bc/C/lux
```

### Methods

#### `lux.getUTXOs`

Gets all UTXOs for the specified addresses.

**Signature:**

```sh
lux.getUTXOs({
    addresses: [string],
    sourceChain: string,
    startIndex: {
        address: string,
        utxo: string
    },
    limit: number,
    encoding: string
}) -> {
    utxos: [string],
    endIndex: {
        address: string,
        utxo: string
    },
    numFetched: number,
    encoding: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getUTXOs",
    "params" :[{
        "addresses": ["X-lux1..."],
        "sourceChain": "X",
        "limit": 100,
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.issueTx`

Issues a transaction to the network.

**Signature:**

```sh
lux.issueTx({
    tx: string,
    encoding: string
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.issueTx",
    "params" :[{
        "tx": "0x...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.getAtomicTxStatus`

Returns the status of the specified atomic transaction.

**Signature:**

```sh
lux.getAtomicTxStatus({
    txID: string
}) -> {
    status: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getAtomicTxStatus",
    "params" :[{
        "txID": "2QouvNW..."
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.getAtomicTx`

Returns the specified atomic transaction.

**Signature:**

```sh
lux.getAtomicTx({
    txID: string,
    encoding: string
}) -> {
    tx: string,
    encoding: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getAtomicTx",
    "params" :[{
        "txID": "2QouvNW...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.version`

Returns the version of the VM.

**Signature:**

```sh
lux.version() -> {
    version: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.version",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

# LuxGo LUExchange-Chain RPC (/docs/rpcs/c-chain)

---
title: "LuxGo LUExchange-Chain RPC"
description: "This page is an overview of the LUExchange-Chain RPC associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/graft/coreth/plugin/evm/api.md
---

> **Note:** Ethereum has its own notion of `networkID` and `chainID`. These have no relationship to Lux's view of networkID and chainID and are purely internal to the [LUExchange-Chain](https://build.lux.network/docs/quick-start/primary-network#c-chain). On Mainnet, the LUExchange-Chain uses `1` and `43114` for these values. On the Testnet Testnet, it uses `1` and `43113` for these values. `networkID` and `chainID` can also be obtained using the `net_version` and `eth_chainId` methods.

## Ethereum APIs

### Endpoints

#### JSON-RPC Endpoints

To interact with LUExchange-Chain via the JSON-RPC endpoint:

```sh
/ext/bc/C/rpc
```

To interact with other instances of the EVM via the JSON-RPC endpoint:

```sh
/ext/bc/blockchainID/rpc
```

where `blockchainID` is the ID of the blockchain running the EVM.

#### WebSocket Endpoints

> **Info:** The [public API node](https://build.lux.network/integrations#RPC%20Providers) (api.lux.network) supports HTTP APIs for Exchange-Chain, Platform-Chain, and LUExchange-Chain, but websocket connections are only available for LUExchange-Chain. Other EVM chains are not available via websocket on the public API node.

To interact with LUExchange-Chain via the websocket endpoint:

```sh
/ext/bc/C/ws
```

For example, to interact with the LUExchange-Chain's Ethereum APIs via websocket on localhost, you can use:

```sh
ws://127.0.0.1:9650/ext/bc/C/ws
```

> **Tip:** On localhost, use `ws://`. When using the [Public API](https://build.lux.network/integrations#RPC%20Providers) or another host that supports encryption, use `wss://`.

To interact with other instances of the EVM via the websocket endpoint:

```sh
/ext/bc/blockchainID/ws
```

where `blockchainID` is the ID of the blockchain running the EVM.

### Standard Ethereum APIs

Lux offers an API interface identical to Geth's API except that it only supports the following
services:

- `web3_`
- `net_`
- `eth_`
- `personal_`
- `txpool_`
- `debug_` (note: this is turned off on the public API node.)

You can interact with these services the same exact way you'd interact with Geth (see exceptions below). See the
[Ethereum Wiki's JSON-RPC Documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/)
and [Geth's JSON-RPC Documentation](https://geth.ethereum.org/docs/rpc/server)
for a full description of this API.

> **Info:** For batched requests on the [public API node](https://build.lux.network/integrations#RPC%20Providers) , the maximum number of items is 40.

#### Exceptions

Starting with release [`v0.12.2`](https://github.com/luxfi/luxgo/releases/tag/v1.12.2), `eth_getProof` has a different behavior compared to geth:

- On archival nodes (nodes with`pruning-enabled` set to `false`), queries for state proofs older than 24 hours preceding the last accepted block will be rejected by default. This can be adjusted with `historical-proof-query-window`, which defines the number of blocks before the last accepted block that can be queried for state proofs. Set this option to `0` to accept a state query for any block number.
- On pruning nodes (nodes with `pruning-enabled` set to `true`), queries for state proofs outside the 32 block window after the last accepted block are always rejected.

### Lux - Ethereum APIs

In addition to the standard Ethereum APIs, Lux offers `eth_baseFee`,
`eth_maxPriorityFeePerGas`, and `eth_getChainConfig`.

They use the same endpoint as standard Ethereum APIs:

```sh
/ext/bc/C/rpc
```

#### `eth_baseFee`

Get the base fee for the next block.

**Signature:**

```sh
eth_baseFee() -> {}
```

`result` is the hex value of the base fee for the next block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_baseFee",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x34630b8a00"
}
```

#### `eth_maxPriorityFeePerGas`

Get the priority fee needed to be included in a block.

**Signature:**

```sh
eth_maxPriorityFeePerGas() -> {}
```

`result` is hex value of the estimated priority fee needed to be included in a block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_maxPriorityFeePerGas",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2540be400"
}
```

For more information on dynamic fees see the [LUExchange-Chain section of the transaction fee
documentation](https://build.lux.network/docs/rpcs/other/guides/txn-fees#c-chain-fees).

## Admin APIs

The Admin API provides administrative functionality for the EVM.

### Admin API Endpoint

```sh
/ext/bc/C/admin
```

### Admin API Methods

#### `admin_startCPUProfiler`

Starts a CPU profile that writes to the specified file.

**Signature:**

```sh
admin_startCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_startCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_stopCPUProfiler`

Stops the CPU profile.

**Signature:**

```sh
admin_stopCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_stopCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_memoryProfile`

Runs a memory profile writing to the specified file.

**Signature:**

```sh
admin_memoryProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_memoryProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_lockProfile`

Runs a mutex profile writing to the specified file.

**Signature:**

```sh
admin_lockProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_lockProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_setLogLevel`

Sets the log level for the EVM.

**Signature:**

```sh
admin_setLogLevel({
    level: string
}) -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_setLogLevel",
    "params" :[{
        "level": "debug"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_getVMConfig`

Returns the current VM configuration.

**Signature:**

```sh
admin_getVMConfig() -> {
    config: {
        // VM configuration fields
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_getVMConfig",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

## Lux-Specific APIs

### Lux-Specific API Endpoint

```sh
/ext/bc/C/lux
```

### Lux-Specific API Methods

#### `lux.getUTXOs`

Gets all UTXOs for the specified addresses.

**Signature:**

```sh
lux.getUTXOs({
    addresses: [string],
    sourceChain: string,
    startIndex: {
        address: string,
        utxo: string
    },
    limit: number,
    encoding: string
}) -> {
    utxos: [string],
    endIndex: {
        address: string,
        utxo: string
    },
    numFetched: number,
    encoding: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getUTXOs",
    "params" :[{
        "addresses": ["X-lux1..."],
        "sourceChain": "X",
        "limit": 100,
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.issueTx`

Issues a transaction to the network.

**Signature:**

```sh
lux.issueTx({
    tx: string,
    encoding: string
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.issueTx",
    "params" :[{
        "tx": "0x...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.getAtomicTxStatus`

Returns the status of the specified atomic transaction.

**Signature:**

```sh
lux.getAtomicTxStatus({
    txID: string
}) -> {
    status: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getAtomicTxStatus",
    "params" :[{
        "txID": "2QouvNW..."
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

#### `lux.getAtomicTx`

Returns the specified atomic transaction.

**Signature:**

```sh
lux.getAtomicTx({
    txID: string,
    encoding: string
}) -> {
    tx: string,
    encoding: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"lux.getAtomicTx",
    "params" :[{
        "txID": "2QouvNW...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/lux
```

# Transaction Format (/docs/rpcs/c-chain/txn-format)

---
title: Transaction Format
---

This page is meant to be the single source of truth for how we serialize atomic
transactions in `Coreth`. This document uses the [primitive serialization](/docs/rpcs/other/standards/serialization-primitives) format for packing and
[secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#cryptography-in-the-lux-virtual-machine)
for cryptographic user identification.

## Codec ID

Some data is prepended with a codec ID (unt16) that denotes how the data should
be deserialized. Right now, the only valid codec ID is 0 (`0x00 0x00`).

## Inputs

Inputs to Coreth Atomic Transactions are either an `EVMInput` from this chain or
a `TransferableInput` (which contains a `SECP256K1TransferInput`) from another
chain. The `EVMInput` will be used in `ExportTx` to spend funds from this chain,
while the `TransferableInput` will be used to import atomic UTXOs from another
chain.

## EVM Input

Input type that specifies an EVM account to deduct the funds from as part of an `ExportTx`.

### What EVM Input Contains

An EVM Input contains an `address`, `amount`, `assetID`, and `nonce`.

- **`Address`** is the EVM address from which to transfer funds.
- **`Amount`** is the amount of the asset to be transferred (specified in nLUX
  for LUX and the smallest denomination for all other assets).
- **`AssetID`** is the ID of the asset to transfer.
- **`Nonce`** is the nonce of the EVM account exporting funds.

### Gantt EVM Input Specification

```text
+----------+----------+-------------------------+
| address  : [20]byte |                20 bytes |
+----------+----------+-------------------------+
| amount   : uint64   |                08 bytes |
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| nonce    : uint64   |                08 bytes |
+----------+----------+-------------------------+
                      |                68 bytes |
                      +-------------------------+
```

### Proto EVM Input Specification

```text
message  {
    bytes address = 1; // 20 bytes
    uint64 amount = 2; // 08 bytes
    bytes assetID = 3; // 32 bytes
    uint64 nonce = 4;  // 08 bytes
}
```

### EVM Input Example

Let's make an EVM Input:

- `Address: 0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc`
- `Amount: 2000000`
- `AssetID: 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `Nonce: 0`

```text
[
    Address   <- 0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc,
    Amount    <- 0x00000000001e8480
    AssetID   <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    Nonce     <- 0x0000000000000000
]
=
[
    // address:
    0x8d, 0xb9, 0x7c, 0x7c, 0xec, 0xe2, 0x49, 0xc2,
    0xb9, 0x8b, 0xdc, 0x02, 0x26, 0xcc, 0x4c, 0x2a,
    0x57, 0xbf, 0x52, 0xfc,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x1e, 0x84, 0x80,
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    // nonce:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
]
```

## Transferable Input

Transferable Input wraps a `SECP256K1TransferInput`. Transferable inputs
describe a specific UTXO with a provided transfer input.

### What Transferable Input Contains

A transferable input contains a `TxID`, `UTXOIndex` `AssetID` and an `Input`.

- **`TxID`** is a 32-byte array that defines which transaction this input is consuming an output from.
- **`UTXOIndex`** is an int that defines which utxo this input is consuming in the specified transaction.
- **`AssetID`** is a 32-byte array that defines which asset this input references.
- **`Input`** is a `SECP256K1TransferInput`, as defined below.

### Gantt Transferable Input Specification

```text
+------------+----------+------------------------+
| tx_id      : [32]byte |               32 bytes |
+------------+----------+------------------------+
| utxo_index : int      |               04 bytes |
+------------+----------+------------------------+
| asset_id   : [32]byte |               32 bytes |
+------------+----------+------------------------+
| input      : Input    |      size(input) bytes |
+------------+----------+------------------------+
                        | 68 + size(input) bytes |
                        +------------------------+
```

### Proto Transferable Input Specification

```text
message TransferableInput {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
    bytes asset_id = 3;    // 32 bytes
    Input input = 4;       // size(input)
}
```

### Transferable Input Example

Let's make a transferable input:

- `TxID: 0x6613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e59`
- `UTXOIndex: 1`
- `AssetID: 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`
- `Input: "Example SECP256K1 Transfer Input from below"`

```text
[
    TxID      <- 0x6613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e59
    UTXOIndex <- 0x00000001
    AssetID   <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    Input     <- 0x0000000500000000075bcd15000000020000000700000003
]
=
[
    // txID:
    0x66, 0x13, 0xa4, 0x0d, 0xcd, 0xd8, 0xd2, 0x2e,
    0xa4, 0xaa, 0x99, 0xa4, 0xc8, 0x43, 0x49, 0x05,
    0x63, 0x17, 0xcf, 0x55, 0x0b, 0x66, 0x85, 0xe0,
    0x45, 0xe4, 0x59, 0x95, 0x4f, 0x25, 0x8e, 0x59,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
]
```

## SECP256K1 Transfer Input

A
[secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#cryptography-in-the-lux-virtual-machine)
transfer input allows for spending an unspent secp256k1 transfer output.

### What SECP256K1 Transfer Input Contains

A secp256k1 transfer input contains an `Amount` and `AddressIndices`.

- **`TypeID`** is the ID for this input type. It is `0x00000005`.
- **`Amount`** is a long that specifies the quantity that this input should be
  consuming from the UTXO. Must be positive. Must be equal to the amount
  specified in the UTXO.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.

### Gantt SECP256K1 Transfer Input Specification

```text
+-------------------------+-------------------------------------+
| type_id         : int   |                             4 bytes |
+-----------------+-------+-------------------------------------+
| amount          : long  |                             8 bytes |
+-----------------+-------+-------------------------------------+
| address_indices : []int |  4 + 4 * len(address_indices) bytes |
+-----------------+-------+-------------------------------------+
                          | 16 + 4 * len(address_indices) bytes |
                          +-------------------------------------+
```

### Proto SECP256K1 Transfer Input Specification

```text
message SECP256K1TransferInput {
    uint32 typeID = 1;                   // 04 bytes
    uint64 amount = 2;                   // 08 bytes
    repeated uint32 address_indices = 3; // 04 bytes + 04 bytes * len(address_indices)
}
```

### SECP256K1 Transfer Input Example

Let's make a payment input with:

- **`TypeId`**: 5
- **`Amount`**: 500000000000
- **`AddressIndices`**: \[0\]

```text
[
    TypeID         <- 0x00000005
    Amount         <- 500000000000 = 0x000000746a528800,
    AddressIndices <- [0x00000000]
]
=
[
    // type id:
    0x00, 0x00, 0x00, 0x05,
    // amount:
    0x00, 0x00, 0x00, 0x74, 0x6a, 0x52, 0x88, 0x00,
    // length:
    0x00, 0x00, 0x00, 0x01,
    // sig[0]
    0x00, 0x00, 0x00, 0x00,
]
```

## Outputs

Outputs to Coreth Atomic Transactions are either an `EVMOutput` to be added to
the balance of an address on this chain or a `TransferableOutput` (which
contains a `SECP256K1TransferOutput`) to be moved to another chain.

The EVM Output will be used in `ImportTx` to add funds to this chain, while the
`TransferableOutput` will be used to export atomic UTXOs to another chain.

## EVM Output

Output type specifying a state change to be applied to an EVM account as part of an `ImportTx`.

### What EVM Output Contains

An EVM Output contains an `address`, `amount`, and `assetID`.

- **`Address`** is the EVM address that will receive the funds.
- **`Amount`** is the amount of the asset to be transferred (specified in nLUX
  for LUX and the smallest denomination for all other assets).
- **`AssetID`** is the ID of the asset to transfer.

### Gantt EVM Output Specification

```text
+----------+----------+-------------------------+
| address  : [20]byte |                20 bytes |
+----------+----------+-------------------------+
| amount   : uin64    |                08 bytes |
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
                      |                60 bytes |
                      +-------------------------+
```

### Proto EVM Output Specification

```text
message  {
    bytes address = 1; // 20 bytes
    uint64 amount = 2; // 08 bytes
    bytes assetID = 3; // 32 bytes
}
```

### EVM Output Example

Let's make an EVM Output:

- `Address: 0x0eb5ccb85c29009b6060decb353a38ea3b52cd20`
- `Amount: 500000000000`
- `AssetID: 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`

```text
[
    Address   <- 0x0eb5ccb85c29009b6060decb353a38ea3b52cd20,
    Amount    <- 0x000000746a528800
    AssetID   <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
]
=
[
    // address:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
    // amount:
    0x00, 0x00, 0x00, 0x74, 0x6a, 0x52, 0x88, 0x00,
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
]
```

## Transferable Output

Transferable outputs wrap a `SECP256K1TransferOutput` with an asset ID.

### What Transferable Output Contains

A transferable output contains an `AssetID` and an `Output` which is a `SECP256K1TransferOutput`.

- **`AssetID`** is a 32-byte array that defines which asset this output references.
- **`Output`** is a `SECP256K1TransferOutput` as defined below.

### Gantt Transferable Output Specification

```text
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| output   : Output   |      size(output) bytes |
+----------+----------+-------------------------+
                      | 32 + size(output) bytes |
                      +-------------------------+
```

### Proto Transferable Output Specification

```text
message TransferableOutput {
    bytes asset_id = 1; // 32 bytes
    Output output = 2;  // size(output)
}
```

### Transferable Output Example

Let's make a transferable output:

- `AssetID: 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`
- `Output: "Example SECP256K1 Transfer Output from below"`

```text
[
    AssetID <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    Output  <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
]
=
[
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    // output:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x0f, 0x42, 0x40, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x66, 0xf9, 0x0d, 0xb6,
    0x13, 0x7a, 0x78, 0xf7, 0x6b, 0x36, 0x93, 0xf7,
    0xf2, 0xbc, 0x50, 0x79, 0x56, 0xda, 0xe5, 0x63,
]
```

## SECP256K1 Transfer Output

A
[secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#cryptography-in-the-lux-virtual-machine)
transfer output allows for sending a quantity of an asset to a collection of
addresses after a specified Unix time.

### What SECP256K1 Transfer Output Contains

A secp256k1 transfer output contains a `TypeID`, `Amount`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000007`.
- **`Amount`** is a long that specifies the quantity of the asset that this output owns. Must be positive.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Transfer Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| amount    : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 28 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Transfer Output Specification

```text
message SECP256K1TransferOutput {
    uint32 typeID = 1;            // 04 bytes
    uint64 amount = 2;            // 08 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Transfer Output Example

Let's make a secp256k1 transfer output with:

- **`TypeID`**: 7
- **`Amount`**: 1000000
- **`Locktime`**: 0
- **`Threshold`**: 1
- **`Addresses`**:
  - 0x66f90db6137a78f76b3693f7f2bc507956dae563

```text
[
    TypeID    <- 0x00000007
    Amount    <- 0x00000000000f4240
    Locktime  <- 0x0000000000000000
    Threshold <- 0x00000001
    Addresses <- [
        0x66f90db6137a78f76b3693f7f2bc507956dae563
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x07,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x0f, 0x42, 0x40,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0x66, 0xf9, 0x0d, 0xb6, 0x13, 0x7a, 0x78, 0xf7,
    0x6b, 0x36, 0x93, 0xf7, 0xf2, 0xbc, 0x50, 0x79,
    0x56, 0xda, 0xe5, 0x63,
]
```

## Atomic Transactions

Atomic Transactions are used to move funds between chains. There are two types `ImportTx` and `ExportTx`.

## ExportTx

ExportTx is a transaction to export funds from Coreth to a different chain.

### What ExportTx Contains

An ExportTx contains an `typeID`, `networkID`, `blockchainID`, `destinationChain`, `inputs`, and `exportedOutputs`.

- **`typeID`** is an int that the type for an ExportTx. The typeID for an exportTx is 1.
- **`networkID`** is an int that defines which Lux network this
  transaction is meant to be issued to. This could refer to Mainnet, Testnet, etc.
  and is different than the EVM's network ID.
- **`blockchainID`** is a 32-byte array that defines which blockchain this transaction was issued to.
- **`destinationChain`** is a 32-byte array that defines which blockchain this
  transaction exports funds to.
- **`inputs`** is an array of EVM Inputs to fund the ExportTx.
- **`exportedOutputs`** is an array of TransferableOutputs to be transferred to `destinationChain`.

### Gantt ExportTx Specification

```text
+---------------------+----------------------+-------------------------------------------------+
| typeID              : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| networkID           : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| blockchainID        : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| destinationChain    : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| inputs              : []EvmInput           |                          4 + size(inputs) bytes |
+---------------------+----------------------+-------------------------------------------------+
| exportedOutputs     : []TransferableOutput |                 4 + size(exportedOutputs) bytes |
+----------+----------+----------------------+-------------------------------------------------+
                                             | 80 + size(inputs) + size(exportedOutputs) bytes |
                                             +-------------------------------------------------+
```

### ExportTx Example

Let's make an EVM Output:

- **`TypeID`**: `1`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735`
- **`DestinationChain`**: `0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf`
- **`Inputs`**:
  - `"Example EVMInput as defined above"`
- **`Exportedoutputs`**:
  - `"Example TransferableOutput as defined above"`

```text
[
    TypeID           <- 0x00000001
    NetworkID        <- 0x00003039
    BlockchainID     <- 0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735
    DestinationChain <- 0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf
    Inputs           <- [
        0xc3344128e060128ede3523a24a461c8943ab08590000000000003039000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000000000001
    ]
    ExportedOutputs  <- [
        0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2dbdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db0000000700000000000f42400000000000000000000000010000000166f90db6137a78f76b3693f7f2bc507956dae563
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x01,
    // networkID:
    0x00, 0x00, 0x00, 0x04,
    // blockchainID:
    0x91, 0x06, 0x0e, 0xab, 0xfb, 0x5a, 0x57, 0x17,
    0x20, 0x10, 0x9b, 0x58, 0x96, 0xe5, 0xff, 0x00,
    0x01, 0x0a, 0x1c, 0xfe, 0x6b, 0x10, 0x3d, 0x58,
    0x5e, 0x6e, 0xbf, 0x27, 0xb9, 0x7a, 0x17, 0x35,
    // destination_chain:
    0xd8, 0x91, 0xad, 0x56, 0x05, 0x6d, 0x9c, 0x01,
    0xf1, 0x8f, 0x43, 0xf5, 0x8b, 0x5c, 0x78, 0x4a,
    0xd0, 0x7a, 0x4a, 0x49, 0xcf, 0x3d, 0x1f, 0x11,
    0x62, 0x38, 0x04, 0xb5, 0xcb, 0xa2, 0xc6, 0xbf,
    // inputs[] count:
    0x00, 0x00, 0x00, 0x01,
    // inputs[0]
    0x8d, 0xb9, 0x7c, 0x7c, 0xec, 0xe2, 0x49, 0xc2,
    0xb9, 0x8b, 0xdc, 0x02, 0x26, 0xcc, 0x4c, 0x2a,
    0x57, 0xbf, 0x52, 0xfc, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x1e, 0x84, 0x80, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // exportedOutputs[] count
    0x00, 0x00, 0x00, 0x01,
    // exportedOutputs[0]
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x0f, 0x42, 0x40, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x66, 0xf9, 0x0d, 0xb6,
    0x13, 0x7a, 0x78, 0xf7, 0x6b, 0x36, 0x93, 0xf7,
    0xf2, 0xbc, 0x50, 0x79, 0x56, 0xda, 0xe5, 0x63,
]
```

## ImportTx

ImportTx is a transaction to import funds to Coreth from another chain.

### What ImportTx Contains

An ImportTx contains an `typeID`, `networkID`, `blockchainID`,
`destinationChain`, `importedInputs`, and `Outs`.

- **`typeID`** is an int that the type for an ImportTx. The typeID for an `ImportTx` is 0.
- **`networkID`** is an int that defines which Lux network this
  transaction is meant to be issued to. This could refer to Mainnet, Testnet, etc.
  and is different than the EVM's network ID.
- **`blockchainID`** is a 32-byte array that defines which blockchain this transaction was issued to.
- **`sourceChain`** is a 32-byte array that defines which blockchain from which to import funds.
- **`importedInputs`** is an array of TransferableInputs to fund the ImportTx.
- **`Outs`** is an array of EVM Outputs to be imported to this chain.

### Gantt ImportTx Specification

```text
+---------------------+----------------------+-------------------------------------------------+
| typeID              : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| networkID           : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| blockchainID        : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| sourceChain         : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| importedInputs      : []TransferableInput  |                  4 + size(importedInputs) bytes |
+---------------------+----------------------+-------------------------------------------------+
| outs                : []EVMOutput          |                            4 + size(outs) bytes |
+----------+----------+----------------------+-------------------------------------------------+
                                             |    80 + size(importedInputs) + size(outs) bytes |
                                             +-------------------------------------------------+
```

### ImportTx Example

Let's make an ImportTx:

- **`TypeID`**: `0`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735`
- **`SourceChain`**: `0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf`
- **`ImportedInputs`**:
  - `"Example TransferableInput as defined above"`
- **`Outs`**:
  - `"Example EVMOutput as defined above"`

```text
[
    TypeID           <- 0x00000000
    NetworkID        <- 0x00003039
    BlockchainID     <- 0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735
    SourceChain      <- 0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf
    ImportedInputs   <- [
        0x6613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e5900000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000005000000746a5288000000000100000000
    ]
    Outs             <- [
        0x0eb5ccb85c29009b6060decb353a38ea3b52cd20000000746a528800dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x00,
    // networkID:
    0x00, 0x00, 0x00, 0x04,
    // blockchainID:
    0x91, 0x06, 0x0e, 0xab, 0xfb, 0x5a, 0x57, 0x17,
    0x20, 0x10, 0x9b, 0x58, 0x96, 0xe5, 0xff, 0x00,
    0x01, 0x0a, 0x1c, 0xfe, 0x6b, 0x10, 0x3d, 0x58,
    0x5e, 0x6e, 0xbf, 0x27, 0xb9, 0x7a, 0x17, 0x35,
    // sourceChain:
    0xd8, 0x91, 0xad, 0x56, 0x05, 0x6d, 0x9c, 0x01,
    0xf1, 0x8f, 0x43, 0xf5, 0x8b, 0x5c, 0x78, 0x4a,
    0xd0, 0x7a, 0x4a, 0x49, 0xcf, 0x3d, 0x1f, 0x11,
    0x62, 0x38, 0x04, 0xb5, 0xcb, 0xa2, 0xc6, 0xbf,
    // importedInputs[] count:
    0x00, 0x00, 0x00, 0x01,
    // importedInputs[0]
    0x66, 0x13, 0xa4, 0x0d, 0xcd, 0xd8, 0xd2, 0x2e,
    0xa4, 0xaa, 0x99, 0xa4, 0xc8, 0x43, 0x49, 0x05,
    0x63, 0x17, 0xcf, 0x55, 0x0b, 0x66, 0x85, 0xe0,
    0x45, 0xe4, 0x59, 0x95, 0x4f, 0x25, 0x8e, 0x59,
    0x00, 0x00, 0x00, 0x01, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x74, 0x6a, 0x52, 0x88, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    // outs[] count
    0x00, 0x00, 0x00, 0x01,
    // outs[0]
    0x0e, 0xb5, 0xcc, 0xb8, 0x5c, 0x29, 0x00, 0x9b,
    0x60, 0x60, 0xde, 0xcb, 0x35, 0x3a, 0x38, 0xea,
    0x3b, 0x52, 0xcd, 0x20, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb,
]
```

## Credentials

Credentials have one possible type: `SECP256K1Credential`. Each credential is
paired with an Input. The order of the credentials match the order of the
inputs.

## SECP256K1 Credential

A
[secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#cryptography-in-the-lux-virtual-machine)
credential contains a list of 65-byte recoverable signatures.

### What SECP256K1 Credential Contains

- **`TypeID`** is the ID for this type. It is `0x00000009`.
- **`Signatures`** is an array of 65-byte recoverable signatures. The order of
  the signatures must match the input's signature indices.

### Gantt SECP256K1 Credential Specification

```text
+------------------------------+---------------------------------+
| type_id         : int        |                         4 bytes |
+-----------------+------------+---------------------------------+
| signatures      : [][65]byte |  4 + 65 * len(signatures) bytes |
+-----------------+------------+---------------------------------+
                               |  8 + 65 * len(signatures) bytes |
                               +---------------------------------+
```

### Proto SECP256K1 Credential Specification

```text
message SECP256K1Credential {
    uint32 typeID = 1;             // 4 bytes
    repeated bytes signatures = 2; // 4 bytes + 65 bytes * len(signatures)
}
```

### SECP256K1 Credential Example

Let's make a payment input with:

- **`TypeID`**: 9
- **`signatures`**:
  - `0x0acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a30010199dbf`

```text
[
    TypeID         <- 0x00000009
    Signatures     <- [
        0x0acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a30010199dbf,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x09,
    // length:
    0x00, 0x00, 0x00, 0x01,
    // sig[0]
    0x0a, 0xcc, 0xcf, 0x47, 0xa8, 0x20, 0x54, 0x9a,
    0x84, 0x42, 0x84, 0x40, 0xe2, 0x42, 0x19, 0x75,
    0x13, 0x87, 0x90, 0xe4, 0x1b, 0xe2, 0x62, 0xf7,
    0x19, 0x7f, 0x3d, 0x93, 0xfa, 0xa2, 0x6c, 0xc8,
    0x74, 0x10, 0x60, 0xd7, 0x43, 0xff, 0xaf, 0x02,
    0x57, 0x82, 0xc8, 0xc8, 0x6b, 0x86, 0x2d, 0x2b,
    0x9f, 0xeb, 0xeb, 0xe7, 0xd3, 0x52, 0xf0, 0xb4,
    0x59, 0x1a, 0xfb, 0xd1, 0xa7, 0x37, 0xf8, 0xa3,
    0x00, 0x10, 0x19, 0x9d, 0xbf,
]
```

## Signed Transaction

A signed transaction contains an unsigned `AtomicTx` and credentials.

### What Signed Transaction Contains

A signed transaction contains a `CodecID`, `AtomicTx`, and `Credentials`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`AtomicTx`** is an atomic transaction, as described above.
- **`Credentials`** is an array of credentials. Each credential corresponds to
  the input at the same index in the AtomicTx

### Gantt Signed Transaction Specification

```text
+---------------------+--------------+------------------------------------------------+
| codec_id            : uint16       |                                        2 bytes |
+---------------------+--------------+------------------------------------------------+
| atomic_tx           : AtomicTx     |                          size(atomic_tx) bytes |
+---------------------+--------------+------------------------------------------------+
| credentials         : []Credential |                    4 + size(credentials) bytes |
+---------------------+--------------+------------------------------------------------+
                                     |   6 + size(atomic_tx) + len(credentials) bytes |
                                     +------------------------------------------------+
```

### Proto Signed Transaction Specification

```text
message Tx {
    uint16 codec_id = 1;                 // 2 bytes
    AtomicTx atomic_tx = 2;              // size(atomic_tx)
    repeated Credential credentials = 3; // 4 bytes + size(credentials)
}
```

### Signed Transaction Example

Let's make a signed transaction that uses the unsigned transaction and credential from the previous examples.

- **`CodecID`**: `0`
- **`UnsignedTx`**: `0x000000000000303991060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf000000016613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e5900000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000005000000746a5288000000000100000000000000010eb5ccb85c29009b6060decb353a38ea3b52cd20000000746a528800dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`
- **`Credentials`**

  `0x00000009000000010acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a300`

```text
[
    CodecID            <- 0x0000
    UnsignedAtomic Tx  <- 0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Credentials        <- [
        0x00000009000000010acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a300,
    ]
]
=
[
    // Codec ID
    0x00, 0x00,
    // unsigned atomic transaction:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x91, 0x06, 0x0e, 0xab, 0xfb, 0x5a, 0x57, 0x17,
    0x20, 0x10, 0x9b, 0x58, 0x96, 0xe5, 0xff, 0x00,
    0x01, 0x0a, 0x1c, 0xfe, 0x6b, 0x10, 0x3d, 0x58,
    0x5e, 0x6e, 0xbf, 0x27, 0xb9, 0x7a, 0x17, 0x35,
    0xd8, 0x91, 0xad, 0x56, 0x05, 0x6d, 0x9c, 0x01,
    0xf1, 0x8f, 0x43, 0xf5, 0x8b, 0x5c, 0x78, 0x4a,
    0xd0, 0x7a, 0x4a, 0x49, 0xcf, 0x3d, 0x1f, 0x11,
    0x62, 0x38, 0x04, 0xb5, 0xcb, 0xa2, 0xc6, 0xbf,
    0x00, 0x00, 0x00, 0x01, 0x66, 0x13, 0xa4, 0x0d,
    0xcd, 0xd8, 0xd2, 0x2e, 0xa4, 0xaa, 0x99, 0xa4,
    0xc8, 0x43, 0x49, 0x05, 0x63, 0x17, 0xcf, 0x55,
    0x0b, 0x66, 0x85, 0xe0, 0x45, 0xe4, 0x59, 0x95,
    0x4f, 0x25, 0x8e, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x0e, 0xb5, 0xcc, 0xb8, 0x5c, 0x29, 0x00, 0x9b,
    0x60, 0x60, 0xde, 0xcb, 0x35, 0x3a, 0x38, 0xea,
    0x3b, 0x52, 0xcd, 0x20, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb,
    // number of credentials:
    0x00, 0x00, 0x00, 0x01,
    // credential[0]:
    0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x01,
    0x0a, 0xcc, 0xcf, 0x47, 0xa8, 0x20, 0x54, 0x9a,
    0x84, 0x42, 0x84, 0x40, 0xe2, 0x42, 0x19, 0x75,
    0x13, 0x87, 0x90, 0xe4, 0x1b, 0xe2, 0x62, 0xf7,
    0x19, 0x7f, 0x3d, 0x93, 0xfa, 0xa2, 0x6c, 0xc8,
    0x74, 0x10, 0x60, 0xd7, 0x43, 0xff, 0xaf, 0x02,
    0x57, 0x82, 0xc8, 0xc8, 0x6b, 0x86, 0x2d, 0x2b,
    0x9f, 0xeb, 0xeb, 0xe7, 0xd3, 0x52, 0xf0, 0xb4,
    0x59, 0x1a, 0xfb, 0xd1, 0xa7, 0x37, 0xf8, 0xa3,
    0x00,
```

## UTXO

A UTXO is a standalone representation of a transaction output.

### What UTXO Contains

A UTXO contains a `CodecID`, `TxID`, `UTXOIndex`, `AssetID`, and `Output`.

- **`CodecID`** The only valid `CodecID` is `00 00`
- **`TxID`** is a 32-byte transaction ID. Transaction IDs are calculated by
  taking sha256 of the bytes of the signed transaction.
- **`UTXOIndex`** is an int that specifies which output in the transaction
  specified by **`TxID`** that this utxo was created by.
- **`AssetID`** is a 32-byte array that defines which asset this utxo references.
- **`Output`** is the output object that created this utxo. The serialization of
  Outputs was defined above.

### Gantt UTXO Specification

```text
+--------------+----------+-------------------------+
| codec_id     : uint16   |                 2 bytes |
+--------------+----------+-------------------------+
| tx_id        : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output_index : int      |                 4 bytes |
+--------------+----------+-------------------------+
| asset_id     : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output       : Output   |      size(output) bytes |
+--------------+----------+-------------------------+
                          | 70 + size(output) bytes |
                          +-------------------------+
```

### Proto UTXO Specification

```text
message Utxo {
    uint16 codec_id = 1;     // 02 bytes
    bytes tx_id = 2;         // 32 bytes
    uint32 output_index = 3; // 04 bytes
    bytes asset_id = 4;      // 32 bytes
    Output output = 5;       // size(output)
}
```

### UTXO Example

Let's make a UTXO from the signed transaction created above:

- **`CodecID`**: `0`
- **`TxID`**: `0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7`
- **`UTXOIndex`**: 0 = 0x00000000
- **`AssetID`**: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- **`Output`**: `"Example EVMOutput as defined above"`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7
    UTXOIndex <- 0x00000000
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output    <-     0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // Codec ID:
    0x00, 0x00,
    // txID:
    0xf9, 0x66, 0x75, 0x0f, 0x43, 0x88, 0x67, 0xc3,
    0xc9, 0x82, 0x8d, 0xdc, 0xdb, 0xe6, 0x60, 0xe2,
    0x1c, 0xcd, 0xbb, 0x36, 0xa9, 0x27, 0x69, 0x58,
    0xf0, 0x11, 0xba, 0x47, 0x2f, 0x75, 0xd4, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x00,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21, 0x22, 0x23,
    0x24, 0x25, 0x26, 0x27,
]
```



# Using Explorer (/docs/primary-network/verify-contract/explorer)

---
title: Using Explorer
description: Learn how to verify a smart contract using the official Lux Explorer.
---

This document outlines the process of verifying a Smart Contract deployed on the Lux Network using the official explorer.

## Contract Deployment

1. Compile the smart contract using the tooling of your choice.

2. Deploy the compiled smart contract to the Lux network.
   - This can be done on either the mainnet or testnet (depending on your RPC configuration)

3. Upon successful deployment, you will receive:
   - A transaction hash
   - A contract address

<Callout title="Note">
Ensure you save the contract address as it will be required for the verification process.
</Callout>

## Contract Verification

1. Navigate to the official [Lux Explorer](https://subnets.lux.network/) and click on **Tools** dropdown menu to select **Smart Contract Verification** interface. You may need to open the [Testnet Explorer](https://subnets-test.lux.network/) in case the contract is deployed on Testnet Testnet.

![](/images/verification-portal.png)

2. Prepare the following files:
   - The contract's Solidity file (`.sol`)
   - The `metadata.json` file containing the ABI and metadata

3. Upload the required files:
   - Upload the contract's Solidity file
   - Upload the `metadata.json` file

4. Enter the contract address:
   - Paste the contract address obtained from the deployment step into the designated input field.

![](/images/contract-addr-input.png)

5. Initiate verification:
   - Click on the **Submit Contract** button to start the verification process.

## Next Steps

After submitting the contract for verification, your request will be processed shortly and you will see the below message.

![](/images/verification-success.png)

For any issues during deployment or verification, please reach out to the DevRel/Support team on Discord/Telegram/Slack.

# Using HardHat (/docs/primary-network/verify-contract/hardhat)

---
title: Using HardHat
description: Learn how to verify a smart contract using Hardhat.
---

{/*
  EVM Version Warning - TEMPORARY
  Remove this section when Lux adds Pectra support (after SAE implementation)
  Last reviewed: December 2025
*/}

<Callout type="warn" title="Solidity Compiler EVM Version">
Lux LUExchange-Chain and Subnet-EVM currently support the **Cancun** EVM version and do not yet support newer hardforks like **Pectra**. Since Solidity v0.8.30 changed its default target to Pectra, you must explicitly set `evmVersion` to `cancun` in your Hardhat config.

See the [sample configuration](#verifying-with-hardhat-verify) below which includes the required `evmVersion: "cancun"` setting.
</Callout>

This tutorial assumes that the contract was deployed using Hardhat and that all Hardhat dependencies are properly installed.

After deploying a smart contract one can verify the smart contract on Snowtrace in three steps:

1.  Flatten the Smart Contract
2.  Clean up the flattened contract
3.  Verify using the Snowtrace GUI

## Flatten Smart Contract using Hardhat

To flatten the contract, run the command: `npx hardhat flatten <path-to-contract> >> <flat-contract-name>.sol`

## Cleanup the Flattened Smart Contract

Some clean-up may be necessary to get the code to compile properly in the Snowtrace Contract Verifier

- Remove all but the top SPDX license.
- If the contract uses multiple SPDX licenses, use both licenses by adding **AND**: `SPDX-License-Identifier: MIT AND BSD-3-Clause`

## Verify Smart Contract using Snowtrace UI

Snowtrace is currently working on a new user interface (UI) for smart contract verification. Meanwhile, you may consider using their API for a seamless smart contract verification experience.

## Verify Smart Contract Programmatically Using APIs

Ensure you have Postman or any other API platform installed on your computer (or accessible through online services), along with your contract's source code and the parameters utilized during deployment.

Here is the API call URL to use for a POST request: `https://api.snowtrace.io/api?module=contract&action=verifysourcecode`

Please note that this URL is specifically configured for verifying contracts on the Lux LUExchange-Chain Mainnet. If you intend to verify on the Testnet Testnet, use: `https://api-testnet.snowtrace.io/api?module=contract&action=verifysourcecode`

Here's the body of the API call with the required parameters:

```json
{
  "contractaddress": "YOUR_CONTRACT_ADDRESS",
  "sourceCode": "YOUR_FLATTENED_SOURCE_CODE",
  "codeformat": "solidity-single-file",
  "contractname": "YOUR_CONTRACT_NAME",
  "compilerversion": "YOUR_COMPILER_VERSION",
  "optimizationUsed": "YOUR_OPTIMIZATION_VALUE",  // 0 if not optimized, 1 if optimized
  "runs": "YOUR_OPTIMIZATION_RUNS",  // remove if not applicable
  "licenseType": "YOUR_LICENSE_TYPE",  // 1 if not specified
  "apikey": "API_KEY_PLACEHOLDER", // you don't need an API key, use a placeholder
  "evmversion": "YOUR_EVM_VERSION_ON_REMIX",
  "constructorArguments": "YOUR_CONSTRUCTOR_ARGUMENTS"  // Remove if not applicable
}
```

## Verifying with Hardhat-Verify

This part of the tutorial assumes that the contract was deployed using Hardhat and that all Hardhat dependencies are properly installed to include `'@nomiclabs/hardhat-etherscan'`.

You will need to create a `.env.json` with your _Wallet Seed Phrase_. You don't need an API key to verify on Snowtrace.

Example `.env.json`:

```json title=".env.json"
{
  "MNEMONIC": "your-wallet-seed-phrase",
}
```

Below is a sample `hardhat.config.ts` used for deployment and verification:

```ts title="hardhat.config.ts"
import { task } from "hardhat/config"
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers"
import { BigNumber } from "ethers"
import "@typechain/hardhat"
import "@nomiclabs/hardhat-ethers"
import "@nomiclabs/hardhat-waffle"
import "hardhat-gas-reporter"
import "@nomiclabs/hardhat-etherscan"
import { MNEMONIC, APIKEY } from "./.env.json"

// When using the hardhat network, you may choose to fork Testnet or Lux Mainnet
// This will allow you to debug contracts using the hardhat network while keeping the current network state
// To enable forking, turn one of these booleans on, and then run your tasks/scripts using ``--network hardhat``
// For more information go to the hardhat guide
// https://hardhat.org/hardhat-network/
// https://hardhat.org/guides/mainnet-forking.html
const FORK_FUJI = false
const FORK_MAINNET = false
const forkingData = FORK_FUJI
  ? {
      url: "https://api.lux-test.network/ext/bc/C/rpc",
    }
  : FORK_MAINNET
  ? {
      url: "https://api.lux.network/ext/bc/C/rpc",
    }
  : undefined

task(
  "accounts",
  "Prints the list of accounts",
  async (args, hre): Promise<void> => {
    const accounts: SignerWithAddress[] = await hre.ethers.getSigners()
    accounts.forEach((account: SignerWithAddress): void => {
      console.log(account.address)
    })
  }
)

task(
  "balances",
  "Prints the list of LUX account balances",
  async (args, hre): Promise<void> => {
    const accounts: SignerWithAddress[] = await hre.ethers.getSigners()
    for (const account of accounts) {
      const balance: BigNumber = await hre.ethers.provider.getBalance(
        account.address
      )
      console.log(`${account.address} has balance ${balance.toString()}`)
    }
  }
)
export default {
  etherscan: {
    // Your don't need an API key for Snowtrace
  },

  solidity: {
    version: "0.8.30",
    settings: {
      evmVersion: "cancun", // Required for Lux
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  networks: {
    hardhat: {
      gasPrice: 225000000000,
      chainId: 43114, //Only specify a chainId if we are not forking
      // forking: {
      //   url: 'https://api.lux.network/ext/bc/C/rpc',
      // },
    },
    testnet: {
      url: "https://api.lux-test.network/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43113,
      accounts: { mnemonic: MNEMONIC },
    },
    mainnet: {
      url: "https://api.lux.network/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43114,
      accounts: { mnemonic: MNEMONIC },
    },
  },
}
```

Once the contract is deployed, verify with hardhat verify by running the following:

```bash
npx hardhat verify <contract address> <arguments> --network <network>
```

Example:

```bash
npx hardhat verify 0x3972c87769886C4f1Ff3a8b52bc57738E82192D5 MockNFT Mock ipfs://QmQ2RFEmZaMds8bRjZCTJxo4DusvcBdLTS6XuDbhp5BZjY 100 --network testnet
```

You can also verify contracts programmatically via script. Example:

```ts title="verify.ts"
import console from "console"
const hre = require("hardhat")

// Define the NFT
const name = "MockNFT"
const symbol = "Mock"
const _metadataUri = "ipfs://QmQ2RFEmZaMds8bRjZCTJxo4DusvcBdLTS6XuDbhp5BZjY"
const _maxTokens = "100"

async function main() {
  await hre.run("verify:verify", {
    address: "0x3972c87769886C4f1Ff3a8b52bc57738E82192D5",
    constructorArguments: [name, symbol, _metadataUri, _maxTokens],
  })
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })
```

First create your script, then execute it via hardhat by running the following:

```bash
npx hardhat run scripts/verify.ts --network testnet
```

Verifying via terminal will not allow you to pass an array as an argument, however, you can do this when verifying via script by including the array in your _Constructor Arguments_. Example: 

```ts
import console from "console"
const hre = require("hardhat")

// Define the NFT
const name = "MockNFT"
const symbol = "Mock"
const _metadataUri =
  "ipfs://QmQn2jepp3jZ3tVxoCisMMF8kSi8c5uPKYxd71xGWG38hV/Example"
const _royaltyRecipient = "0xcd3b766ccdd6ae721141f452c550ca635964ce71"
const _royaltyValue = "50000000000000000"
const _custodians = [
  "0x8626f6940e2eb28930efb4cef49b2d1f2c9c1199",
  "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "0xdd2fd4581271e230360230f9337d5c0430bf44c0",
]
const _saleLength = "172800"
const _claimAddress = "0xcd3b766ccdd6ae721141f452c550ca635964ce71"

async function main() {
  await hre.run("verify:verify", {
    address: "0x08bf160B8e56899723f2E6F9780535241F145470",
    constructorArguments: [
      name,
      symbol,
      _metadataUri,
      _royaltyRecipient,
      _royaltyValue,
      _custodians,
      _saleLength,
      _claimAddress,
    ],
  })
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })
```



# Using Snowtrace (/docs/primary-network/verify-contract/snowtrace)

---
title: Using Snowtrace
description: Learn how to verify a contract on the Lux C-chain using Snowtrace.
---

The LUExchange-Chain Explorer supports verifying smart contracts, allowing users to review it. The Mainnet LUExchange-Chain Explorer is [here](https://snowtrace.io/) and the Testnet Testnet Explorer is [here.](https://testnet.snowtrace.io/)

If you have issues, contact us on [Discord](https://chat.avalabs.org/).

## Steps

Navigate to the _Contract_ tab at the Explorer page for your contract's address.

![verify and publish](/images/snowtrace1.png)

Click _Verify & Publish_ to enter the smart contract verification page.

![SRC](/images/snowtrace2.png)

[Libraries](https://docs.soliditylang.org/en/v0.8.4/contracts.html?highlight=libraries#libraries) can be provided. If they are, they must be deployed, independently verified and in the _Add Contract Libraries_ section.

![libraries](/images/snowtrace3.png)

The LUExchange-Chain Explorer can fetch constructor arguments automatically for simple smart contracts. More complicated contracts might require you to pass in special constructor arguments. Smart contracts with complicated constructors may have validation issues (see the Caveats section below). You can try this [online ABI encoder](https://abi.hashex.org/).

## Requirements

- **IMPORTANT** Contracts should be verified on Testnet before being deployed to Mainnet to ensure there are no issues.
- Contracts must be flattened. Includes will not work.
- Contracts should be compile-able in [Remix](https://remix.ethereum.org/). A flattened contract with `pragma experimental ABIEncoderV2` (as an example) can create unusual binary and/or constructor blobs. This might cause validation issues.
- The LUExchange-Chain Explorer **only** validates [solc JavaScript](https://github.com/ethereum/solc-bin) and only supports [Solidity](https://docs.soliditylang.org/) contracts.

## Libraries

The compile bytecode will identify if there are external libraries. If you released with Remix, you will also see multiple transactions created.

```
{
  "linkReferences": {
    "contracts/Storage.sol": {
      "MathUtils": [
        {
          "length": 20,
          "start": 3203
        }
        ...
      ]
    }
  },
  "object": "....",
  ...
}
```

This requires you to add external libraries in order to verify the code.

A library can have dependent libraries. To verify a library, the hierarchy of dependencies will need to be provided to the LUExchange-Chain Explorer. Verification may fail if you provide more than the library plus any dependencies (that is you might need to prune the Solidity code to exclude anything but the necessary classes).

You can also see references in the byte code in the form `__$75f20d36....$__`. The keccak256 hash is generated from the library name.

Example [online converter](https://emn178.github.io/online-tools/keccak_256.html): `contracts/Storage.sol:MathUtils` => `75f20d361629befd780a5bd3159f017ee0f8283bdb6da80805f83e829337fd12`

## Examples

- [SwapFlashLoan](https://testnet.snowtrace.io/address/0x12DF75Fed4DEd309477C94cE491c67460727C0E8/contract/43113/code)

SwapFlashLoan uses `swaputils` and `mathutils`:

- [SwapUtils](https://testnet.snowtrace.io/address/0x6703e4660E104Af1cD70095e2FeC337dcE034dc1/contract/43113/code)

SwapUtils requires mathutils:

- [MathUtils](https://testnet.snowtrace.io/address/0xbA21C84E4e593CB1c6Fe6FCba340fa7795476966/contract/43113/code)

## Caveats

### SPDX License Required

An SPDX must be provided.

```solidity
// SPDX-License-Identifier: ...
```

### `keccak256` Strings Processed

The LUExchange-Chain Explorer interprets all keccak256(...) strings, even those in comments. This can cause issues with constructor arguments.

```solidity
/// keccak256("1");
keccak256("2");
```

This could cause automatic constructor verification failures. If you receive errors about constructor arguments they can be provided in ABI hex encoded form on the contract verification page.

### Solidity Constructors

Constructors and inherited constructors can cause problems verifying the constructor arguments. Example:

```solidity
abstract contract Parent {
  constructor () {
    address msgSender = ...;
    emit Something(address(0), msgSender);
  }
}
contract Main is Parent {
  constructor (
          string memory _name,
          address deposit,
          uint fee
  ) {
    ...
  }
}
```

If you receive errors about constructor arguments, they can be provided in ABI hex encoded form on the contract verification page.


# LuxGo Platform-Chain RPC (/docs/rpcs/p-chain)

---
title: "LuxGo Platform-Chain RPC"
description: "This page is an overview of the Platform-Chain RPC associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/vms/platformvm/service.md
---

The Platform-Chain API allows clients to interact with the [Platform-Chain](https://build.lux.network/docs/quick-start/primary-network#p-chain), which maintains Lux’s validator set and handles blockchain creation.

## Endpoint

```
/ext/bc/P
```

## Format

This API uses the `json 2.0` RPC format.

## Methods

### `platform.getBalance`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

</Callout>

Get the balance of LUX controlled by a given address.

**Signature:**

```
platform.getBalance({
    addresses: []string
}) -> {
    balances: string -> int,
    unlockeds: string -> int,
    lockedStakeables: string -> int,
    lockedNotStakeables: string -> int,
    utxoIDs: []{
        txID: string,
        outputIndex: int
    }
}
```

- `addresses` are the addresses to get the balance of.
- `balances` is a map from assetID to the total balance.
- `unlockeds` is a map from assetID to the unlocked balance.
- `lockedStakeables` is a map from assetID to the locked stakeable balance.
- `lockedNotStakeables` is a map from assetID to the locked and not stakeable balance.
- `utxoIDs` are the IDs of the UTXOs that reference `address`.

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"platform.getBalance",
  "params" :{
      "addresses":["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"]
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balance": "30000000000000000",
    "unlocked": "20000000000000000",
    "lockedStakeable": "10000000000000000",
    "lockedNotStakeable": "0",
    "balances": {
      "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "30000000000000000"
    },
    "unlockeds": {
      "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "20000000000000000"
    },
    "lockedStakeables": {
      "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "10000000000000000"
    },
    "lockedNotStakeables": {},
    "utxoIDs": [
      {
        "txID": "11111111111111111111111111111111LpoYY",
        "outputIndex": 1
      },
      {
        "txID": "11111111111111111111111111111111LpoYY",
        "outputIndex": 0
      }
    ]
  },
  "id": 1
}
```

### `platform.getBlock`

Get a block by its ID.

**Signature:**

```
platform.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the block encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlock",
    "params": {
        "blockID": "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000000309473dc99a0851a29174d84e522da8ccb1a56ac23f7b0ba79f80acce34cf576900000000000f4241000000010000001200000001000000000000000000000000000000000000000000000000000000000000000000000000000000011c4c57e1bcb3c567f9f03caa75563502d1a21393173c06d9d79ea247b20e24800000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000000338e0465f0000000100000000000000000427d4b22a2a78bcddd456742caf91b56badbff985ee19aef14573e7343fd6520000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000338d1041f0000000000000000000000010000000195a4467dd8f939554ea4e6501c08294386938cbf000000010000000900000001c79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed738580119286dde",
    "encoding": "hex"
  },
  "id": 1
}
```

#### JSON Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlock",
    "params": {
        "blockID": "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
        "encoding": "json"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": {
      "parentID": "5615di9ytxujackzaXNrVuWQy5y8Yrt8chPCscMr5Ku9YxJ1S",
      "height": 1000001,
      "txs": [
        {
          "unsignedTx": {
            "inputs": {
              "networkID": 1,
              "blockchainID": "11111111111111111111111111111111LpoYY",
              "outputs": [],
              "inputs": [
                {
                  "txID": "DTqiagiMFdqbNQ62V2Gt1GddTVLkKUk2caGr4pyza9hTtsfta",
                  "outputIndex": 0,
                  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                  "input": {
                    "amount": 13839124063,
                    "signatureIndices": [0]
                  }
                }
              ],
              "memo": "0x"
            },
            "destinationChain": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5",
            "exportedOutputs": [
              {
                "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                "output": {
                  "addresses": [
                    "P-lux1jkjyvlwclyu42n4yuegpczpfgwrf8r9lyj0d3c"
                  ],
                  "amount": 13838124063,
                  "locktime": 0,
                  "threshold": 1
                }
              }
            ]
          },
          "credentials": [
            {
              "signatures": [
                "0xc79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed7385801"
              ]
            }
          ]
        }
      ]
    },
    "encoding": "json"
  },
  "id": 1
}
```

### `platform.getBlockByHeight`

Get a block by its height.

**Signature:**

```
platform.getBlockByHeight({
    height: int
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `height` is the block height.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the block encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockByHeight",
    "params": {
        "height": 1000001,
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000000309473dc99a0851a29174d84e522da8ccb1a56ac23f7b0ba79f80acce34cf576900000000000f4241000000010000001200000001000000000000000000000000000000000000000000000000000000000000000000000000000000011c4c57e1bcb3c567f9f03caa75563502d1a21393173c06d9d79ea247b20e24800000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000000338e0465f0000000100000000000000000427d4b22a2a78bcddd456742caf91b56badbff985ee19aef14573e7343fd6520000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000338d1041f0000000000000000000000010000000195a4467dd8f939554ea4e6501c08294386938cbf000000010000000900000001c79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed738580119286dde",
    "encoding": "hex"
  },
  "id": 1
}
```

#### JSON Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockByHeight",
    "params": {
        "height": 1000001,
        "encoding": "json"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": {
      "parentID": "5615di9ytxujackzaXNrVuWQy5y8Yrt8chPCscMr5Ku9YxJ1S",
      "height": 1000001,
      "txs": [
        {
          "unsignedTx": {
            "inputs": {
              "networkID": 1,
              "blockchainID": "11111111111111111111111111111111LpoYY",
              "outputs": [],
              "inputs": [
                {
                  "txID": "DTqiagiMFdqbNQ62V2Gt1GddTVLkKUk2caGr4pyza9hTtsfta",
                  "outputIndex": 0,
                  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                  "input": {
                    "amount": 13839124063,
                    "signatureIndices": [0]
                  }
                }
              ],
              "memo": "0x"
            },
            "destinationChain": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5",
            "exportedOutputs": [
              {
                "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                "output": {
                  "addresses": [
                    "P-lux1jkjyvlwclyu42n4yuegpczpfgwrf8r9lyj0d3c"
                  ],
                  "amount": 13838124063,
                  "locktime": 0,
                  "threshold": 1
                }
              }
            ]
          },
          "credentials": [
            {
              "signatures": [
                "0xc79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed7385801"
              ]
            }
          ]
        }
      ]
    },
    "encoding": "json"
  },
  "id": 1
}
```

### `platform.getBlockchains`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

</Callout>

Get all the blockchains that exist (excluding the Platform-Chain).

**Signature:**

```
platform.getBlockchains() ->
{
  blockchains: []{
    id: string,
    name: string,
    subnetID: string,
    vmID: string
  }
}
```

- `blockchains` is all of the blockchains that exists on the Lux network.
- `name` is the human-readable name of this blockchain.
- `id` is the blockchain’s ID.
- `subnetID` is the ID of the Subnet that validates this blockchain.
- `vmID` is the ID of the Virtual Machine the blockchain runs.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockchains",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "blockchains": [
      {
        "id": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "name": "Exchange-Chain",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq"
      },
      {
        "id": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5",
        "name": "LUExchange-Chain",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "mgj786NP7uDwBCcq6YwThhaN8FLyybkCa4zBWTQbNgmK6k9A6"
      },
      {
        "id": "CqhF97NNugqYLiGaQJ2xckfmkEr8uNeGG5TQbyGcgnZ5ahQwa",
        "name": "Simple DAG Payments",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "sqjdyTKUSrQs1YmKDTUbdUhdstSdtRTGRbUn8sqK8B6pkZkz1"
      },
      {
        "id": "VcqKNBJsYanhVFxGyQE5CyNVYxL3ZFD7cnKptKWeVikJKQkjv",
        "name": "Simple Chain Payments",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "sqjchUjzDqDfBPGjfQq2tXW1UCwZTyvzAWHsNzF2cb1eVHt6w"
      },
      {
        "id": "2SMYrx4Dj6QqCEA3WjnUTYEFSnpqVTwyV3GPNgQqQZbBbFgoJX",
        "name": "Simple Timestamp Server",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH"
      },
      {
        "id": "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN",
        "name": "My new timestamp",
        "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
        "vmID": "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH"
      },
      {
        "id": "2TtHFqEAAJ6b33dromYMqfgavGPF3iCpdG3hwNMiart2aB5QHi",
        "name": "My new XVM",
        "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
        "vmID": "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq"
      }
    ]
  },
  "id": 1
}
```

### `platform.getBlockchainStatus`

Get the status of a blockchain.

**Signature:**

```
platform.getBlockchainStatus(
  {
    blockchainID: string
  }
) -> {status: string}
```

`status` is one of:

- `Validating`: The blockchain is being validated by this node.
- `Created`: The blockchain exists but isn’t being validated by this node.
- `Preferred`: The blockchain was proposed to be created and is likely to be created but the
  transaction isn’t yet accepted.
- `Syncing`: This node is participating in this blockchain as a non-validating node.
- `Unknown`: The blockchain either wasn’t proposed or the proposal to create it isn’t preferred. The
  proposal may be resubmitted.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockchainStatus",
    "params":{
        "blockchainID":"2NbS4dwGaf2p1MaXb65PrkZdXRwmSX4ZzGnUu7jm3aykgThuZE"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "Created"
  },
  "id": 1
}
```

### `platform.getCurrentSupply`

Returns an upper bound on amount of tokens that exist that can stake the requested Subnet. This is
an upper bound because it does not account for burnt tokens, including transaction fees.

**Signature:**

```
platform.getCurrentSupply ({
  subnetID: string // optional
}) -> { supply: int }
```

- `supply` is an upper bound on the number of tokens that exist.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getCurrentSupply",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "supply": "365865167637779183"
  },
  "id": 1
}
```

The response in this example indicates that LUX’s supply is at most 365.865 million.

### `platform.getCurrentValidators`

List the current validators of the given Subnet.

**Signature:**

```
platform.getCurrentValidators({
  subnetID: string, // optional
  nodeIDs: string[], // optional
}) -> {
    validators: []{
        txID: string,
        startTime: string,
        endTime: string,
        nodeID: string,
        weight: string,
        validationID: string,
        publicKey: string,
        remainingBalanceOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        deactivationOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        minNonce: string,
        balance: string,
        validationRewardOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        delegationRewardOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        potentialReward: string,
        delegationFee: string,
        uptime: string,
        connected: bool,
        signer: {
            publicKey: string,
            proofOfPosession: string
        },
        delegatorCount: string,
        delegatorWeight: string,
        delegators: []{
            txID: string,
            startTime: string,
            endTime: string,
            weight: string,
            nodeID: string,
            rewardOwner: {
                locktime: string,
                threshold: string,
                addresses: string[]
            },
            potentialReward: string,
        }
    }
}
```

- `subnetID` is the Subnet whose current validators are returned. If omitted, returns the current
  validators of the Primary Network.
- `nodeIDs` is a list of the NodeIDs of current validators to request. If omitted, all current
  validators are returned. If a specified NodeID is not in the set of current validators, it will
  not be included in the response.
- `validators` can include different fields based on the subnet type (L1, PoA Subnets, the Primary Network):
  - `txID` is the validator transaction.
  - `startTime` is the Unix time when the validator starts validating the Subnet.
  - `endTime` is the Unix time when the validator stops validating the Subnet. Omitted if `subnetID` is a L1 Subnet.
  - `nodeID` is the validator’s node ID.
  - `weight` is the validator’s weight (stake) when sampling validators.
  - `validationID` is the ID for L1 subnet validator registration transaction. Omitted if `subnetID` is not an L1 Subnet.
  - `publicKey` is the compressed BLS public key of the validator. Omitted if `subnetID` is not an L1 Subnet.
  - `remainingBalanceOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that will receive any withdrawn balance. Omitted if `subnetID` is not an L1 Subnet.
  - `deactivationOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that can withdraw the balance. Omitted if `subnetID` is not an L1 Subnet.
  - `minNonce` is minimum nonce that must be included in a `SetL1ValidatorWeightTx` for the transaction to be valid. Omitted if `subnetID` is not an L1 Subnet.
  - `balance` is current remaining balance that can be used to pay for the validators continuous fee. Omitted if `subnetID` is not an L1 Subnet.
  - `validationRewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and
    array of `addresses`. Specifies the owner of the potential reward earned from staking. Omitted
    if `subnetID` is not the Primary Network.
  - `delegationRewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and
    array of `addresses`. Specifies the owner of the potential reward earned from delegations. Omitted if `subnetID` is not the Primary Network.
  - `potentialReward` is the potential reward earned from staking. Omitted if `subnetID` is not the Primary Network.
  - `delegationFeeRate` is the percent fee this validator charges when others delegate stake to
    them. Omitted if `subnetID` is not the Primary Network.
  - `uptime` is the % of time the queried node has reported the peer as online and validating the
    Subnet. Omitted if `subnetID` is not the Primary Network.
  - `connected` is if the node is connected and tracks the Subnet. Omitted if `subnetID` is not the Primary Network.
  - `signer` is the node's BLS public key and proof of possession. Omitted if the validator doesn't
    have a BLS public key. Omitted if `subnetID` is not the Primary Network.
  - `delegatorCount` is the number of delegators on this validator.
    Omitted if `subnetID` is not the Primary Network.
  - `delegatorWeight` is total weight of delegators on this validator.
    Omitted if `subnetID` is not the Primary Network.
  - `delegators` is the list of delegators to this validator. Omitted if `subnetID` is not the Primary Network. Omitted unless `nodeIDs` specifies a single NodeID.
    - `txID` is the delegator transaction.
    - `startTime` is the Unix time when the delegator started.
    - `endTime` is the Unix time when the delegator stops.
    - `weight` is the amount of nLUX this delegator staked.
    - `nodeID` is the validating node’s node ID.
    - `rewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and array of
      `addresses`.
    - `potentialReward` is the potential reward earned from staking

Note: An L1 Subnet can include both initial legacy PoA validators (before L1 conversion) and L1 validators. The response will include both types of validators.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getCurrentValidators",
    "params": {
      "nodeIDs": ["NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD"]
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response (Primary Network):**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "2NNkpYTGfTFLSGXJcHtVv6drwVU2cczhmjK2uhvwDyxwsjzZMm",
        "startTime": "1600368632",
        "endTime": "1602960455",
        "weight": "2000000000000",
        "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
        "validationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": ["P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"]
        },
        "delegationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": ["P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"]
        },
        "potentialReward": "117431493426",
        "delegationFee": "10.0000",
        "uptime": "0.0000",
        "connected": false,
        "delegatorCount": "1",
        "delegatorWeight": "25000000000",
        "delegators": [
          {
            "txID": "Bbai8nzGVcyn2VmeYcbS74zfjJLjDacGNVuzuvAQkHn1uWfoV",
            "startTime": "1600368523",
            "endTime": "1602960342",
            "weight": "25000000000",
            "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
            "rewardOwner": {
              "locktime": "0",
              "threshold": "1",
              "addresses": ["P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"]
            },
            "potentialReward": "11743144774"
          }
        ]
      }
    ]
  },
  "id": 1
}
```

**Example Response (L1):**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "validationID": "2wTscvX3JUsMbZHFRd9t8Ywz2q9j2BmETg8cTvgUHgawjbSvZX",
        "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
        "publicKey": "0x91951771ff32b1a985a4936592bce8512a986353c4c2eb5a0f12dbb76bda3a0a0c975e26413ff44c0ee9d8d689eff8ed",
        "remainingBalanceOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-testnet1ywzvrftfqexh5g6qa9zyrytj6pqdfetza2hqln"
          ]
        },
        "deactivationOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-testnet1ywzvrftfqexh5g6qa9zyrytj6pqdfetza2hqln"
          ]
        },
        "startTime": "1734034648",
        "weight": "20",
        "minNonce": "0",
        "balance": "8780477952"
      }
    ]
  },
  "id": 1
}
```

### `platform.getFeeConfig`

Returns the dynamic fee configuration of the P-chain.

**Signature:**

```
platform.getFeeConfig() -> {
  weights: []uint64,
  maxCapacity: uint64,
  maxPerSecond: uint64,
  targetPerSecond: uint64,
  minPrice: uint64,
  excessConversionConstant: uint64
}
```

- `weights` to merge fee dimensions into a single gas value
- `maxCapacity` is the amount of gas the chain is allowed to store for future use
- `maxPerSecond` is the amount of gas the chain is allowed to consume per second
- `targetPerSecond` is the target amount of gas the chain should consume per second to keep fees stable
- `minPrice` is the minimum price per unit of gas
- `excessConversionConstant` is used to convert excess gas to a gas price

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getFeeConfig",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "weights": [1, 1000, 1000, 4],
    "maxCapacity": 1000000,
    "maxPerSecond": 100000,
    "targetPerSecond": 50000,
    "minPrice": 1,
    "excessConversionConstant": 2164043
  },
  "id": 1
}
```

### `platform.getFeeState`

Returns the current fee state of the P-chain.

**Signature:**

```
platform.getFeeState() -> {
  capacity: uint64,
  excess: uint64,
  price: uint64,
  timestamp: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getFeeState",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "capacity": 973044,
    "excess": 26956,
    "price": 1,
    "timestamp": "2024-12-16T17:19:07Z"
  },
  "id": 1
}
```

### `platform.getHeight`

Returns the height of the last accepted block.

**Signature:**

```
platform.getHeight() ->
{
  height: int,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "56"
  },
  "id": 1
}
```

### `platform.getL1Validator`

Returns a current L1 validator.

**Signature:**

```
platform.getL1Validator({
    validationID: string,
}) -> {
    validationID: string,
    subnetID: string,
    nodeID: string,
    publicKey: string,
    remainingBalanceOwner: {
      locktime: string,
      threshold: string,
      addresses: string[]
    },
    deactivationOwner: {
      locktime: string,
      threshold: string,
      addresses: string[]
    },
    startTime: string,
    weight: string,
    minNonce: string,
    balance: string,
    height: string
}
```

- `validationID` is the ID for L1 subnet validator registration transaction.
- `subnetID` is the L1 this validator is validating.
- `nodeID` is the node ID of the validator.
- `publicKey` is the compressed BLS public key of the validator.
- `remainingBalanceOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that will receive any withdrawn balance.
- `deactivationOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that can withdraw the balance.
- `startTime` is the unix timestamp, in seconds, of when this validator was added to the validator set.
- `weight` is weight of this validator used for consensus voting and ICM.
- `minNonce` is minimum nonce that must be included in a `SetL1ValidatorWeightTx` for the transaction to be valid.
- `balance` is current remaining balance that can be used to pay for the validators continuous fee.
- `height` is height of the last accepted block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getL1Validator",
    "params": {
      "validationID": ["9FAftNgNBrzHUMMApsSyV6RcFiL9UmCbvsCu28xdLV2mQ7CMo"]
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "subnetID": "2DeHa7Qb6sufPkmQcFWG2uCd4pBPv9WB6dkzroiMQhd1NSRtof",
    "nodeID": "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
    "validationID": "9FAftNgNBrzHUMMApsSyV6RcFiL9UmCbvsCu28xdLV2mQ7CMo",
    "publicKey": "0x900c9b119b5c82d781d4b49be78c3fc7ae65f2b435b7ed9e3a8b9a03e475edff86d8a64827fec8db23a6f236afbf127d",
    "remainingBalanceOwner": {
      "locktime": "0",
      "threshold": "0",
      "addresses": []
    },
    "deactivationOwner": {
      "locktime": "0",
      "threshold": "0",
      "addresses": []
    },
    "startTime": "1731445206",
    "weight": "49463",
    "minNonce": "0",
    "balance": "1000000000",
    "height": "3"
  },
  "id": 1
}
```

### `platform.getProposedHeight`

Returns this node's current proposer VM height

**Signature:**

```
platform.getProposedHeight() ->
{
  height: int,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getProposedHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "56"
  },
  "id": 1
}
```

### `platform.getMinStake`

Get the minimum amount of tokens required to validate the requested Subnet and the minimum amount of
tokens that can be delegated.

**Signature:**

```
platform.getMinStake({
  subnetID: string // optional
}) ->
{
  minValidatorStake : uint64,
  minDelegatorStake : uint64
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getMinStake",
    "params": {
        "subnetID":"11111111111111111111111111111111LpoYY"
    },
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "minValidatorStake": "2000000000000",
    "minDelegatorStake": "25000000000"
  },
  "id": 1
}
```

### `platform.getRewardUTXOs`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

</Callout>

Returns the UTXOs that were rewarded after the provided transaction's staking or delegation period
ended.

**Signature:**

```
platform.getRewardUTXOs({
    txID: string,
    encoding: string // optional
}) -> {
    numFetched: integer,
    utxos: []string,
    encoding: string
}
```

- `txID` is the ID of the staking or delegating transaction
- `numFetched` is the number of returned UTXOs
- `utxos` is an array of encoded reward UTXOs
- `encoding` specifies the format for the returned UTXOs. Can only be `hex` when a value is
  provided.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getRewardUTXOs",
    "params": {
        "txID": "2nmH8LithVbdjaXsxVQCQfXtzN9hBbmebrsaEYnLM9T32Uy2Y5"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "2",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a"
    ],
    "encoding": "hex"
  },
  "id": 1
}
```

### `platform.getStake`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

</Callout>

Get the amount of nLUX staked by a set of addresses. The amount returned does not include staking
rewards.

**Signature:**

```
platform.getStake({
    addresses: []string,
    validatorsOnly: true or false
}) ->
{
    stakeds: string -> int,
    stakedOutputs:  []string,
    encoding: string
}
```

- `addresses` are the addresses to get information about.
- `validatorsOnly` can be either `true` or `false`. If `true`, will skip checking delegators for stake.
- `stakeds` is a map from assetID to the amount staked by addresses provided.
- `stakedOutputs` are the string representation of staked outputs.
- `encoding` specifies the format for the returned outputs.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getStake",
    "params": {
        "addresses": [
            "P-lux1pmgmagjcljjzuz2ve339dx82khm7q8getlegte"
          ],
        "validatorsOnly": true
    },
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "staked": "6500000000000",
    "stakeds": {
      "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z": "6500000000000"
    },
    "stakedOutputs": [
      "0x000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff00000007000005e96630e800000000000000000000000001000000011f1c933f38da6ba0ba46f8c1b0a7040a9a991a80dd338ed1"
    ],
    "encoding": "hex"
  },
  "id": 1
}
```

### `platform.getStakingAssetID`

Retrieve an assetID for a Subnet’s staking asset.

**Signature:**

```
platform.getStakingAssetID({
    subnetID: string // optional
}) -> {
    assetID: string
}
```

- `subnetID` is the Subnet whose assetID is requested.
- `assetID` is the assetID for a Subnet’s staking asset.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getStakingAssetID",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "assetID": "2fombhL7aGPwj3KH4bfrmJwW6PVnMobf9Y2fn9GwxiAAJyFDbe"
  },
  "id": 1
}
```

<Callout title="Note">

The AssetID for LUX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

</Callout>

### `platform.getSubnet`

Get owners and info about the Subnet or L1.

**Signature:**

```
platform.getSubnet({
    subnetID: string
}) ->
{
    isPermissioned: bool,
    controlKeys: []string,
    threshold: string,
    locktime: string,
    subnetTransformationTxID: string,
    conversionID: string,
    managerChainID: string,
    managerAddress: string
}
```

- `subnetID` is the ID of the Subnet to get information about. If omitted, fails.
- `threshold` signatures from addresses in `controlKeys` are needed to make changes to
  a permissioned subnet. If the Subnet is not a PoA Subnet, then `threshold` will be `0` and `controlKeys`
  will be empty.
- changes can not be made into the subnet until `locktime` is in the past.
- `subnetTransformationTxID` is the ID of the transaction that changed the subnet into an elastic one, if it exists.
- `conversionID` is the ID of the conversion from a permissioned Subnet into an L1, if it exists.
- `managerChainID` is the ChainID that has the ability to modify this L1s validator set, if it exists.
- `managerAddress` is the address that has the ability to modify this L1s validator set, if it exists.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getSubnet",
    "params": {"subnetID":"Vz2ArUpigHt7fyE79uF3gAXvTPLJi2LGgZoMpgNPHowUZJxBb"},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isPermissioned": true,
    "controlKeys": [
      "P-testnet1ztvstx6naeg6aarfd047fzppdt8v4gsah88e0c",
      "P-testnet193kvt4grqewv6ce2x59wnhydr88xwdgfcedyr3"
    ],
    "threshold": "1",
    "locktime": "0",
    "subnetTransformationTxID": "11111111111111111111111111111111LpoYY",
    "conversionID": "11111111111111111111111111111111LpoYY",
    "managerChainID": "11111111111111111111111111111111LpoYY",
    "managerAddress": null
  },
  "id": 1
}
```

### `platform.getSubnets`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

</Callout>

Get info about the Subnets.

**Signature:**

```
platform.getSubnets({
    ids: []string
}) ->
{
    subnets: []{
        id: string,
        controlKeys: []string,
        threshold: string
    }
}
```

- `ids` are the IDs of the Subnets to get information about. If omitted, gets information about all
  Subnets.
- `id` is the Subnet’s ID.
- `threshold` signatures from addresses in `controlKeys` are needed to add a validator to the
  Subnet. If the Subnet is not a PoA Subnet, then `threshold` will be `0` and `controlKeys` will be
  empty.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getSubnets",
    "params": {"ids":["hW8Ma7dLMA7o4xmJf3AXBbo17bXzE7xnThUd3ypM4VAWo1sNJ"]},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "subnets": [
      {
        "id": "hW8Ma7dLMA7o4xmJf3AXBbo17bXzE7xnThUd3ypM4VAWo1sNJ",
        "controlKeys": [
          "KNjXsaA1sZsaKCD1cd85YXauDuxshTes2",
          "Aiz4eEt5xv9t4NCnAWaQJFNz5ABqLtJkR"
        ],
        "threshold": "2"
      }
    ]
  },
  "id": 1
}
```

### `platform.getTimestamp`

Get the current Platform-Chain timestamp.

**Signature:**

```
platform.getTimestamp() -> {time: string}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTimestamp",
    "params": {},
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "timestamp": "2021-09-07T00:00:00-04:00"
  },
  "id": 1
}
```

### `platform.getTotalStake`

Get the total amount of tokens staked on the requested Subnet.

**Signature:**

```
platform.getTotalStake({
    subnetID: string
}) -> {
    stake: int
    weight: int
}
```

#### Primary Network Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTotalStake",
    "params": {
      "subnetID": "11111111111111111111111111111111LpoYY"
    },
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "stake": "279825917679866811",
    "weight": "279825917679866811"
  },
  "id": 1
}
```

#### Subnet Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTotalStake",
    "params": {
        "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
    },
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "weight": "100000"
  },
  "id": 1
}
```

### `platform.getTx`

Gets a transaction by its ID.

Optional `encoding` parameter to specify the format for the returned transaction. Can be either
`hex` or `json`. Defaults to `hex`.

**Signature:**

```
platform.getTx({
    txID: string,
    encoding: string // optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTx",
    "params": {
        "txID":"28KVjSw5h3XKGuNpJXWY74EdnGq4TUWvCgEtJPymgQTvudiugb",
        "encoding": "json"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "11111111111111111111111111111111LpoYY",
        "outputs": [],
        "inputs": [
          {
            "txID": "NXNJHKeaJyjjWVSq341t6LGQP5UNz796o1crpHPByv1TKp9ZP",
            "outputIndex": 0,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 20824279595,
              "signatureIndices": [0]
            }
          },
          {
            "txID": "2ahK5SzD8iqi5KBqpKfxrnWtrEoVwQCqJsMoB9kvChCaHgAQC9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 28119890783,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "validator": {
          "nodeID": "NodeID-VT3YhgFaWEzy4Ap937qMeNEDscCammzG",
          "start": 1682945406,
          "end": 1684155006,
          "weight": 48944170378
        },
        "stake": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["P-lux1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 48944170378,
              "locktime": 0,
              "threshold": 1
            }
          }
        ],
        "rewardsOwner": {
          "addresses": ["P-lux19zfygxaf59stehzedhxjesads0p5jdvfeedal0"],
          "locktime": 0,
          "threshold": 1
        }
      },
      "credentials": [
        {
          "signatures": [
            "0x6954e90b98437646fde0c1d54c12190fc23ae5e319c4d95dda56b53b4a23e43825251289cdc3728f1f1e0d48eac20e5c8f097baa9b49ea8a3cb6a41bb272d16601"
          ]
        },
        {
          "signatures": [
            "0x6954e90b98437646fde0c1d54c12190fc23ae5e319c4d95dda56b53b4a23e43825251289cdc3728f1f1e0d48eac20e5c8f097baa9b49ea8a3cb6a41bb272d16601"
          ]
        }
      ],
      "id": "28KVjSw5h3XKGuNpJXWY74EdnGq4TUWvCgEtJPymgQTvudiugb"
    },
    "encoding": "json"
  },
  "id": 1
}
```

### `platform.getTxStatus`

Gets a transaction’s status by its ID. If the transaction was dropped, response will include a
`reason` field with more information why the transaction was dropped.

**Signature:**

```
platform.getTxStatus({
  txID: string
}) -> { status: string }
```

`status` is one of:

- `Committed`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Dropped`: The transaction will never be accepted by any node in the network, check `reason` field
  for more information
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTxStatus",
    "params": {
        "txID":"TAG9Ns1sa723mZy1GSoGqWipK6Mvpaj7CAswVJGM6MkVJDF9Q"
   },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "Committed"
  },
  "id": 1
}
```

### `platform.getUTXOs`

Gets the UTXOs that reference a given set of addresses.

**Signature:**

```
platform.getUTXOs(
    {
        addresses: []string,
        limit: int, // optional
        startIndex: { // optional
            address: string,
            utxo: string
        },
        sourceChain: string, // optional
        encoding: string, // optional
    },
) ->
{
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    encoding: string,
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (that is when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` specifies the format for the returned UTXOs. Can only be `hex` when a value is
  provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `P-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getUTXOs",
    "params" :{
        "addresses":["P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "P-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getUTXOs",
    "params" :{
        "addresses":["P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "0x62fc816bb209857923770c286192ab1f9e3f11e4a7d4ba0943111c3bbfeb9e4a5ea72fae"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the X Chain to the P Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getUTXOs",
    "params" :{
        "addresses":["P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "sourceChain": "X",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000000746a528800000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29cd704fe76"
    ],
    "endIndex": {
      "address": "P-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "S5UKgWoVpoGFyxfisebmmRf8WqC7ZwcmYwS7XaDVZqoaFcCwK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `platform.getValidatorsAt`

Get the validators and their weights of a Subnet or the Primary Network at a given Platform-Chain height.

**Signature:**

```
platform.getValidatorsAt(
    {
        height: [int|string],
        subnetID: string, // optional
    }
)
```

- `height` is the Platform-Chain height to get the validator set at, or the string literal "proposed"
  to return the validator set at this node's ProposerVM height.
- `subnetID` is the Subnet ID to get the validator set of. If not given, gets validator set of the
  Primary Network.

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getValidatorsAt",
    "params": {
        "height":1
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": {
      "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg": 2000000000000000,
      "NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu": 2000000000000000,
      "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ": 2000000000000000,
      "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN": 2000000000000000,
      "NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5": 2000000000000000
    }
  },
  "id": 1
}
```

### `platform.getAllValidatorsAt`

Get the validators and their weights of all Subnets and the Primary Network at a given Platform-Chain height.

**Signature:**

```
platform.getAllValidatorsAt(
    {
        height: [int|string],
    }
)
```

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getAllValidatorsAt",
    "params": {
        "height":1
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "validatorSets": {
            "11111111111111111111111111111111LpoYY": {
                "validators": [
                    {
                        "publicKey": "0x8048109c3da13de0700f9f3590c3270bfc42277417f6d0cc84282947e1a1f8b4980fd3e3fe223acf0f56a5838890814a",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5"
                        ]
                    },
                    {
                        "publicKey": "0xa058ff27a4c570664bfa28e34939368539a1340867951943d0f56fa8aac13bc09ff64f341acf8cc0cef74202c2d6f9c0",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ"
                        ]
                    },
                    {
                        "publicKey": "0xa10b6955a85684a0f5c94b8381f04506f1bee60625927d372323f78b3d30196cc56c8618c77eaf429298e74673d832c3",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN"
                        ]
                    },
                    {
                        "publicKey": "0xaccd61ceb90c61628aa0fa34acab27ecb08f6897e9ccad283578c278c52109f9e10e4f8bc31aa6d7905c4e1623de367e",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu"
                        ]
                    },
                    {
                        "publicKey": "0x900c9b119b5c82d781d4b49be78c3fc7ae65f2b435b7ed9e3a8b9a03e475edff86d8a64827fec8db23a6f236afbf127d",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg"
                        ]
                    }
                ],
                "totalWeight": "10000000000000000"
            }
        }
    },
    "id": 1
}
```

- `height` is the Platform-Chain height to get the validator set at, or the string literal "proposed"
  to return the validator set at this node's ProposerVM height.

**Example Call:**

### `platform.getValidatorFeeConfig`

Returns the validator fee configuration of the Platform-Chain.

**Signature:**

```
platform.getValidatorFeeConfig() -> {
  capacity: uint64,
  target: uint64,
  minPrice: uint64,
  excessConversionConstant: uint64
}
```

- `capacity` is the maximum number of L1 validators the chain is allowed to have at any given time
- `target` is the target number of L1 validators the chain should have to keep fees stable
- `minPrice` is the minimum price per L1 validator
- `excessConversionConstant` is used to convert excess L1 validators to a gas price

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getValidatorFeeConfig",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "capacity": 20000,
    "target": 10000,
    "targetPerSecond": 50000,
    "minPrice": 512,
    "excessConversionConstant": 1246488515
  },
  "id": 1
}
```

### `platform.getValidatorFeeState`

Returns the current validator fee state of the Platform-Chain.

**Signature:**

```
platform.getValidatorFeeState() -> {
  excess: uint64,
  price: uint64,
  timestamp: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getValidatorFeeState",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "excess": 26956,
    "price": 512,
    "timestamp": "2024-12-16T17:19:07Z"
  },
  "id": 1
}
```

### `platform.issueTx`

Issue a transaction to the Platform Chain.

**Signature:**

```
platform.issueTx({
    tx: string,
    encoding: string, // optional
}) -> { txID: string }
```

- `tx` is the byte representation of a transaction.
- `encoding` specifies the encoding format for the transaction bytes. Can only be `hex` when a value
  is provided.
- `txID` is the transaction’s ID.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.issueTx",
    "params": {
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txID": "G3BuH6ytQ2averrLxJJugjWZHTRubzCrUZEXoheG5JMqL5ccY"
  },
  "id": 1
}
```

### `platform.sampleValidators`

Sample validators from the specified Subnet.

**Signature:**

```
platform.sampleValidators(
    {
        size: int,
        subnetID: string, // optional
    }
) ->
{
    validators: []string
}
```

- `size` is the number of validators to sample.
- `subnetID` is the Subnet to sampled from. If omitted, defaults to the Primary Network.
- Each element of `validators` is the ID of a validator.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.sampleValidators",
    "params" :{
        "size":2
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "validators": [
      "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ",
      "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN"
    ]
  }
}
```

### `platform.validatedBy`

Get the Subnet that validates a given blockchain.

**Signature:**

```
platform.validatedBy(
    {
        blockchainID: string
    }
) -> { subnetID: string }
```

- `blockchainID` is the blockchain’s ID.
- `subnetID` is the ID of the Subnet that validates the blockchain.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.validatedBy",
    "params": {
        "blockchainID": "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r"
  },
  "id": 1
}
```

### `platform.validates`

Get the IDs of the blockchains a Subnet validates.

**Signature:**

```
platform.validates(
    {
        subnetID: string
    }
) -> { blockchainIDs: []string }
```

- `subnetID` is the Subnet’s ID.
- Each element of `blockchainIDs` is the ID of a blockchain the Subnet validates.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.validates",
    "params": {
        "subnetID":"2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "blockchainIDs": [
      "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN",
      "2TtHFqEAAJ6b33dromYMqfgavGPF3iCpdG3hwNMiart2aB5QHi"
    ]
  },
  "id": 1
}
```

# Transaction Format (/docs/rpcs/p-chain/txn-format)

---
title: Transaction Format
---

This file is meant to be the single source of truth for how we serialize
transactions in Lux's Platform Virtual Machine, aka the `Platform Chain`
or `Platform-Chain`. This document uses the [primitive serialization](/docs/rpcs/other/standards/serialization-primitives) format for packing and
[secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) for cryptographic
user identification.

## Codec ID

Some data is prepended with a codec ID (unt16) that denotes how the data should
be deserialized. Right now, the only valid codec ID is 0 (`0x00 0x00`).

## Proof of Possession

A BLS public key and a proof of possession of the key.

### What Proof of Possession Contains

- **PublicKey** is the 48 byte representation of the public key.
- **Signature** is the 96 byte signature by the private key over its public key.

### Proof of Possession Specification

```text
+------------+----------+-------------------------+
| public_key : [48]byte |                48 bytes |
+------------+----------+-------------------------+
| signature  : [96]byte |                96 bytes |
+------------+----------+-------------------------+
                        |               144 bytes |
                        +-------------------------+
```

### Proof of Possession Specification

```text
message ProofOfPossession {
    bytes public_key = 1; // 48 bytes
    bytes signature = 2;  // 96 bytes
}
```

### Proof of Possession Example

```text
    // Public Key:
    0x85, 0x02, 0x5b, 0xca, 0x6a, 0x30, 0x2d, 0xc6,
    0x13, 0x38, 0xff, 0x49, 0xc8, 0xba, 0xa5, 0x72,
    0xde, 0xd3, 0xe8, 0x6f, 0x37, 0x59, 0x30, 0x4c,
    0x7f, 0x61, 0x8a, 0x2a, 0x25, 0x93, 0xc1, 0x87,
    0xe0, 0x80, 0xa3, 0xcf, 0xde, 0xc9, 0x50, 0x40,
    0x30, 0x9a, 0xd1, 0xf1, 0x58, 0x95, 0x30, 0x67,
    // Signature:
    0x8b, 0x1d, 0x61, 0x33, 0xd1, 0x7e, 0x34, 0x83,
    0x22, 0x0a, 0xd9, 0x60, 0xb6, 0xfd, 0xe1, 0x1e,
    0x4e, 0x12, 0x14, 0xa8, 0xce, 0x21, 0xef, 0x61,
    0x62, 0x27, 0xe5, 0xd5, 0xee, 0xf0, 0x70, 0xd7,
    0x50, 0x0e, 0x6f, 0x7d, 0x44, 0x52, 0xc5, 0xa7,
    0x60, 0x62, 0x0c, 0xc0, 0x67, 0x95, 0xcb, 0xe2,
    0x18, 0xe0, 0x72, 0xeb, 0xa7, 0x6d, 0x94, 0x78,
    0x8d, 0x9d, 0x01, 0x17, 0x6c, 0xe4, 0xec, 0xad,
    0xfb, 0x96, 0xb4, 0x7f, 0x94, 0x22, 0x81, 0x89,
    0x4d, 0xdf, 0xad, 0xd1, 0xc1, 0x74, 0x3f, 0x7f,
    0x54, 0x9f, 0x1d, 0x07, 0xd5, 0x9d, 0x55, 0x65,
    0x59, 0x27, 0xf7, 0x2b, 0xc6, 0xbf, 0x7c, 0x12
```

## Transferable Output

Transferable outputs wrap an output with an asset ID.

### What Transferable Output Contains

A transferable output contains an `AssetID` and an `Output`.

- **`AssetID`** is a 32-byte array that defines which asset this output
  references. The only valid `AssetID` is the LUX `AssetID`.
- **`Output`** is an output, as defined below. For example, this can be a SECP256K1 transfer output.

### Gantt Transferable Output Specification

```text
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| output   : Output   |      size(output) bytes |
+----------+----------+-------------------------+
                      | 32 + size(output) bytes |
                      +-------------------------+
```

### Proto Transferable Output Specification

```text
message TransferableOutput {
    bytes asset_id = 1; // 32 bytes
    Output output = 2;  // size(output)
}
```

### Transferable Output Example

Let's make a transferable output:

- `AssetID: 0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a`
- `Output: "Example SECP256K1 Transfer Output from below"`

```text
[
    AssetID <- 0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a,
    Output  <- 0x0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c,
]
=
[
    // assetID:
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
]
```

## Transferable Input

Transferable inputs describe a specific UTXO with a provided transfer input.

### What Transferable Input Contains

A transferable input contains a `TxID`, `UTXOIndex` `AssetID` and an `Input`.

- **`TxID`** is a 32-byte array that defines which transaction this input is consuming an output from.
- **`UTXOIndex`** is an int that defines which utxo this input is consuming the specified transaction.
- **`AssetID`** is a 32-byte array that defines which asset this input
  references. The only valid `AssetID` is the LUX `AssetID`.
- **`Input`** is a transferable input object.

### Gantt Transferable Input Specification

```text
+------------+----------+------------------------+
| tx_id      : [32]byte |               32 bytes |
+------------+----------+------------------------+
| utxo_index : int      |               04 bytes |
+------------+----------+------------------------+
| asset_id   : [32]byte |               32 bytes |
+------------+----------+------------------------+
| input      : Input    |      size(input) bytes |
+------------+----------+------------------------+
                        | 68 + size(input) bytes |
                        +------------------------+
```

### Proto Transferable Input Specification

```text
message TransferableInput {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
    bytes asset_id = 3;    // 32 bytes
    Input input = 4;       // size(input)
}
```

### Transferable Input Example

Let's make a transferable input:

- **`TxID`**: `0x0dfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15`
- **`UTXOIndex`**: `0`
- **`AssetID`**: `0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a`
- **`Input`**: `"Example SECP256K1 Transfer Input from below"`

```text
[
    TxID      <- 0x0dfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15
    UTXOIndex <- 0x00000001
    AssetID   <- 0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a
    Input     <- 0x0000000500000000ee6b28000000000100000000
]
=
[
    // txID:
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00
]
```

## Outputs

Outputs have two possible type: `SECP256K1TransferOutput`, `SECP256K1OutputOwners`.

## SECP256K1 Transfer Output

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) transfer output
allows for sending a quantity of an asset to a collection of addresses after a
specified Unix time. The only valid asset is LUX.

### What SECP256K1 Transfer Output Contains

A secp256k1 transfer output contains a `TypeID`, `Amount`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000007`.
- **`Amount`** is a long that specifies the quantity of the asset that this output owns. Must be positive.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Transfer Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| amount    : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 28 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Transfer Output Specification

```text
message SECP256K1TransferOutput {
    uint32 type_id = 1;           // 04 bytes
    uint64 amount = 2;            // 08 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Transfer Output Example

Let's make a secp256k1 transfer output with:

- **`TypeID`**: 7
- **`Amount`**: 3999000000
- **`Locktime`**: 0
- **`Threshold`**: 1
- **`Addresses`**:
  - 0xda2bee01be82ecc00c34f361eda8eb30fb5a715c

```text
[
    TypeID    <- 0x00000007
    Amount    <- 0x00000000ee5be5c0
    Locktime  <- 0x0000000000000000
    Threshold <- 0x00000001
    Addresses <- [
        0xda2bee01be82ecc00c34f361eda8eb30fb5a715c,
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x07,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0xee, 0x5b, 0xe5, 0xc0,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xda, 0x2b, 0xee, 0x01, 0xbe, 0x82, 0xec, 0xc0,
    0x0c, 0x34, 0xf3, 0x61, 0xed, 0xa8, 0xeb, 0x30,
    0xfb, 0x5a, 0x71, 0x5c,
]
```

## SECP256K1 Output Owners Output

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) output owners
output will receive the staking rewards when the lock up period ends.

### What SECP256K1 Output Owners Output Contains

A secp256k1 output owners output contains a `TypeID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x0000000b`.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Output Owners Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 20 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Output Owners Output Specification

```text
message SECP256K1OutputOwnersOutput {
    uint32 type_id = 1;           // 04 bytes
    uint64 locktime = 2;          // 08 bytes
    uint32 threshold = 3;         // 04 bytes
    repeated bytes addresses = 4; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Output Owners Output Example

Let's make a secp256k1 output owners output with:

- **`TypeID`**: 11
- **`Locktime`**: 0
- **`Threshold`**: 1
- **`Addresses`**:
  - 0xda2bee01be82ecc00c34f361eda8eb30fb5a715c

```text
[
    TypeID    <- 0x0000000b
    Locktime  <- 0x0000000000000000
    Threshold <- 0x00000001
    Addresses <- [
        0xda2bee01be82ecc00c34f361eda8eb30fb5a715c,
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x0b,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xda, 0x2b, 0xee, 0x01, 0xbe, 0x82, 0xec, 0xc0,
    0x0c, 0x34, 0xf3, 0x61, 0xed, 0xa8, 0xeb, 0x30,
    0xfb, 0x5a, 0x71, 0x5c,
]
```

## Inputs

Inputs have one possible type: `SECP256K1TransferInput`.

## SECP256K1 Transfer Input

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) transfer input
allows for spending an unspent secp256k1 transfer output.

### What SECP256K1 Transfer Input Contains

A secp256k1 transfer input contains an `Amount` and `AddressIndices`.

- **`TypeID`** is the ID for this output type. It is `0x00000005`.
- **`Amount`** is a long that specifies the quantity that this input should be
  consuming from the UTXO. Must be positive. Must be equal to the amount
  specified in the UTXO.
- **`AddressIndices`** is a list of unique ints that define the private keys are
  being used to spend the UTXO. Each UTXO has an array of addresses that can
  spend the UTXO. Each int represents the index in this address array that will
  sign this transaction. The array must be sorted low to high.

### Gantt SECP256K1 Transfer Input Specification

```text
+-------------------------+-------------------------------------+
| type_id         : int   |                             4 bytes |
+-----------------+-------+-------------------------------------+
| amount          : long  |                             8 bytes |
+-----------------+-------+-------------------------------------+
| address_indices : []int |  4 + 4 * len(address_indices) bytes |
+-----------------+-------+-------------------------------------+
                          | 16 + 4 * len(address_indices) bytes |
                          +-------------------------------------+
```

**Proto SECP256K1 Transfer Input Specification**

```text
message SECP256K1TransferInput {
    uint32 type_id = 1;                  // 04 bytes
    uint64 amount = 2;                   // 08 bytes
    repeated uint32 address_indices = 3; // 04 bytes + 4 bytes * len(address_indices)
}
```

### SECP256K1 Transfer Input Example

Let's make a payment input with:

- **`TypeID`**: 5
- **`Amount`**: 4000000000
- **`AddressIndices`**: \[0\]

```text
[
    TypeID         <- 0x00000005
    Amount         <- 0x00000000ee6b2800,
    AddressIndices <- [0x00000000]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x05,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0xee, 0x6b, 0x28, 0x00,
    // length:
    0x00, 0x00, 0x00, 0x01,
    // address_indices[0]
    0x00, 0x00, 0x00, 0x00
]
```

## Unsigned Transactions

Unsigned transactions contain the full content of a transaction with only the
signatures missing. Unsigned transactions have six possible types:
`AddValidatorTx`, `AddSubnetValidatorTx`, `AddDelegatorTx`, `CreateSubnetTx`,
`ImportTx`, and `ExportTx`. They embed `BaseTx`, which contains common fields
and operations.

## Unsigned BaseTx

### What Base TX Contains

A base TX contains a `TypeID`, `NetworkID`, `BlockchainID`, `Outputs`, `Inputs`, and `Memo`.

- **`TypeID`** is the ID for this type. It is `0x00000000`.
- **`NetworkID`** is an int that defines which network this transaction is meant
  to be issued to. This value is meant to support transaction routing and is not
  designed for replay attack prevention.
- **`BlockchainID`** is a 32-byte array that defines which blockchain this
  transaction was issued to. This is used for replay attack prevention for
  transactions that could potentially be valid across network or blockchain.
- **`Outputs`** is an array of transferable output objects. Outputs must be
  sorted lexicographically by their serialized representation. The total
  quantity of the assets created in these outputs must be less than or equal to
  the total quantity of each asset consumed in the inputs minus the transaction
  fee.
- **`Inputs`** is an array of transferable input objects. Inputs must be sorted
  and unique. Inputs are sorted first lexicographically by their **`TxID`** and
  then by the **`UTXOIndex`** from low to high. If there are inputs that have
  the same **`TxID`** and **`UTXOIndex`**, then the transaction is invalid as
  this would result in a double spend.
- **`Memo`** Memo field contains arbitrary bytes, up to 256 bytes.

### Gantt Base TX Specification

```text
+---------------+----------------------+-----------------------------------------+
| type_id       : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| network_id    : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| blockchain_id : [32]byte             |                                32 bytes |
+---------------+----------------------+-----------------------------------------+
| outputs       : []TransferableOutput |                 4 + size(outputs) bytes |
+---------------+----------------------+-----------------------------------------+
| inputs        : []TransferableInput  |                  4 + size(inputs) bytes |
+---------------+----------------------+-----------------------------------------+
| memo          : [256]byte            |                    4 + size(memo) bytes |
+---------------+----------------------+-----------------------------------------+
                          | 52 + size(outputs) + size(inputs) + size(memo) bytes |
                          +------------------------------------------------------+
```

### Proto Base TX Specification

```text
message BaseTx {
    uint32 type_id = 1;          // 04 bytes
    uint32 network_id = 2;       // 04 bytes
    bytes blockchain_id = 3;     // 32 bytes
    repeated Output outputs = 4; // 04 bytes + size(outs)
    repeated Input inputs = 5;   // 04 bytes + size(ins)
    bytes memo = 6;              // 04 bytes + size(memo)
}
```

### Base TX Example

Let's make a base TX that uses the inputs and outputs from the previous examples:

- **`TypeID`**: `0`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x000000000000000000000000000000000000000000000000000000000000000`
- **`Outputs`**:
  - `"Example Transferable Output as defined above"`
- **`Inputs`**:
  - `"Example Transferable Input as defined above"`

```text
[
    TypeID       <- 0x00000000
    NetworkID    <- 0x00003039
    BlockchainID <- 0x000000000000000000000000000000000000000000000000000000000000000
    Outputs      <- [
        0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c
    ]
    Inputs       <- [
        0xdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x00,
    // networkID:
    0x00, 0x00, 0x30, 0x39,
    // blockchainID:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // number of outputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable output:
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    // number of inputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable input:
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    // Memo length:
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Validator TX

### What Unsigned Add Validator TX Contains

An unsigned add validator TX contains a `BaseTx`, `Validator`, `Stake`,
`RewardsOwner`, and `Shares`. The `TypeID` for this type is `0x0000000c`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is 20 bytes which is the node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`Stake`** Stake has `LockedOuts`
  - **`LockedOuts`** An array of Transferable Outputs that are locked for the
    duration of the staking period. At the end of the staking period, these
    outputs are refunded to their respective addresses.
- **`RewardsOwner`** A `SECP256K1OutputOwners`
- **`Shares`** 10,000 times percentage of reward taken from delegators

### Gantt Unsigned Add Validator TX Specification

```text
+---------------+-----------------------+-----------------------------------------+
| base_tx       : BaseTx                |                     size(base_tx) bytes |
+---------------+-----------------------+-----------------------------------------+
| validator     : Validator             |                                44 bytes |
+---------------+-----------------------+-----------------------------------------+
| stake         : Stake                 |                  size(LockedOuts) bytes |
+---------------+-----------------------+-----------------------------------------+
| rewards_owner : SECP256K1OutputOwners |               size(rewards_owner) bytes |
+---------------+-----------------------+-----------------------------------------+
| shares        : Shares                |                                 4 bytes |
+---------------+-----------------------+-----------------------------------------+
                  | 48 + size(stake) + size(rewards_owner) + size(base_tx) bytes |
                  +--------------------------------------------------------------+
```

### Proto Unsigned Add Validator TX Specification

```text
message AddValidatorTx {
    BaseTx base_tx = 1;                      // size(base_tx)
    Validator validator = 2;                 // 44 bytes
    Stake stake = 3;                         // size(LockedOuts)
    SECP256K1OutputOwners rewards_owner = 4; // size(rewards_owner)
    uint32 shares = 5;                       // 04 bytes
}
```

### Unsigned Add Validator TX Example

Let's make an unsigned add validator TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0c"`
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is 20 bytes which is the node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`Stake`**: `0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c`
- **`RewardsOwner`**: `0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c`
- **`Shares`**: `0x00000064`

```text
[
    BaseTx       <- 0x0000000c000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    NodeID       <- 0xe9094f73698002fd52c90819b457b9fbc866ab80
    StarTime     <- 0x000000005f21f31d
    EndTime      <- 0x000000005f497dc6
    Weight       <- 0x000000000000d431
    Stake        <- 0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c
    RewardsOwner <- 0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c
    Shares       <- 0x00000064
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x0c, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x68, 0x70, 0xb7, 0xd6,
    0x6a, 0xc3, 0x25, 0x40, 0x31, 0x13, 0x79, 0xe5,
    0xb5, 0xdb, 0xad, 0x28, 0xec, 0x7e, 0xb8, 0xdd,
    0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    0x00, 0x00, 0x00, 0x01,
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Node ID
    0xe9, 0x09, 0x4f, 0x73, 0x69, 0x80, 0x02, 0xfd,
    0x52, 0xc9, 0x08, 0x19, 0xb4, 0x57, 0xb9, 0xfb,
    0xc8, 0x66, 0xab, 0x80,
    // StartTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x21, 0xf3, 0x1d,
    // EndTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x49, 0x7d, 0xc6,
    // Weight
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // Stake
    0x00, 0x00, 0x00, 0x01, 0x39, 0xc3, 0x3a, 0x49,
    0x9c, 0xe4, 0xc3, 0x3a, 0x3b, 0x09, 0xcd, 0xd2,
    0xcf, 0xa0, 0x1a, 0xe7, 0x0d, 0xbf, 0x2d, 0x18,
    0xb2, 0xd7, 0xd1, 0x68, 0x52, 0x44, 0x40, 0xe5,
    0x5d, 0x55, 0x00, 0x88, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
    0x3c, 0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a,
    0x0e, 0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68,
    0x61, 0xe1, 0xb2, 0x9c,
    // RewardsOwner
    0x00, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    // Shares
    0x00, 0x00, 0x00, 0x64,
]
```

## Unsigned Remove Lux L1 Validator TX

### What Unsigned Remove Lux L1 Validator TX Contains

An unsigned remove Lux L1 validator TX contains a `BaseTx`, `NodeID`,
`SubnetID`, and `SubnetAuth`. The `TypeID` for this type is 23 or `0x00000017`.

- **`BaseTx`**
- **`NodeID`** is the 20 byte node ID of the validator.
- **`SubnetID`** is the 32 byte Lux L1 ID (SubnetID) that the validator is being removed from.
- **`SubnetAuth`** contains `SigIndices` and has a type id of `0x0000000a`.
  `SigIndices` is a list of unique ints that define the addresses signing the
  control signature which proves that the issuer has the right to remove the
  node from the Lux L1. The array must be sorted low to high.

### Gantt Unsigned Remove Lux L1 Validator TX Specification

```text
+---------------+----------------------+------------------------------------------------+
| base_tx       : BaseTx               |                            size(base_tx) bytes |
+---------------+----------------------+------------------------------------------------+
| node_id       : [20]byte             |                                       20 bytes |
+---------------+----------------------+------------------------------------------------+
| subnet_id     : [32]byte             |                                       32 bytes |
+---------------+----------------------+------------------------------------------------+
| sig_indices   : SubnetAuth           |               4 bytes + len(sig_indices) bytes |
+---------------+----------------------+------------------------------------------------+
| 56 + len(sig_indices) + size(base_tx) bytes                                           |
+---------------------------------------------------------------------------------------+
```

### Proto Unsigned Remove Lux L1 Validator TX Specification

```text
message RemoveSubnetValidatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    string node_id = 2;         // 20 bytes
    SubnetID subnet_id = 3;     // 32 bytes
    SubnetAuth subnet_auth = 4; // 04 bytes + len(sig_indices)
}
```

### Unsigned Remove Lux L1 Validator TX Example

Let's make an unsigned remove Lux L1 validator TX that uses the inputs and
outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 17"`
- **`NodeID`**: `0xe902a9a86640bfdb1cd0e36c0cc982b83e5765fa`
- **`SubnetID`**: `0x4a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db`
- **`SubnetAuth`**: `0x0000000a0000000100000000`

```text
[
    BaseTx       <- 0x0000000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000000000000000000000
    NodeID       <- 0xe902a9a86640bfdb1cd0e36c0cc982b83e5765fa
    SubnetID     <- 0x4a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db
    SubnetAuth   <- 0x0000000a0000000100000000
]
=
[
    // BaseTx
    0x00, 0x00, 0x00, 0x17, 0x00, 0x00, 0x30, 0x39,
    0x3d, 0x0a, 0xd1, 0x2b, 0x8e, 0xe8, 0x92, 0x8e,
    0xdf, 0x24, 0x8c, 0xa9, 0x1c, 0xa5, 0x56, 0x00,
    0xfb, 0x38, 0x3f, 0x07, 0xc3, 0x2b, 0xff, 0x1d,
    0x6d, 0xec, 0x47, 0x2b, 0x25, 0xcf, 0x59, 0xa7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // NodeID
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa,
    // SubnetID
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    // SubnetAuth
    // SubnetAuth TypeID
    0x00, 0x00, 0x00, 0x0a,
    // SigIndices length
    0x00, 0x00, 0x00, 0x01,
    // SigIndices
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Permissionless Validator TX

### What Unsigned Add Permissionless Validator TX Contains

An unsigned add permissionless validator TX contains a `BaseTx`, `Validator`,
`SubnetID`, `Signer`, `StakeOuts`, `ValidatorRewardsOwner`,
`DelegatorRewardsOwner`, and `DelegationShares`. The `TypeID` for this type is
25 or `0x00000019`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is the 20 byte node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`SubnetID`** is the 32 byte Lux L1 ID (SubnetID) of the Lux L1 this validator will validate.
- **`Signer`** If the [SubnetID] is the primary network, [Signer] is the type ID
  28 (`0x1C`) followed by a [Proof of Possession](#proof-of-possession). If the
  [SubnetID] is not the primary network, this value is the empty signer, whose
  byte representation is only the type ID 27 (`0x1B`).
- **`StakeOuts`** An array of Transferable Outputs. Where to send staked tokens when done validating.
- **`ValidatorRewardsOwner`** Where to send validation rewards when done validating.
- **`DelegatorRewardsOwner`** Where to send delegation rewards when done validating.
- **`DelegationShares`** a short which is the fee this validator charges
  delegators as a percentage, times 10,000 For example, if this validator has
  DelegationShares=300,000 then they take 30% of rewards from delegators.

### Gantt Unsigned Add Permissionless Validator TX Specification

```text
+---------------+----------------------+------------------------------------------------+
| base_tx       : BaseTx               |                            size(base_tx) bytes |
+---------------+----------------------+------------------------------------------------+
| validator     : Validator            |                                       44 bytes |
+---------------+----------------------+------------------------------------------------+
| subnet_id     : [32]byte             |                                       32 bytes |
+---------------+----------------------+------------------------------------------------+
| signer        : Signer               |                                      144 bytes |
+---------------+----------------------+------------------------------------------------+
| stake_outs    : []TransferOut        |                     4 + size(stake_outs) bytes |
+---------------+----------------------+------------------------------------------------+
| validator_rewards_owner : SECP256K1OutputOwners | size(validator_rewards_owner) bytes |
+---------------+----------------------+------------------------------------------------+
| delegator_rewards_owner : SECP256K1OutputOwners | size(delegator_rewards_owner) bytes |
+---------------+----------------------+------------------------------------------------+
| delegation_shares   : uint32         |                                        4 bytes |
+---------------+----------------------+------------------------------------------------+
| 232 + size(base_tx) + size(stake_outs) +                                              |
| size(validator_rewards_owner) + size(delegator_rewards_owner) bytes                   |
+---------------------------------------------------------------------------------------+
```

### Proto Unsigned Add Permissionless Validator TX Specification

```text
message AddPermissionlessValidatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    Validator validator = 2;    // 44 bytes
    SubnetID subnet_id = 3;     // 32 bytes
    Signer signer = 4; // 148 bytes
    repeated TransferOut stake_outs = 5; // 4 bytes + size(stake_outs)
    SECP256K1OutputOwners validator_rewards_owner = 6; // size(validator_rewards_owner) bytes
    SECP256K1OutputOwners delegator_rewards_owner = 7; // size(delegator_rewards_owner) bytes
    uint32 delegation_shares = 8; // 4 bytes
}
```

### Unsigned Add Permissionless Validator TX Example

Let's make an unsigned add permissionless validator TX that uses the inputs and
outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 1a"`
- **`Validator`**: `0x5fa29ed4356903dac2364713c60f57d8472c7dda000000006397616e0000000063beee6e000001d1a94a2000`
- **`SubnetID`**: `0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada`
- **`Signer`**: `0x0000001ca5af179e4188583893c2b99e1a8be27d90a9213cfbff1d75b74fe2bc9f3b072c2ded0863a9d9acd9033f223295810e429238e28d3c9b7f7212b63d746b2ae73a54fe08a3de61b132f2f89e9eeff97d4d7ca3a3c88986aa855cd36296fcfe8f02162d0258be494d267d4c5798bc081ab602ded90b0fc16d8a035e68ff5294794cb63ff1ee068fbfc2b4c8cd2d08ebf297`
- **`StakeOuts`**: `0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0`
- **`ValidatorRewardsOwner`**: `0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52`
- **`DelegatorRewardsOwner`**: `0x0000000b00000000000000000000000100000001b2b91313ac487c222445254e26cd026d21f6f440`
- **`DelegationShares`**: `0x00004e20`

```text
[
    BaseTx       <- 0x0000001a00003039e902a9a86640bfdb1cd0e36c0cc982b83e5765fad5f6bbe6abdcce7b5ae7d7c700000000000000014a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db000000003d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000005000001d1a94a2000000000010000000000000000
    Validator    <- 0x5fa29ed4356903dac2364713c60f57d8472c7dda000000006397616e0000000063beee6e000001d1a94a2000
    SubnetID     <- 0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada
    Signer       <- 0x0000001ca5af179e4188583893c2b99e1a8be27d90a9213cfbff1d75b74fe2bc9f3b072c2ded0863a9d9acd9033f223295810e429238e28d3c9b7f7212b63d746b2ae73a54fe08a3de61b132f2f89e9eeff97d4d7ca3a3c88986aa855cd36296fcfe8f02162d0258be494d267d4c5798bc081ab602ded90b0fc16d8a035e68ff5294794cb63ff1ee068fbfc2b4c8cd2d08ebf297
    StakeOuts    <- 0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0
    ValidatorRewardsOwner  <- 0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52
    DelegatorRewardsOwner  <- 0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52
    DelegationShares       <- 0x00004e20
]
=
[
    // BaseTx
    0x00, 0x00, 0x00, 0x1a, 0x00, 0x00, 0x30, 0x39,
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa, 0xd5, 0xf6, 0xbb, 0xe6,
    0xab, 0xdc, 0xce, 0x7b, 0x5a, 0xe7, 0xd7, 0xc7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    0x00, 0x00, 0x00, 0x00, 0x3d, 0x0a, 0xd1, 0x2b,
    0x8e, 0xe8, 0x92, 0x8e, 0xdf, 0x24, 0x8c, 0xa9,
    0x1c, 0xa5, 0x56, 0x00, 0xfb, 0x38, 0x3f, 0x07,
    0xc3, 0x2b, 0xff, 0x1d, 0x6d, 0xec, 0x47, 0x2b,
    0x25, 0xcf, 0x59, 0xa7, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Validator
    // NodeID
    0x5f, 0xa2, 0x9e, 0xd4, 0x35, 0x69, 0x03, 0xda,
    0xc2, 0x36, 0x47, 0x13, 0xc6, 0x0f, 0x57, 0xd8,
    0x47, 0x2c, 0x7d, 0xda, 0x
    // Start time
    0x00, 0x00, 0x00, 0x00, 0x63, 0x97, 0x61, 0x6e,
    // End time
    0x00, 0x00, 0x00, 0x00, 0x63, 0xbe, 0xee, 0x6e,
    // Weight
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // SubnetID
    0xf3, 0x08, 0x6d, 0x7b, 0xfc, 0x35, 0xbe, 0x1c,
    0x68, 0xdb, 0x66, 0x4b, 0xa9, 0xce, 0x61, 0xa2,
    0x06, 0x01, 0x26, 0xb0, 0xd6, 0xb4, 0xbf, 0xb0,
    0x9f, 0xd7, 0xa5, 0xfb, 0x76, 0x78, 0xca, 0xda,
    // Signer
    // TypeID
    0x00, 0x00, 0x00, 0x1c,
    // Pub key
    0xa5, 0xaf, 0x17, 0x9e, 0x41, 0x88, 0x58, 0x38,
    0x93, 0xc2, 0xb9, 0x9e, 0x1a, 0x8b, 0xe2, 0x7d,
    0x90, 0xa9, 0x21, 0x3c, 0xfb, 0xff, 0x1d, 0x75,
    0xb7, 0x4f, 0xe2, 0xbc, 0x9f, 0x3b, 0x07, 0x2c,
    0x2d, 0xed, 0x08, 0x63, 0xa9, 0xd9, 0xac, 0xd9,
    0x03, 0x3f, 0x22, 0x32, 0x95, 0x81, 0x0e, 0x42,
    // Sig
    0x92, 0x38, 0xe2, 0x8d, 0x3c, 0x9b, 0x7f, 0x72,
    0x12, 0xb6, 0x3d, 0x74, 0x6b, 0x2a, 0xe7, 0x3a,
    0x54, 0xfe, 0x08, 0xa3, 0xde, 0x61, 0xb1, 0x32,
    0xf2, 0xf8, 0x9e, 0x9e, 0xef, 0xf9, 0x7d, 0x4d,
    0x7c, 0xa3, 0xa3, 0xc8, 0x89, 0x86, 0xaa, 0x85,
    0x5c, 0xd3, 0x62, 0x96, 0xfc, 0xfe, 0x8f, 0x02,
    0x16, 0x2d, 0x02, 0x58, 0xbe, 0x49, 0x4d, 0x26,
    0x7d, 0x4c, 0x57, 0x98, 0xbc, 0x08, 0x1a, 0xb6,
    0x02, 0xde, 0xd9, 0x0b, 0x0f, 0xc1, 0x6d, 0x8a,
    0x03, 0x5e, 0x68, 0xff, 0x52, 0x94, 0x79, 0x4c,
    0xb6, 0x3f, 0xf1, 0xee, 0x06, 0x8f, 0xbf, 0xc2,
    0xb4, 0xc8, 0xcd, 0x2d, 0x08, 0xeb, 0xf2, 0x97,
    // Stake outs
    // Num stake outs
    0x00, 0x00, 0x00, 0x01,
    // AssetID
    0x3d, 0x0a, 0xd1, 0x2b, 0x8e, 0xe8, 0x92, 0x8e,
    0xdf, 0x24, 0x8c, 0xa9, 0x1c, 0xa5, 0x56, 0x00,
    0xfb, 0x38, 0x3f, 0x07, 0xc3, 0x2b, 0xff, 0x1d,
    0x6d, 0xec, 0x47, 0x2b, 0x25, 0xcf, 0x59, 0xa7,
    // Output
    // typeID
    0x00, 0x00, 0x00, 0x07,
    // Amount
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x33, 0xee, 0xff, 0xc6, 0x47, 0x85, 0xcf, 0x9d,
    0x80, 0xe7, 0x73, 0x1d, 0x9f, 0x31, 0xf6, 0x7b,
    0xd0, 0x3c, 0x5c, 0xf0,
    // Validator rewards owner
    // TypeID
    0x00, 0x00, 0x00, 0x0b,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x72, 0xf3, 0xeb, 0x9a, 0xea, 0xf8, 0x28, 0x30,
    0x11, 0xce, 0x6e, 0x43, 0x7f, 0xde, 0xcd, 0x65,
    0xea, 0xce, 0x8f, 0x52,
    // Delegator rewards owner
    // TypeID
    0x00, 0x00, 0x00, 0x0b,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0xb2, 0xb9, 0x13, 0x13, 0xac, 0x48, 0x7c, 0x22,
    0x24, 0x45, 0x25, 0x4e, 0x26, 0xcd, 0x02, 0x6d,
    0x21, 0xf6, 0xf4, 0x40,
    // Delegation shares
    0x00, 0x00, 0x4e, 0x20,
]
```

## Unsigned Add Permissionless Delegator TX

### What Unsigned Add Permissionless Delegator TX Contains

An unsigned add permissionless delegator TX contains a `BaseTx`, `Validator`,
`SubnetID`, `StakeOuts`, and `DelegatorRewardsOwner`. The `TypeID` for this type
is 26 or `0x0000001a`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is the 20 byte node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`SubnetID`** is the 32 byte Lux L1 ID (SubnetID) of the Lux L1 this delegation is on.
- **`StakeOuts`** An array of Transferable Outputs. Where to send staked tokens when done validating.
- **`DelegatorRewardsOwner`** Where to send staking rewards when done validating.

### Gantt Unsigned Add Permissionless Delegator TX Specification

```text
+---------------+----------------------+------------------------------------------------+
| base_tx       : BaseTx               |                            size(base_tx) bytes |
+---------------+----------------------+------------------------------------------------+
| validator     : Validator            |                                       44 bytes |
+---------------+----------------------+------------------------------------------------+
| subnet_id     : [32]byte             |                                       32 bytes |
+---------------+----------------------+------------------------------------------------+
| stake_outs    : []TransferOut        |                     4 + size(stake_outs) bytes |
+---------------+----------------------+------------------------------------------------+
| delegator_rewards_owner : SECP256K1OutputOwners | size(delegator_rewards_owner) bytes |
+---------------+----------------------+------------------------------------------------+
| 80 + size(base_tx) + size(stake_outs) + size(delegator_rewards_owner) bytes           |
+---------------------------------------------------------------------------------------+
```

### Proto Unsigned Add Permissionless Delegator TX Specification

```text
message AddPermissionlessDelegatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    Validator validator = 2;    // size(validator)
    SubnetID subnet_id = 3;     // 32 bytes
    repeated TransferOut stake_outs = 4; // 4 bytes + size(stake_outs)
    SECP256K1OutputOwners delegator_rewards_owner = 5; // size(delegator_rewards_owner) bytes
}
```

### Unsigned Add Permissionless Delegator TX Example

Let's make an unsigned add permissionless delegator TX that uses the inputs and
outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 1a"`
- **`Validator`**: `0x5fa29ed4356903dac2364713c60f57d8472c7dda00000000639761970000000063beee97000001d1a94a2000`
- **`SubnetID`**: `0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada`
- **`StakeOuts`**: `0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0`
- **`DelegatorRewardsOwner`**: `0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52`

```text
[
    BaseTx       <- 0x0000001a00003039e902a9a86640bfdb1cd0e36c0cc982b83e5765fad5f6bbe6abdcce7b5ae7d7c700000000000000014a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db000000003d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000005000001d1a94a2000000000010000000000000000
    Validator    <- 0x5fa29ed4356903dac2364713c60f57d8472c7dda00000000639761970000000063beee97000001d1a94a2000
    SubnetID     <- 0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada
    StakeOuts    <- 0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0
    DelegatorRewardsOwner <- 0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52
]
=
[
    // BaseTx
    0x00, 0x00, 0x00, 0x1a, 0x00, 0x00, 0x30, 0x39,
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa, 0xd5, 0xf6, 0xbb, 0xe6,
    0xab, 0xdc, 0xce, 0x7b, 0x5a, 0xe7, 0xd7, 0xc7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    0x00, 0x00, 0x00, 0x00, 0x3d, 0x0a, 0xd1, 0x2b,
    0x8e, 0xe8, 0x92, 0x8e, 0xdf, 0x24, 0x8c, 0xa9,
    0x1c, 0xa5, 0x56, 0x00, 0xfb, 0x38, 0x3f, 0x07,
    0xc3, 0x2b, 0xff, 0x1d, 0x6d, 0xec, 0x47, 0x2b,
    0x25, 0xcf, 0x59, 0xa7, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Validator
    // NodeID
    0x5f, 0xa2, 0x9e, 0xd4, 0x35, 0x69, 0x03, 0xda,
    0xc2, 0x36, 0x47, 0x13, 0xc6, 0x0f, 0x57, 0xd8,
    0x47, 0x2c, 0x7d, 0xda,
    // Start time
    0x00, 0x00, 0x00, 0x00, 0x63, 0x97, 0x61, 0x97,
    // End time
    0x00, 0x00, 0x00, 0x00, 0x63, 0xbe, 0xee, 0x97,
    // Weight
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // Stake_outs
    // Num stake outs
    0x00, 0x00, 0x00, 0x01,
    // Stake out 0
    // AssetID
    0x3d, 0x0a, 0xd1, 0x2b, 0x8e, 0xe8, 0x92, 0x8e,
    0xdf, 0x24, 0x8c, 0xa9, 0x1c, 0xa5, 0x56, 0x00,
    0xfb, 0x38, 0x3f, 0x07, 0xc3, 0x2b, 0xff, 0x1d,
    0x6d, 0xec, 0x47, 0x2b, 0x25, 0xcf, 0x59, 0xa7,
    // TypeID
    0x00, 0x00, 0x00, 0x07,
    // Amount
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x33, 0xee, 0xff, 0xc6, 0x47, 0x85, 0xcf, 0x9d,
    0x80, 0xe7, 0x73, 0x1d, 0x9f, 0x31, 0xf6, 0x7b,
    0xd0, 0x3c, 0x5c, 0xf0,
    // Delegator_rewards_owner
    // TypeID
    0x00, 0x00, 0x00, 0x0b,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x72, 0xf3, 0xeb, 0x9a, 0xea, 0xf8, 0x28, 0x30,
    0x11, 0xce, 0x6e, 0x43, 0x7f, 0xde, 0xcd, 0x65,
    0xea, 0xce, 0x8f, 0x52,
]
```

## Unsigned Transform Lux L1 TX

> **Note:** This transaction type has been disabled post-activation of LP-77 (Etna upgrade). The `TransformSubnetTx` is no longer accepted on the Platform-Chain after the activation of this upgrade.

Transforms a permissioned Lux L1 into a permissionless Lux L1. Must be signed by the Lux L1 owner.

### What Unsigned Transform Lux L1 TX Contains

An unsigned transform Lux L1 TX contains a `BaseTx`, `SubnetID`, `AssetID`,
`InitialSupply`, `MaximumSupply`, `MinConsumptionRate`, `MaxConsumptionRate`,
`MinValidatorStake`, `MaxValidatorStake`, `MinStakeDuration`,
`MaxStakeDuration`, `MinDelegationFee`, `MinDelegatorStake`,
`MaxValidatorWeightFactor`, `UptimeRequirement`, and `SubnetAuth`. The `TypeID`
for this type is 24 or `0x00000018`.

- **`BaseTx`**
- **`SubnetID`** a 32-byte Lux L1 ID of the Lux L1 to transform.
- **`AssetID`** is a 32-byte array that defines which asset to use when staking on the Lux L1.
  - Restrictions
    - Must not be the Empty ID
    - Must not be the LUX ID
- **`InitialSupply`** is a long which is the amount to initially specify as the current supply.
  - Restrictions
    - Must be > 0
- **`MaximumSupply`** is a long which is the amount to specify as the maximum token supply.
  - Restrictions
    - Must be >= [InitialSupply]
- **`MinConsumptionRate`** is a long which is the rate to allocate funds if the
  validator's stake duration is 0.
- **`MaxConsumptionRate`** is a long which is the rate to allocate funds if the
  validator's stake duration is equal to the minting period.
  - Restrictions
    - Must be `>=` [MinConsumptionRate]
    - Must be `<=` [`reward.PercentDenominator`]
- **`MinValidatorStake`** is a long which the minimum amount of funds required to become a validator.
  - Restrictions
    - Must be `>` 0
    - Must be `<=` [InitialSupply]
- **`MaxValidatorStake`** is a long which is the maximum amount of funds a
  single validator can be allocated, including delegated funds.
  - Restrictions:
    - Must be `>=` [MinValidatorStake]
    - Must be `<=` [MaximumSupply]
- **`MinStakeDuration`** is a short which is the minimum number of seconds a staker can stake for.
  - Restrictions
    - Must be `>` 0
- **`MaxStakeDuration`** is a short which is the maximum number of seconds a staker can stake for.
  - Restrictions
    - Must be `>=` [MinStakeDuration]
    - Must be `<=` [GlobalMaxStakeDuration]
- **`MinDelegationFee`** is a short is the minimum percentage a validator must
  charge a delegator for delegating.
  - Restrictions
    - Must be `<=` [`reward.PercentDenominator`]
- **`MinDelegatorStake`** is a short which is the minimum amount of funds required to become a delegator.
  - Restrictions
    - Must be `>` 0
- **`MaxValidatorWeightFactor`** is a byte which is the factor which calculates
  the maximum amount of delegation a validator can receive. Note: a value of 1
  effectively disables delegation.
  - Restrictions
    - Must be `>` 0
- **`UptimeRequirement`** is a short which is the minimum percentage a validator
  must be online and responsive to receive a reward.
  - Restrictions
    - Must be `<=` [`reward.PercentDenominator`]
- **`SubnetAuth`** contains `SigIndices` and has a type id of `0x0000000a`.
  `SigIndices` is a list of unique ints that define the addresses signing the
  control signature to authorizes this transformation. The array must be sorted
  low to high.

### Gantt Unsigned Transform Lux L1 TX Specification

```text
+----------------------+------------------+----------------------------------+
| base_tx              : BaseTx           |              size(base_tx) bytes |
+----------------------+------------------+----------------------------------+
| subnet_id            : [32]byte         |                         32 bytes |
+----------------------+------------------+----------------------------------+
| asset_id             : [32]byte         |                         32 bytes |
+----------------------+------------------+----------------------------------+
| initial_supply       : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| maximum_supply       : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| min_consumption_rate : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| max_consumption_rate : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| min_validator_stake  : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| max_validator_stake  : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| min_stake_duration   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| max_stake_duration   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| min_delegation_fee   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| min_delegator_stake  : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| max_validator_weight_factor : byte      |                           1 byte |
+----------------------+------------------+----------------------------------+
| uptime_requirement   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| subnet_auth          : SubnetAuth       | 4 bytes + len(sig_indices) bytes |
+----------------------+------------------+----------------------------------+
| 141 + size(base_tx) + len(sig_indices) bytes                               |
+----------------------------------------------------------------------------+
```

### Proto Unsigned Transform Lux L1 TX Specification

```text
message TransformSubnetTx {
    BaseTx base_tx = 1;              // size(base_tx)
    SubnetID subnet_id = 2;          // 32 bytes
    bytes asset_id = 3;              // 32 bytes
    uint64 initial_supply = 4;       // 08 bytes
    uint64 maximum_supply = 5;       // 08 bytes
    uint64 min_consumption_rate = 6; // 08 bytes
    uint64 max_consumption_rate = 7; // 08 bytes
    uint64 min_validator_stake = 8;  // 08 bytes
    uint64 max_validator_stake = 9;  // 08 bytes
    uint32 min_stake_duration = 10;  // 04 bytes
    uint32 max_stake_duration = 11;  // 04 bytes
    uint32 min_delegation_fee = 12;  // 04 bytes
    uint32 min_delegator_stake = 13; // 08 bytes
    byte max_validator_weight_factor = 14; // 01 byte
    uint32 uptime_requirement = 15; // 04 bytes
    SubnetAuth subnet_auth = 16;    // 04 bytes + len(sig_indices)
}
```

### Unsigned Transform Lux L1 TX Example

Let's make an unsigned transform Lux L1 TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 18"`
- **`SubnetID`**: `0x5fa29ed4356903dac2364713c60f57d8472c7dda4a5e08d88a88ad8ea71aed60`
- **`AssetID`**: `0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada`
- **`InitialSupply`**: `0x000000e8d4a51000`
- **`MaximumSupply`**: `0x000009184e72a000`
- **`MinConsumptionRate`**: `0x0000000000000001`
- **`MaxConsumptionRate`**: `0x000000000000000a`
- **`MinValidatorStake`**: `0x000000174876e800`
- **`MaxValidatorStake`**: `0x000001d1a94a2000`
- **`MinStakeDuration`**: `0x00015180`
- **`MaxStakeDuration`**: `0x01e13380`
- **`MinDelegationFee`**: `0x00002710`
- **`MinDelegatorStake`**: `0x000000174876e800`
- **`MaxValidatorWeightFactor`**: `0x05`
- **`UptimeRequirement`**: `0x000c3500`
- **`SubnetAuth`**:
  - **`TypeID`**: `0x0000000a`
  - **`SigIndices`**: `0x00000000`

```text
[
    BaseTx       <- 0000001800003039e902a9a86640bfdb1cd0e36c0cc982b83e5765fad5f6bbe6abdcce7b5ae7d7c700000000000000014a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db000000003d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a70000000500000000000f4240000000010000000000000000
    SubnetID     <- 0x5fa29ed4356903dac2364713c60f57d8472c7dda4a5e08d88a88ad8ea71aed60
    AssetID      <- 0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada
    InitialSupply <- 0x000000e8d4a51000
    MaximumSupply <- 0x000009184e72a000
    MinConsumptionRate <- 0x0000000000000001
    MaxConsumptionRate <- 0x000000000000000a
    MinValidatorStake <- 0x000000174876e800
    MaxValidatorStake <- 0x000001d1a94a2000
    MinStakeDuration <- 0x00015180
    MaxStakeDuration <- 0x01e13380
    MinDelegationFee <- 0x00002710
    MinDelegatorStake <- 0x000000174876e800
    MaxValidatorWeightFactor <- 0x05
    UptimeRequirement <- 0x000c3500
    SubnetAuth   <- 0x0000000a0000000100000000
]
=
[
    // BaseTx:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x30, 0x39,
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa, 0xd5, 0xf6, 0xbb, 0xe6,
    0xab, 0xdc, 0xce, 0x7b, 0x5a, 0xe7, 0xd7, 0xc7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    0x00, 0x00, 0x00, 0x00, 0x3d, 0x0a, 0xd1, 0x2b,
    0x8e, 0xe8, 0x92, 0x8e, 0xdf, 0x24, 0x8c, 0xa9,
    0x1c, 0xa5, 0x56, 0x00, 0xfb, 0x38, 0x3f, 0x07,
    0xc3, 0x2b, 0xff, 0x1d, 0x6d, 0xec, 0x47, 0x2b,
    0x25, 0xcf, 0x59, 0xa7, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x0f, 0x42, 0x40,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x5f, 0xa2, 0x9e, 0xd4,
    0x35, 0x69, 0x03, 0xda, 0xc2, 0x36, 0x47, 0x13,
    0xc6, 0x0f, 0x57, 0xd8, 0x47, 0x2c, 0x7d, 0xda,
    0x4a, 0x5e, 0x08, 0xd8, 0x8a, 0x88, 0xad, 0x8e,
    0xa7, 0x1a, 0xed, 0x60, 0xf3, 0x08, 0x6d, 0x7b,
    0xfc, 0x35, 0xbe, 0x1c, 0x68, 0xdb, 0x66, 0x4b,
    0xa9, 0xce, 0x61, 0xa2, 0x06, 0x01, 0x26, 0xb0,
    0xd6, 0xb4, 0xbf, 0xb0, 0x9f, 0xd7, 0xa5, 0xfb,
    0x76, 0x78, 0xca, 0xda, 0x00, 0x00, 0x00, 0xe8,
    0xd4, 0xa5, 0x10, 0x00, 0x00, 0x00, 0x09, 0x18,
    0x4e, 0x72, 0xa0, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x0a, 0x00, 0x00, 0x00, 0x17,
    0x48, 0x76, 0xe8, 0x00, 0x00, 0x00, 0x01, 0xd1,
    0xa9, 0x4a, 0x20, 0x00, 0x00, 0x01, 0x51, 0x80,
    0x01, 0xe1, 0x33, 0x80, 0x00, 0x00, 0x27, 0x10,
    0x00, 0x00, 0x00, 0x17, 0x48, 0x76, 0xe8, 0x00,
    0x05, 0x00, 0x0c, 0x35, 0x00, 0x00, 0x00, 0x00,
    0x0a, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
    0x00,
    // SubnetID
    0x5f, 0xa2, 0x9e, 0xd4, 0x35, 0x69, 0x03, 0xda,
    0xc2, 0x36, 0x47, 0x13, 0xc6, 0x0f, 0x57, 0xd8,
    0x47, 0x2c, 0x7d, 0xda, 0x4a, 0x5e, 0x08, 0xd8,
    0x8a, 0x88, 0xad, 0x8e, 0xa7, 0x1a, 0xed, 0x60,
    // AssetID
    0xf3, 0x08, 0x6d, 0x7b, 0xfc, 0x35, 0xbe, 0x1c,
    0x68, 0xdb, 0x66, 0x4b, 0xa9, 0xce, 0x61, 0xa2,
    0x06, 0x01, 0x26, 0xb0, 0xd6, 0xb4, 0xbf, 0xb0,
    0x9f, 0xd7, 0xa5, 0xfb, 0x76, 0x78, 0xca, 0xda,
    // InitialSupply
    0x00, 0x00, 0x00, 0xe8, 0xd4, 0xa5, 0x10, 0x00,
    // MaximumSupply
    0x00, 0x00, 0x09, 0x18, 0x4e, 0x72, 0xa0, 0x00,
    // MinConsumptionRate
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    // MaxConsumptionRate
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0a,
    // MinValidatorStake
    0x00, 0x00, 0x00, 0x17, 0x48, 0x76, 0xe8, 0x00,
    // MaxValidatorStake
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // MinStakeDuration
    0x00, 0x01, 0x51, 0x80,
    // MaxStakeDuration
    0x01, 0xe1, 0x33, 0x80,
    // MinDelegationFee
    0x00, 0x00, 0x27, 0x10,
    // MinDelegatorStake
    0x00, 0x00, 0x00, 0x17, 0x48, 0x76, 0xe8, 0x00,
    // MaxValidatorWeightFactor
    0x05,
    // UptimeRequirement
    0x00, 0x0c, 0x35, 0x00,
```
// SubnetAuth
```
    // SubnetAuth TypeID
    0x00, 0x00, 0x00, 0x0a,
    // SigIndices length
    0x00, 0x00, 0x00, 0x01,
    // SigIndices
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Lux L1 Validator TX

### What Unsigned Add Lux L1 Validator TX Contains

An unsigned add Lux L1 validator TX contains a `BaseTx`, `Validator`,
`SubnetID`, and `SubnetAuth`. The `TypeID` for this type is `0x0000000d`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is the 20 byte node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`SubnetID`** is the 32 byte Lux L1 ID to add the validator to.
- **`SubnetAuth`** contains `SigIndices` and has a type id of `0x0000000a`.
  `SigIndices` is a list of unique ints that define the addresses signing the
  control signature to add a validator to an Lux L1. The array must be sorted low
  to high.

### Gantt Unsigned Add Lux L1 Validator TX Specification

```text
+---------------+----------------------+-----------------------------------------+
| base_tx       : BaseTx               |                     size(base_tx) bytes |
+---------------+----------------------+-----------------------------------------+
| validator     : Validator            |                                44 bytes |
+---------------+----------------------+-----------------------------------------+
| subnet_id     : [32]byte             |                                32 bytes |
+---------------+----------------------+-----------------------------------------+
| subnet_auth   : SubnetAuth           |        4 bytes + len(sig_indices) bytes |
+---------------+----------------------+-----------------------------------------+
                                   | 80 + len(sig_indices) + size(base_tx) bytes |
                                   +---------------------------------------------+
```

### Proto Unsigned Add Lux L1 Validator TX Specification

```text
message AddSubnetValidatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    Validator validator = 2;    // size(validator)
    SubnetID subnet_id = 3;     // 32 bytes
    SubnetAuth subnet_auth = 4; // 04 bytes + len(sig_indices)
}
```

### Unsigned Add Lux L1 Validator TX Example

Let's make an unsigned add Lux L1 validator TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0d"`
- **`NodeID`**: `0xe9094f73698002fd52c90819b457b9fbc866ab80`
- **`StarTime`**: `0x000000005f21f31d`
- **`EndTime`**: `0x000000005f497dc6`
- **`Weight`**: `0x000000000000d431`
- **`SubnetID`**: `0x58b1092871db85bc752742054e2e8be0adf8166ec1f0f0769f4779f14c71d7eb`
- **`SubnetAuth`**:
  - **`TypeID`**: `0x0000000a`
  - **`SigIndices`**: `0x00000000`

```text
[
    BaseTx       <- 0x0000000d000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    NodeID       <- 0xe9094f73698002fd52c90819b457b9fbc866ab80
    StarTime     <- 0x000000005f21f31d
    EndTime      <- 0x000000005f497dc6
    Weight       <- 0x000000000000d431
    SubnetID     <- 0x58b1092871db85bc752742054e2e8be0adf8166ec1f0f0769f4779f14c71d7eb
    SubnetAuth TypeID   <- 0x0000000a
    SubnetAuth   <- 0x00000000
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x0d,
    0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    0x00, 0x00, 0x00, 0x01,
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Node ID
    0xe9, 0x09, 0x4f, 0x73, 0x69, 0x80, 0x02, 0xfd,
    0x52, 0xc9, 0x08, 0x19, 0xb4, 0x57, 0xb9, 0xfb,
    0xc8, 0x66, 0xab, 0x80,
    // StartTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x21, 0xf3, 0x1d,
    // EndTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x49, 0x7d, 0xc6,
    // Weight
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // SubnetID
    0x58, 0xb1, 0x09, 0x28, 0x71, 0xdb, 0x85, 0xbc,
    0x75, 0x27, 0x42, 0x05, 0x4e, 0x2e, 0x8b, 0xe0,
    0xad, 0xf8, 0x16, 0x6e, 0xc1, 0xf0, 0xf0, 0x76,
    0x9f, 0x47, 0x79, 0xf1, 0x4c, 0x71, 0xd7, 0xeb,
    // SubnetAuth
    // SubnetAuth TypeID
    0x00, 0x00, 0x00, 0x0a,
    // SigIndices length
    0x00, 0x00, 0x00, 0x01,
    // SigIndices
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Delegator TX

### What Unsigned Add Delegator TX Contains

An unsigned add delegator TX contains a `BaseTx`, `Validator`, `Stake`, and
`RewardsOwner`. The `TypeID` for this type is `0x0000000e`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is 20 bytes which is the node ID of the delegatee.
  - **`StartTime`** is a long which is the Unix time when the delegator starts delegating.
  - **`EndTime`** is a long which is the Unix time when the delegator stops
    delegating (and staked LUX is returned).
  - **`Weight`** is a long which is the amount the delegator stakes
- **`Stake`** Stake has `LockedOuts`
  - **`LockedOuts`** An array of Transferable Outputs that are locked for the
    duration of the staking period. At the end of the staking period, these
    outputs are refunded to their respective addresses.
- **`RewardsOwner`** An `SECP256K1OutputOwners`

### Gantt Unsigned Add Delegator TX Specification

```text
+---------------+-----------------------+-----------------------------------------+
| base_tx       : BaseTx                |                     size(base_tx) bytes |
+---------------+-----------------------+-----------------------------------------+
| validator     : Validator             |                                44 bytes |
+---------------+-----------------------+-----------------------------------------+
| stake         : Stake                 |                  size(LockedOuts) bytes |
+---------------+-----------------------+-----------------------------------------+
| rewards_owner : SECP256K1OutputOwners |               size(rewards_owner) bytes |
+---------------+-----------------------+-----------------------------------------+
                |    44 + size(stake) + size(rewards_owner) + size(base_tx) bytes |
                +-----------------------------------------------------------------+
```

### Proto Unsigned Add Delegator TX Specification

```text
message AddDelegatorTx {
    BaseTx base_tx = 1;                      // size(base_tx)
    Validator validator = 2;                 // 44 bytes
    Stake stake = 3;                         // size(LockedOuts)
    SECP256K1OutputOwners rewards_owner = 4; // size(rewards_owner)
}
```

### Unsigned Add Delegator TX Example

Let's make an unsigned add delegator TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0e"`
- **`NodeID`**: `0xe9094f73698002fd52c90819b457b9fbc866ab80`
- **`StarTime`**: `0x000000005f21f31d`
- **`EndTime`**: `0x000000005f497dc6`
- **`Weight`**: `0x000000000000d431`
- **`Stake`**: `0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c`
- **`RewardsOwner`**: `0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c`

```text
[
    BaseTx       <- 0x0000000e000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    NodeID       <- 0xe9094f73698002fd52c90819b457b9fbc866ab80
    StarTime     <- 0x000000005f21f31d
    EndTime      <- 0x000000005f497dc6
    Weight       <- 0x000000000000d431
    Stake        <- 0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c
    RewardsOwner <- 0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x0e, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    0x00, 0x00, 0x00, 0x01,
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Node ID
    0xe9, 0x09, 0x4f, 0x73, 0x69, 0x80, 0x02, 0xfd,
    0x52, 0xc9, 0x08, 0x19, 0xb4, 0x57, 0xb9, 0xfb,
    0xc8, 0x66, 0xab, 0x80,
    // StartTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x21, 0xf3, 0x1d,
    // EndTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x49, 0x7d, 0xc6,
    // Weight
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // Stake
    0x00, 0x00, 0x00, 0x01, 0x39, 0xc3, 0x3a, 0x49,
    0x9c, 0xe4, 0xc3, 0x3a, 0x3b, 0x09, 0xcd, 0xd2,
    0xcf, 0xa0, 0x1a, 0xe7, 0x0d, 0xbf, 0x2d, 0x18,
    0xb2, 0xd7, 0xd1, 0x68, 0x52, 0x44, 0x40, 0xe5,
    0x5d, 0x55, 0x00, 0x88, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
    0x3c, 0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a,
    0x0e, 0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68,
    0x61, 0xe1, 0xb2, 0x9c,
    // RewardsOwner
    0x00, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
]
```

## Unsigned Create Chain TX

### What Unsigned Create Chain TX Contains

An unsigned create chain TX contains a `BaseTx`, `SubnetID`, `ChainName`,
`VMID`, `FxIDs`, `GenesisData` and `SubnetAuth`. The `TypeID` for this type is
`0x0000000f`.

- **`BaseTx`**
- **`SubnetID`** ID of the Lux L1 that validates this blockchain
- **`ChainName`** A human readable name for the chain; need not be unique
- **`VMID`** ID of the VM running on the new chain
- **`FxIDs`** IDs of the feature extensions running on the new chain
- **`GenesisData`** Byte representation of genesis state of the new chain
- **`SubnetAuth`** Authorizes this blockchain to be added to this Lux L1

### Gantt Unsigned Create Chain TX Specification

```text
+--------------+-------------+------------------------------------------+
| base_tx      : BaseTx      |                      size(base_tx) bytes |
+--------------+-------------+------------------------------------------+
| subnet_id    : SubnetID    |                                 32 bytes |
+--------------+-------------+------------------------------------------+
| chain_name   : ChainName   |                2 + len(chain_name) bytes |
+--------------+-------------+------------------------------------------+
| vm_id        : VMID        |                                 32 bytes |
+--------------+-------------+------------------------------------------+
| fx_ids       : FxIDs       |                   4 + size(fx_ids) bytes |
+--------------+-------------+------------------------------------------+
| genesis_data : GenesisData |             4 + size(genesis_data) bytes |
+--------------+-------------+------------------------------------------+
| subnet_auth  : SubnetAuth  |                  size(subnet_auth) bytes |
+--------------+-------------+------------------------------------------+
               | 74 + size(base_tx) + size(chain_name) + size(fx_ids) + |
               |           size(genesis_data) + size(subnet_auth) bytes |
+--------------+--------------------------------------------------------+
```

### Proto Unsigned Create Chain TX Specification

```text
message CreateChainTx {
    BaseTx base_tx = 1;               // size(base_tx)
    SubnetID subnet_id = 2;           // 32 bytes
    ChainName chain_name = 3;         // 2 + len(chain_name) bytes
    VMID vm_id = 4;                   // 32 bytes
    FxIDs fx_ids = 5;                 // 4 + size(fx_ids) bytes
    GenesisData genesis_data = 6      // 4 + size(genesis_data) bytes
    SubnetAuth subnet_auth = 7;       // size(subnet_auth) bytes
}
```

### Unsigned Create Chain TX Example

Let's make an unsigned create chain TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0f"`
- **`SubnetID`**: `24tZhrm8j8GCJRE9PomW8FaeqbgGS4UAQjJnqqn8pq5NwYSYV1`
- **`ChainName`**: `EPIC XVM`
- **`VMID`**: `xvm`
- **`FxIDs`**: [`secp256k1fx`]
- **`GenesisData`**: `11111DdZMhYXUZiFV9FNpfpTSQroysXhzWicG954YAKfkrk3bCEzLVY7gun1eAmAwMiQzVhtGpdR6dnPVcfhBE7brzkJ1r4wzi3dgA8G9Jwc4WpZ6Uh4Dr9aTdw7sFA5cpvCAVBsx6Xf3CB82jwH1gjPZ3WQnnCSKr2reoLtam6TfyYRra5xxXSkZcUm6BaJMW4fKzNP58uyExajPYKZvT5LrQ7MPJ9Fp7ebmYSzXg7YYauNARj`
- **`SubnetAuth`**: `0x0000000a0000000100000000`

```text
[
    BaseTx       <- 0x0000000f000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    SubnetID     <- 0x8c86d07cd60218661863e0116552dccd5bd84c564bd29d7181dbddd5ec616104
    ChainName    <- 0x455049432041564d
    VMID         <- 0x61766d0000000000000000000000000000000000000000000000000000000000
    FxIDs        <- 0x736563703235366b316678000000000000000000000000000000000000000000
    GenesisData  <- 0x000000000001000e4173736574416c6961735465737400000539000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b66726f6d20736e6f77666c616b6520746f206176616c616e636865000a54657374204173736574000454455354000000000100000000000000010000000700000000000001fb000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c
    SubnetAuth   <- 0x0000000a0000000100000000
]
=
[
  // base tx
  0x00, 0x00, 0x00, 0x0f,
  0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x39, 0xc3, 0x3a, 0x49, 0x9c, 0xe4, 0xc3, 0x3a,
  0x3b, 0x09, 0xcd, 0xd2, 0xcf, 0xa0, 0x1a, 0xe7,
  0x0d, 0xbf, 0x2d, 0x18, 0xb2, 0xd7, 0xd1, 0x68,
  0x52, 0x44, 0x40, 0xe5, 0x5d, 0x55, 0x00, 0x88,
  0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x12, 0x30,
  0x9c, 0xd5, 0xfd, 0xc0, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
  0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
  0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  // end base tx

  // Subnet id
  0x8c, 0x86, 0xd0, 0x7c, 0xd6, 0x02, 0x18, 0x66,
  0x18, 0x63, 0xe0, 0x11, 0x65, 0x52, 0xdc, 0xcd,
  0x5b, 0xd8, 0x4c, 0x56, 0x4b, 0xd2, 0x9d, 0x71,
  0x81, 0xdb, 0xdd, 0xd5, 0xec, 0x61, 0x61, 0x04,

  // chain name length
  0x00, 0x08,

  // chain name
  0x45, 0x50, 0x49, 0x43, 0x20, 0x41, 0x56, 0x4d,

  // vm id
  0x61, 0x76, 0x6d, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,

  // fxids
  // num fxids
  0x00, 0x00, 0x00, 0x01,
  // fxid
  0x73, 0x65, 0x63, 0x70, 0x32, 0x35, 0x36, 0x6b,
  0x31, 0x66, 0x78, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,

  // genesis data len
  0x00, 0x00, 0x00, 0xb0,
  // genesis data
  0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x0e,
  0x41, 0x73, 0x73, 0x65, 0x74, 0x41, 0x6c, 0x69,
  0x61, 0x73, 0x54, 0x65, 0x73, 0x74, 0x00, 0x00,
  0x05, 0x39, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x1b, 0x66, 0x72,
  0x6f, 0x6d, 0x20, 0x73, 0x6e, 0x6f, 0x77, 0x66,
  0x6c, 0x61, 0x6b, 0x65, 0x20, 0x74, 0x6f, 0x20,
  0x61, 0x76, 0x61, 0x6c, 0x61, 0x6e, 0x63, 0x68,
  0x65, 0x00, 0x0a, 0x54, 0x65, 0x73, 0x74, 0x20,
  0x41, 0x73, 0x73, 0x65, 0x74, 0x00, 0x04, 0x54,
  0x45, 0x53, 0x54, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x01, 0xfb, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
  0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
  0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,

  // type id (Subnet Auth)
  0x00, 0x00, 0x00, 0x0a,
  // num address indices
  0x00, 0x00, 0x00, 0x01,
  // address index
  0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Create Lux L1 TX

### What Unsigned Create Lux L1 TX Contains

An unsigned create Lux L1 TX contains a `BaseTx`, and `RewardsOwner`. The `TypeID` for this type is `0x00000010`.

- **`BaseTx`**
- **`RewardsOwner`** A `SECP256K1OutputOwners`

### Gantt Unsigned Create Lux L1 TX Specification

```text
+-----------------+-----------------------|---------------------------------+
| base_tx         : BaseTx                |             size(base_tx) bytes |
+-----------------+-----------------------+--------------------------------+
| rewards_owner   : SECP256K1OutputOwners |       size(rewards_owner) bytes |
+-----------------+-----------------------+---------------------------------+
                                | size(rewards_owner) + size(base_tx) bytes |
                                +-------------------------------------------+
```

### Proto Unsigned Create Lux L1 TX Specification

```text
message CreateSubnetTx {
    BaseTx base_tx = 1;                      // size(base_tx)
    SECP256K1OutputOwners rewards_owner = 2; // size(rewards_owner)
}
```

### Unsigned Create Lux L1 TX Example

Let's make an unsigned create Lux L1 TX that uses the inputs from the previous examples:

- **`BaseTx`**: "Example BaseTx as defined above but with TypeID set to 16"
- **`RewardsOwner`**:
  - **`TypeId`**: 11
  - **`Locktime`**: 0
  - **`Threshold`**: 1
  - **`Addresses`**: \[ 0xda2bee01be82ecc00c34f361eda8eb30fb5a715c \]

```text
[
    BaseTx        <- 0x00000010000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    RewardsOwner <-
        TypeID    <- 0x0000000b
        Locktime  <- 0x0000000000000000
        Threshold <- 0x00000001
        Addresses <- [
            0xda2bee01be82ecc00c34f361eda8eb30fb5a715c,
        ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x10,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x39, 0xc3, 0x3a, 0x49, 0x9c, 0xe4, 0xc3, 0x3a,
    0x3b, 0x09, 0xcd, 0xd2, 0xcf, 0xa0, 0x1a, 0xe7,
    0x0d, 0xbf, 0x2d, 0x18, 0xb2, 0xd7, 0xd1, 0x68,
    0x52, 0x44, 0x40, 0xe5, 0x5d, 0x55, 0x00, 0x88,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x12, 0x30,
    0x9c, 0xd5, 0xfd, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
    0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
    0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // RewardsOwner type id
    0x00, 0x00, 0x00, 0x0b,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c
]
```

## Unsigned Import TX

### What Unsigned Import TX Contains

An unsigned import TX contains a `BaseTx`, `SourceChain`, and `Ins`. The `TypeID` for this type is `0x00000011`.

- **`BaseTx`**
- **`SourceChain`** is a 32-byte source blockchain ID.
- **`Ins`** is a variable length array of Transferable Inputs.

### Gantt Unsigned Import TX Specification

```text
+-----------------+--------------|---------------------------------+
| base_tx         : BaseTx       |             size(base_tx) bytes |
+-----------------+--------------+---------------------------------+
| source_chain    : [32]byte     |                        32 bytes |
+-----------------+--------------+---------------------------------+
| ins             : []TransferIn |             4 + size(ins) bytes |
+-----------------+--------------+---------------------------------+
                            | 36 + size(ins) + size(base_tx) bytes |
                            +--------------------------------------+
```

### Proto Unsigned Import TX Specification

```text
message ImportTx {
    BaseTx base_tx = 1;          // size(base_tx)
    bytes source_chain = 2;      // 32 bytes
    repeated TransferIn ins = 3; // 4 bytes + size(ins)
}
```

### Unsigned Import TX Example

Let's make an unsigned import TX that uses the inputs from the previous examples:

- **`BaseTx`**: "Example BaseTx as defined above with TypeID set to 17"
- **`SourceChain`**:
- **`Ins`**: "Example SECP256K1 Transfer Input as defined above"

```text
[
    BaseTx        <- 0x00000011000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    SourceChain   <- 0x787cd3243c002e9bf5bbbaea8a42a16c1a19cc105047c66996807cbf16acee10
    Ins <- [
            // input:
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x11,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x39, 0xc3, 0x3a, 0x49, 0x9c, 0xe4, 0xc3, 0x3a,
    0x3b, 0x09, 0xcd, 0xd2, 0xcf, 0xa0, 0x1a, 0xe7,
    0x0d, 0xbf, 0x2d, 0x18, 0xb2, 0xd7, 0xd1, 0x68,
    0x52, 0x44, 0x40, 0xe5, 0x5d, 0x55, 0x00, 0x88,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x12, 0x30,
    0x9c, 0xd5, 0xfd, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
    0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
    0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // sourceChain
    0x78, 0x7c, 0xd3, 0x24, 0x3c, 0x00, 0x2e, 0x9b,
    0xf5, 0xbb, 0xba, 0xea, 0x8a, 0x42, 0xa1, 0x6c,
    0x1a, 0x19, 0xcc, 0x10, 0x50, 0x47, 0xc6, 0x69,
    0x96, 0x80, 0x7c, 0xbf, 0x16, 0xac, 0xee, 0x10,
    // input count:
    0x00, 0x00, 0x00, 0x01,
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Export TX

### What Unsigned Export TX Contains

An unsigned export TX contains a `BaseTx`, `DestinationChain`, and `Outs`. The
`TypeID` for this type is `0x00000012`.

- **`DestinationChain`** is the 32 byte ID of the chain where the funds are being exported to.
- **`Outs`** is a variable length array of Transferable Outputs.

### Gantt Unsigned Export TX Specification

```text
+-------------------+---------------+--------------------------------------+
| base_tx           : BaseTx        |                  size(base_tx) bytes |
+-------------------+---------------+--------------------------------------+
| destination_chain : [32]byte      |                             32 bytes |
+-------------------+---------------+--------------------------------------+
| outs              : []TransferOut |                 4 + size(outs) bytes |
+-------------------+---------------+--------------------------------------+
                          | 36 + size(outs) + size(base_tx) bytes |
                          +---------------------------------------+
```

### Proto Unsigned Export TX Specification

```text
message ExportTx {
    BaseTx base_tx = 1;            // size(base_tx)
    bytes destination_chain = 2;   // 32 bytes
    repeated TransferOut outs = 3; // 4 bytes + size(outs)
}
```

### Unsigned Export TX Example

Let's make an unsigned export TX that uses the outputs from the previous examples:

- `BaseTx`: "Example BaseTx as defined above" with `TypeID` set to 18
- `DestinationChain`: `0x0000000000000000000000000000000000000000000000000000000000000000`
- `Outs`: "Example SECP256K1 Transfer Output as defined above"

```text
[
    BaseTx           <- 0x00000012000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    DestinationChain <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Outs <- [
        000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x12
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // destination_chain:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // outs[] count:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
]
```

## Credentials

Credentials have one possible types: `SECP256K1Credential`. Each credential is
paired with an Input or Operation. The order of the credentials match the order
of the inputs or operations.

## SECP256K1 Credential

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) credential
contains a list of 65-byte recoverable signatures.

### What SECP256K1 Credential Contains

- **`TypeID`** is the ID for this type. It is `0x00000009`.
- **`Signatures`** is an array of 65-byte recoverable signatures. The order of
  the signatures must match the input's signature indices.

### Gantt SECP256K1 Credential Specification

```text
+------------------------------+---------------------------------+
| type_id         : int        |                         4 bytes |
+-----------------+------------+---------------------------------+
| signatures      : [][65]byte |  4 + 65 * len(signatures) bytes |
+-----------------+------------+---------------------------------+
                               |  8 + 65 * len(signatures) bytes |
                               +---------------------------------+
```

### Proto SECP256K1 Credential Specification

```text
message SECP256K1Credential {
    uint32 TypeID = 1;             // 4 bytes
    repeated bytes signatures = 2; // 4 bytes + 65 bytes * len(signatures)
}
```

### SECP256K1 Credential Example

Let's make a payment input with:

- **`signatures`**:
- `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00`
- `0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    Signatures <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00,
        0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x09,
    // length:
    0x00, 0x00, 0x00, 0x02,
    // sig[0]
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00,
    // sig[1]
    0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
    0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f,
    0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57,
    0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d, 0x5f,
    0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
    0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d, 0x6f,
    0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
    0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
    0x00,
]
```

## Signed Transaction

A signed transaction is an unsigned transaction with the addition of an array of credentials.

### What Signed Transaction Contains

A signed transaction contains a `CodecID`, `UnsignedTx`, and `Credentials`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`UnsignedTx`** is an unsigned transaction, as described above.
- **`Credentials`** is an array of credentials. Each credential will be paired
  with the input in the same index at this credential.

### Gantt Signed Transaction Specification

```text
+---------------------+--------------+------------------------------------------------+
| codec_id            : uint16       |                                        2 bytes |
+---------------------+--------------+------------------------------------------------+
| unsigned_tx         : UnsignedTx   |                        size(unsigned_tx) bytes |
+---------------------+--------------+------------------------------------------------+
| credentials         : []Credential |                    4 + size(credentials) bytes |
+---------------------+--------------+------------------------------------------------+
                                     | 6 + size(unsigned_tx) + len(credentials) bytes |
                                     +------------------------------------------------+
```

### Proto Signed Transaction Specification

```text
message Tx {
    uint32 codec_id = 1;                 // 2 bytes
    UnsignedTx unsigned_tx = 2;          // size(unsigned_tx)
    repeated Credential credentials = 3; // 4 bytes + size(credentials)
}
```

### Signed Transaction Example

Let's make a signed transaction that uses the unsigned transaction and credential from the previous examples.

- **`CodecID`**: `0`
- **`UnsignedTx`**: `0x0000000100000003ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000003000000070000000400010203`
- **`Credentials`** `0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    CodecID     <- 0x0000
    UnsignedTx  <- 0x0000000100000003ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000003000000070000000400010203
    Credentials <- [
        0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Codec ID
    0x00, 0x00,
    // unsigned transaction:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x03,
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd, 0xcc, 0xcc, 0xcc, 0xcc,
    0xbb, 0xbb, 0xbb, 0xbb, 0xaa, 0xaa, 0xaa, 0xaa,
    0x99, 0x99, 0x99, 0x99, 0x88, 0x88, 0x88, 0x88,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
    0x00, 0x00, 0x00, 0x01, 0xf1, 0xe1, 0xd1, 0xc1,
    0xb1, 0xa1, 0x91, 0x81, 0x71, 0x61, 0x51, 0x41,
    0x31, 0x21, 0x11, 0x01, 0xf0, 0xe0, 0xd0, 0xc0,
    0xb0, 0xa0, 0x90, 0x80, 0x70, 0x60, 0x50, 0x40,
    0x30, 0x20, 0x10, 0x00, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x04, 0x00, 0x01, 0x02, 0x03
    // number of credentials:
    0x00, 0x00, 0x00, 0x01,
    // credential[0]:
    0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46,
    0x47, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e,
    0x4f, 0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56,
    0x57, 0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d,
    0x5f, 0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
    0x67, 0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d,
    0x6f, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76,
    0x77, 0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e,
    0x7f, 0x00,
]
```

## UTXO

A UTXO is a standalone representation of a transaction output.

### What UTXO Contains

A UTXO contains a `CodecID`, `TxID`, `UTXOIndex`, and `Output`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`TxID`** is a 32-byte transaction ID. Transaction IDs are calculated by
  taking sha256 of the bytes of the signed transaction.
- **`UTXOIndex`** is an int that specifies which output in the transaction
  specified by **`TxID`** that this utxo was created by.
- **`AssetID`** is a 32-byte array that defines which asset this utxo
  references.
- **`Output`** is the output object that created this utxo. The serialization of
  Outputs was defined above.

#### Gantt UTXO Specification

```text
+--------------+----------+-------------------------+
| codec_id     : uint16   |                 2 bytes |
+--------------+----------+-------------------------+
| tx_id        : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output_index : int      |                 4 bytes |
+--------------+----------+-------------------------+
| asset_id     : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output       : Output   |      size(output) bytes |
+--------------+----------+-------------------------+
                          | 70 + size(output) bytes |
                          +-------------------------+
```

### Proto UTXO Specification

```text
message Utxo {
    uint32 codec_id = 1;     // 02 bytes
    bytes tx_id = 2;         // 32 bytes
    uint32 output_index = 3; // 04 bytes
    bytes asset_id = 4;      // 32 bytes
    Output output = 5;       // size(output)
}
```

### UTXO Example

Let's make a UTXO from the signed transaction created above:

- **`CodecID`**: `0`
- **`TxID`**: `0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7`
- **`UTXOIndex`**: 0x00000000
- **`AssetID`**: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- **`Output`**: `"Example SECP256K1 Transferable Output as defined above"`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7
    UTXOIndex <- 0x00000000
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output    <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // Codec ID:
    0x00, 0x00,
    // txID:
    0xf9, 0x66, 0x75, 0x0f, 0x43, 0x88, 0x67, 0xc3,
    0xc9, 0x82, 0x8d, 0xdc, 0xdb, 0xe6, 0x60, 0xe2,
    0x1c, 0xcd, 0xbb, 0x36, 0xa9, 0x27, 0x69, 0x58,
    0xf0, 0x11, 0xba, 0x47, 0x2f, 0x75, 0xd4, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x00,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21, 0x22, 0x23,
    0x24, 0x25, 0x26, 0x27,
]
```

## StakeableLockIn

A StakeableLockIn is a staked and locked input. The StakeableLockIn can only
fund StakeableLockOuts with the same address until its lock time has passed.

### What StakeableLockIn Contains

A StakeableLockIn contains a `TypeID`, `Locktime` and `TransferableIn`.

- **`TypeID`** is the ID for this output type. It is `0x00000015`.
- **`Locktime`** is a long that contains the Unix timestamp before which the
  input can be consumed only to stake. The Unix timestamp is specific to the
  second.
- **`TransferableIn`** is a transferable input object.

### Gantt StakeableLockIn Specification

```text
+-----------------+-------------------+--------------------------------+
| type_id         : int               |                        4 bytes |
+-----------------+-------------------+--------------------------------+
| locktime        : long              |                        8 bytes |
+-----------------+-------------------+--------------------------------+
| transferable_in : TransferableInput |          size(transferable_in) |
+-----------------+-------------------+--------------------------------+
                                    | 12 + size(transferable_in) bytes |
                                    +----------------------------------+
```

### Proto StakeableLockIn Specification

```text
message StakeableLockIn {
    uint32 type_id = 1;                    // 04 bytes
    uint64 locktime = 2;                   // 08 bytes
    TransferableInput transferable_in = 3; // size(transferable_in)
}
```

### StakeableLockIn Example

Let's make a StakeableLockIn with:

- **`TypeID`**: 21
- **`Locktime`**: 54321
- **`TransferableIn`**: "Example SECP256K1 Transfer Input as defined above"

```text
[
    TypeID    <- 0x00000015
    Locktime  <- 0x000000000000d431
    TransferableIn <- [
        f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000100000000,
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x15,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // transferable_in
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
]
```

## StakeableLockOut

A StakeableLockOut is an output that is locked until its lock time, but can be staked in the meantime.

### What StakeableLockOut Contains

A StakeableLockOut contains a `TypeID`, `Locktime` and `TransferableOut`.

- **`TypeID`** is the ID for this output type. It is `0x00000016`.
- **`Locktime`** is a long that contains the Unix timestamp before which the
  output can be consumed only to stake. The Unix timestamp is specific to the
  second.
- **`transferableout`**: "Example SECP256K1 Transfer Output as defined above"

### Gantt StakeableLockOut Specification

```text
+------------------+--------------------+--------------------------------+
| type_id          : int                |                        4 bytes |
+------------------+--------------------+--------------------------------+
| locktime         : long               |                        8 bytes |
+------------------+--------------------+--------------------------------+
| transferable_out : TransferableOutput |         size(transferable_out) |
+------------------+--------------------+--------------------------------+
                                     | 12 + size(transferable_out) bytes |
                                     +-----------------------------------+
```

### Proto StakeableLockOut Specification

```text
message StakeableLockOut {
    uint32 type_id = 1;                      // 04 bytes
    uint64 locktime = 2;                     // 08 bytes
    TransferableOutput transferable_out = 3; // size(transferable_out)
}
```

### StakeableLockOut Example

Let's make a stakeablelockout with:

- **`TypeID`**: 22
- **`Locktime`**: 54321
- **`TransferableOutput`**: `"Example SECP256K1 Transfer Output from above"`

```text
[
    TypeID              <- 0x00000016
    Locktime            <- 0x000000000000d431
    TransferableOutput  <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x16,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // transferable_out
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Lux L1 Auth

### What Lux L1 Auth Contains

Specifies the addresses whose signatures will be provided to demonstrate that
the owners of an Lux L1 approve something.

- **`TypeID`** is the ID for this type. It is `0x0000000a`.
- **`AddressIndices`** defines which addresses' signatures will be attached to
  this transaction. AddressIndices[i] is the index in an Lux L1 owner list that
  corresponds to the signature at index i in the signature list. Must be sorted
  low to high and not have duplicates.

### Gantt Lux L1 Auth Specification

```text
+-----------------+------------------+-------------------------------------+
| type_id         : int              |                             4 bytes |
+-----------------+------------------+-------------------------------------+
| address_indices : []int            |    4 + 4*len(address_indices) bytes |
+-----------------+------------------+-------------------------------------+
                  |                       8 + 4*len(address_indices) bytes |
+-----------------+--------------------------------------------------------+
```

### Proto Lux L1 Auth Specification

```text
message SubnetAuth {
    uint32 type_id = 1;                          // 04 bytes
    repeated AddressIndex address_indices = 2;   // 04 + 4*len(address_indices) bytes
}
```

### Lux L1 Auth Example

Let's make an Lux L1 auth:

- **`TypeID`**: `10`
- **`AddressIndices`**: [`0`]

```text
[
    TypeID                <- 0x0000000a
    AddressIndices        <-  [
       0x00000000
    ]
]

=
[
  // type id
  0x00, 0x00, 00x0, 0x0a,

  // num address indices
  0x00, 0x00, 0x00, 0x01,

  // address index 1
  0x00, 0x00, 0x00, 0x00
]
```

## Validator

A validator verifies transactions on a blockchain.

### What Validator Contains

A validator contains `NodeID`, `Start`, `End`, and `Wght`

- **`NodeID`** is the ID of the validator
- **`Start`** Unix time this validator starts validating
- **`End`** Unix time this validator stops validating
- **`Wght`** Weight of this validator used when sampling

### Gantt Validator Specification

```text
+------------------+----------+
| node_id : string | 20 bytes |
+------------------+----------+
| start   : uint64 | 8 bytes  |
+------------------+----------+
| end     : uint64 | 8 bytes  |
+------------------+----------+
| wght    : uint64 | 8 bytes  |
+------------------+----------+
|                  | 44 bytes |
+------------------+----------+
```

### Proto Validator Specification

```text
message Validator {
    string node_id = 1;        // 20 bytes
    uint64 start = 2;          // 08 bytes
    uint64 end = 3;            // 08 bytes
    uint64 wght = 4;           // 08 bytes
}
```

### Validator Example

Let's make a validator:

- **`NodeID`**: `"NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu"`
- **`Start`**: `1643068824`
- **`End`**: `1644364767`
- **`Wght`**: `20`

```text
[
    NodeID  <- 0xaa18d3991cf637aa6c162f5e95cf163f69cd8291
    Start   <- 0x61ef3d98
    End     <- 0x620303df
    Wght    <- 0x14
]

=
[
  // node id
  0xaa, 0x18, 0xd3, 0x99, 0x1c, 0xf6, 0x37,
  0xaa, 0x6c, 0x16, 0x2f, 0x5e, 0x95, 0xcf,
  0x16, 0x3f, 0x69, 0xcd, 0x82, 0x91,
  // start
  0x61, 0xef, 0x3d, 0x98,
  // end
  0x62, 0x03, 0x03, 0xdf,
  // wght
  0x14,
]
```

## Rewards Owner

Where to send staking rewards when done validating

### What Rewards Owner Contains

A rewards owner contains a `TypeID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this validator. It is `0x0000000b`.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt Rewards Owner Specification

```text
+------------------------+-------------------------------+
| type_id   : int        | 4 bytes                       |
+------------------------+-------------------------------+
| locktime  : long       | 8 bytes                       |
+------------------------+-------------------------------+
| threshold : int        | 4 bytes                       |
+------------------------+-------------------------------+
| addresses : [][20]byte | 4 + 20 * len(addresses) bytes |
+------------------------+-------------------------------+
|                        | 40 bytes                      |
+------------------------+-------------------------------+
```

### Proto Rewards Owner Specification

```text
message RewardsOwner {
    string type_id = 1;           // 4 bytes
    uint64 locktime = 2;          // 08 bytes
    uint32 threshold = 3;         // 04 bytes
    repeated bytes addresses = 4; // 04 bytes + 20 bytes * len(addresses)
}
```

### Rewards Owner Example

Let's make a rewards owner:

- **`TypeID`**: `11`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID  <- 0x0000000b
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]

=
[
  // type id
  0x00, 0x00, 0x00, 0x0b,
  // locktime
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
  // threshold:
  0x00, 0x00, 0x00, 0x01,
  // number of addresses:
  0x00, 0x00, 0x00, 0x02,
  // addrs[0]:
  0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
  0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
  0x6d, 0x55, 0xa9, 0x55,
  // addrs[1]:
  0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
  0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
  0x43, 0xab, 0x08, 0x59,
]
```

## Unsigned Convert Subnet To L1 TX

### What Unsigned Convert Subnet To L1 TX Contains

An unsigned convert subnet to L1 TX contains a `BaseTx`, `Subnet`, `ChainID`, `Address`, `Validators`, and `SubnetAuth`. The `TypeID` for this type is `0x00000030`.

- **`BaseTx`**
- **`Subnet`** ID of the Subnet to transform into an L1. Must not be the Primary Network ID.
- **`ChainID`** BlockchainID where the validator manager lives.
- **`Address`** Address of the validator manager.
- **`Validators`** Initial continuous-fee-paying validators for the L1.
- **`SubnetAuth`** Authorizes this conversion. Must be signed by the Subnet's owner.

### Gantt Unsigned Convert Subnet To L1 TX Specification

```text
+------------+------------------+----------------------------------+
| base_tx    : BaseTx           |              size(base_tx) bytes |
+------------+------------------+----------------------------------+
| subnet     : [32]byte         |                         32 bytes |
+------------+------------------+----------------------------------+
| chain_id   : [32]byte         |                         32 bytes |
+------------+------------------+----------------------------------+
| address    : []byte           |             4 + len(address) bytes |
+------------+------------------+----------------------------------+
| validators : []L1Validator    |         4 + size(validators) bytes |
+------------+------------------+----------------------------------+
| subnet_auth: SubnetAuth       | 4 bytes + len(sig_indices) bytes |
+------------+------------------+----------------------------------+
| 76 + size(base_tx) + len(address) + size(validators) + len(sig_indices) bytes |
+----------------------------------------------------------------------------+
```

### Proto Unsigned Convert Subnet To L1 TX Specification

```text
message ConvertSubnetToL1Tx {
    BaseTx base_tx = 1;              // size(base_tx)
    SubnetID subnet = 2;             // 32 bytes
    ChainID chain_id = 3;            // 32 bytes
    bytes address = 4;               // 4 + len(address) bytes
    repeated L1Validator validators = 5; // 4 + size(validators) bytes
    SubnetAuth subnet_auth = 6;      // 4 bytes + len(sig_indices)
}
```

## Unsigned Register L1 Validator TX

### What Unsigned Register L1 Validator TX Contains

An unsigned register L1 validator TX contains a `BaseTx`, `Balance`, `Signer` and `Message`. The `TypeID` for this type is `0x00000031`.

- **`BaseTx`**
- **`Balance`** is the amount of LUX being provided for fees, where `Balance <= sum($LUX inputs) - sum($LUX outputs) - TxFee`.
- **`Signer`** is a BLS signature proving ownership of the BLS public key specified in the Message for this validator.
- **`Message`** is a RegisterL1ValidatorMessage payload delivered as a Warp Message.

### Gantt Unsigned Register L1 Validator TX Specification

```text
+------------+------------------+----------------------------------+
| base_tx    : BaseTx           |              size(base_tx) bytes |
+------------+------------------+----------------------------------+
| balance    : uint64           |                          8 bytes |
+------------+------------------+----------------------------------+
| signer     : [96]byte         |                         96 bytes |
+------------+------------------+----------------------------------+
| message    : WarpMessage      |             size(message) bytes |
+------------+------------------+----------------------------------+
| 104 + size(base_tx) + size(message) bytes                       |
+------------------------------------------------------------------+
```

### Proto Unsigned Register L1 Validator TX Specification

```text
message RegisterL1ValidatorTx {
    BaseTx base_tx = 1;        // size(base_tx)
    uint64 balance = 2;        // 8 bytes
    bytes signer = 3;          // 96 bytes
    WarpMessage message = 4;   // size(message) bytes
}
```

## Unsigned Set L1 Validator Weight TX

### What Unsigned Set L1 Validator Weight TX Contains

An unsigned set L1 validator weight TX contains a `BaseTx` and `Message`. The `TypeID` for this type is `0x00000032`.

- **`BaseTx`**
- **`Message`** An L1ValidatorWeightMessage payload delivered as a Warp Message. Contains the validationID, nonce, and new weight for a validator.

### Gantt Unsigned Set L1 Validator Weight TX Specification

```text
+------------+------------------+----------------------------------+
| base_tx    : BaseTx           |              size(base_tx) bytes |
+------------+------------------+----------------------------------+
| message    : WarpMessage      |             size(message) bytes |
+------------+------------------+----------------------------------+
| size(base_tx) + size(message) bytes                             |
+------------------------------------------------------------------+
```

### Proto Unsigned Set L1 Validator Weight TX Specification

```text
message SetL1ValidatorWeightTx {
    BaseTx base_tx = 1;        // size(base_tx)
    WarpMessage message = 2;   // size(message) bytes
}
```

## Unsigned Disable L1 Validator TX

### What Unsigned Disable L1 Validator TX Contains

An unsigned disable L1 validator TX contains a `BaseTx`, `ValidationID` and `DisableAuth`. The `TypeID` for this type is `0x00000033`.

- **`BaseTx`**
- **`ValidationID`** ID corresponding to the validator to be disabled.
- **`DisableAuth`** Authorizes this validator to be disabled. Must be signed by the DisableOwner specified when the validator was added.

### Gantt Unsigned Disable L1 Validator TX Specification

```text
+----------------+------------------+----------------------------------+
| base_tx        : BaseTx           |              size(base_tx) bytes |
+----------------+------------------+----------------------------------+
| validation_id  : [32]byte         |                         32 bytes |
+----------------+------------------+----------------------------------+
| disable_auth   : Verifiable       |        size(disable_auth) bytes  |
+----------------+------------------+----------------------------------+
| 32 + size(base_tx) + size(disable_auth) bytes                       |
+----------------------------------------------------------------------+
```

### Proto Unsigned Disable L1 Validator TX Specification

```text
message DisableL1ValidatorTx {
    BaseTx base_tx = 1;            // size(base_tx)
    bytes validation_id = 2;       // 32 bytes
    Verifiable disable_auth = 3;   // size(disable_auth) bytes
}
```

## Unsigned Increase L1 Validator Balance TX

### What Unsigned Increase L1 Validator Balance TX Contains

An unsigned increase L1 validator balance TX contains a `BaseTx`, `ValidationID` and `Balance`. The `TypeID` for this type is `0x00000034`.

- **`BaseTx`**
- **`ValidationID`** ID corresponding to the validator.
- **`Balance`** Additional LUX amount to add to the validator's balance where `Balance <= sum($LUX inputs) - sum($LUX outputs) - TxFee`.

### Gantt Unsigned Increase L1 Validator Balance TX Specification

```text
+----------------+------------------+----------------------------------+
| base_tx        : BaseTx           |              size(base_tx) bytes |
+----------------+------------------+----------------------------------+
| validation_id  : [32]byte         |                         32 bytes |
+----------------+------------------+----------------------------------+
| balance        : uint64           |                          8 bytes |
+----------------+------------------+----------------------------------+
| 40 + size(base_tx) bytes                                            |
+----------------------------------------------------------------------+
```

### Proto Unsigned Increase L1 Validator Balance TX Specification

```text
message IncreaseL1ValidatorBalanceTx {
    BaseTx base_tx = 1;       // size(base_tx)
    bytes validation_id = 2;  // 32 bytes
    uint64 balance = 3;       // 8 bytes
}
```

# Subnet-EVM Configs (/docs/rpcs/subnet-evm/config)

---
title: "Subnet-EVM Configs"
description: "This page describes the configuration options available for the Subnet-EVM."
edit_url: https://github.com/luxfi/subnet-evm/edit/master/plugin/evm/config/config.md
---

# Subnet-EVM Configuration

> **Note**: These are the configuration options available in the Subnet-EVM codebase. To set these values, you need to create a configuration file at `~/.luxgo/configs/chains/<blockchainID>/config.json`.
>
> For the LuxGo node configuration options, see the LuxGo Configuration page.

This document describes all configuration options available for Subnet-EVM.

## Example Configuration

```json
{
  "eth-apis": ["eth", "eth-filter", "net", "web3"],
  "pruning-enabled": true,
  "commit-interval": 4096,
  "trie-clean-cache": 512,
  "trie-dirty-cache": 512,
  "snapshot-cache": 256,
  "rpc-gas-cap": 50000000,
  "log-level": "info",
  "metrics-expensive-enabled": true,
  "continuous-profiler-dir": "./profiles",
  "state-sync-enabled": false,
  "accepted-cache-size": 32
}
```

## Configuration Format

Configuration is provided as a JSON object. All fields are optional unless otherwise specified.

## API Configuration

### Ethereum APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `eth-apis` | array of strings | List of Ethereum services that should be enabled | `["eth", "eth-filter", "net", "web3", "internal-eth", "internal-blockchain", "internal-transaction"]` |

### Subnet-EVM Specific APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `validators-api-enabled` | bool | Enable the validators API | `true` |
| `admin-api-enabled` | bool | Enable the admin API for administrative operations | `false` |
| `admin-api-dir` | string | Directory for admin API operations | - |
| `warp-api-enabled` | bool | Enable the Warp API for cross-chain messaging | `false` |

### API Limits and Security

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `rpc-gas-cap` | uint64 | Maximum gas limit for RPC calls | `50,000,000` |
| `rpc-tx-fee-cap` | float64 | Maximum transaction fee cap in LUX | `100` |
| `api-max-duration` | duration | Maximum duration for API calls (0 = no limit) | `0` |
| `api-max-blocks-per-request` | int64 | Maximum number of blocks per getLogs request (0 = no limit) | `0` |
| `http-body-limit` | uint64 | Maximum size of HTTP request bodies | - |
| `batch-request-limit` | uint64 | Maximum number of requests that can be batched in an RPC call. For no limit, set either this or `batch-response-max-size` to 0 | `1000` | 
| `batch-response-max-size` | uint64 | Maximum size (in bytes) of response that can be returned from a batched RPC call. For no limit, set either this or `batch-request-limit` to 0. Defaults to `25 MB`| `1000` |

### WebSocket Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `ws-cpu-refill-rate` | duration | Rate at which WebSocket CPU usage quota is refilled (0 = no limit) | `0` |
| `ws-cpu-max-stored` | duration | Maximum stored WebSocket CPU usage quota (0 = no limit) | `0` |

## Cache Configuration

### Trie Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `trie-clean-cache` | int | Size of the trie clean cache in MB | `512` |
| `trie-dirty-cache` | int | Size of the trie dirty cache in MB | `512` |
| `trie-dirty-commit-target` | int | Memory limit to target in the dirty cache before performing a commit in MB | `20` |
| `trie-prefetcher-parallelism` | int | Maximum concurrent disk reads trie prefetcher should perform | `16` |

### Other Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-cache` | int | Size of the snapshot disk layer clean cache in MB | `256` |
| `accepted-cache-size` | int | Depth to keep in the accepted headers and logs cache (blocks) | `32` |
| `state-sync-server-trie-cache` | int | Trie cache size for state sync server in MB | `64` |

## Ethereum Settings

### Transaction Processing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `preimages-enabled` | bool | Enable preimage recording | `false` |
| `allow-unfinalized-queries` | bool | Allow queries for unfinalized blocks | `false` |
| `allow-unprotected-txs` | bool | Allow unprotected transactions (without EIP-155) | `false` |
| `allow-unprotected-tx-hashes` | array | List of specific transaction hashes allowed to be unprotected | EIP-1820 registry tx |
| `local-txs-enabled` | bool | Enable treatment of transactions from local accounts as local | `false` |

### Snapshots

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-wait` | bool | Wait for snapshot generation on startup | `false` |
| `snapshot-verification-enabled` | bool | Enable snapshot verification | `false` |

## Pruning and State Management

### Basic Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `pruning-enabled` | bool | Enable state pruning to save disk space | `true` |
| `commit-interval` | uint64 | Interval at which to persist EVM and atomic tries (blocks) | `4096` |
| `accepted-queue-limit` | int | Maximum blocks to queue before blocking during acceptance | `64` |

### State Reconstruction

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `allow-missing-tries` | bool | Suppress warnings about incomplete trie index | `false` |
| `populate-missing-tries` | uint64 | Starting block for re-populating missing tries (null = disabled) | `null` |
| `populate-missing-tries-parallelism` | int | Concurrent readers for re-populating missing tries | `1024` |

### Offline Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `offline-pruning-enabled` | bool | Enable offline pruning | `false` |
| `offline-pruning-bloom-filter-size` | uint64 | Bloom filter size for offline pruning in MB | `512` |
| `offline-pruning-data-directory` | string | Directory for offline pruning data | - |

### Historical Data

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `historical-proof-query-window` | uint64 | Number of blocks before last accepted for proof queries (archive mode only, ~24 hours) | `43200` |
| `state-history` | uint64 | Number of most recent states that are accesible on disk (pruning mode only) | `32` |

## Transaction Pool Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `tx-pool-price-limit` | uint64 | Minimum gas price for transaction acceptance | - |
| `tx-pool-price-bump` | uint64 | Minimum price bump percentage for transaction replacement | - |
| `tx-pool-account-slots` | uint64 | Maximum number of executable transaction slots per account | - |
| `tx-pool-global-slots` | uint64 | Maximum number of executable transaction slots for all accounts | - |
| `tx-pool-account-queue` | uint64 | Maximum number of non-executable transaction slots per account | - |
| `tx-pool-global-queue` | uint64 | Maximum number of non-executable transaction slots for all accounts | - |
| `tx-pool-lifetime` | duration | Maximum time transactions can stay in the pool | - |

## Gossip Configuration

### Push Gossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-percent-stake` | float64 | Percentage of total stake to push gossip to (range: [0, 1]) | `0.9` |
| `push-gossip-num-validators` | int | Number of validators to push gossip to | `100` |
| `push-gossip-num-peers` | int | Number of non-validator peers to push gossip to | `0` |

### Regossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-regossip-num-validators` | int | Number of validators to regossip to | `10` |
| `push-regossip-num-peers` | int | Number of non-validator peers to regossip to | `0` |
| `priority-regossip-addresses` | array | Addresses to prioritize for regossip | - |

### Timing Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-frequency` | duration | Frequency of push gossip | `100ms` |
| `pull-gossip-frequency` | duration | Frequency of pull gossip | `1s` |
| `regossip-frequency` | duration | Frequency of regossip | `30s` |

## Logging and Monitoring

### Logging

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `log-level` | string | Logging level (trace, debug, info, warn, error, crit) | `"info"` |
| `log-json-format` | bool | Use JSON format for logs | `false` |

### Profiling

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `continuous-profiler-dir` | string | Directory for continuous profiler output (empty = disabled) | - |
| `continuous-profiler-frequency` | duration | Frequency to run continuous profiler | `15m` |
| `continuous-profiler-max-files` | int | Maximum number of profiler files to maintain | `5` |

### Metrics

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `metrics-expensive-enabled` | bool | Enable expensive debug-level metrics; this includes Firewood metrics | `true` |

## Security and Access

### Keystore

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `keystore-directory` | string | Directory for keystore files (absolute or relative path) | - |
| `keystore-external-signer` | string | External signer configuration | - |
| `keystore-insecure-unlock-allowed` | bool | Allow insecure account unlocking | `false` |

### Fee Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `feeRecipient` | string | Address to send transaction fees to (leave empty if not supported) | - |

## Network and Sync

### Network

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `max-outbound-active-requests` | int64 | Maximum number of outbound active requests for VM2VM network | `16` |

### State Sync

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `state-sync-enabled` | bool | Enable state sync | `false` |
| `state-sync-skip-resume` | bool | Force state sync to use highest available summary block | `false` |
| `state-sync-ids` | string | Comma-separated list of state sync IDs | - |
| `state-sync-commit-interval` | uint64 | Commit interval for state sync (blocks) | `16384` |
| `state-sync-min-blocks` | uint64 | Minimum blocks ahead required for state sync | `300000` |
| `state-sync-request-size` | uint16 | Number of key/values to request per state sync request | `1024` |

## Database Configuration

> **WARNING**: `firewood` and `path` schemes are untested in production. Using `path` is strongly discouraged. To use `firewood`, you must also set the following config options:
>
> - `pruning-enabled: true` (enabled by default)
> - `state-sync-enabled: false`
> - `snapshot-cache: 0`

Failing to set these options will result in errors on VM initialization. Additionally, not all APIs are available - see these portions of the config documentation for more details.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `database-type` | string | Type of database to use | `"pebbledb"` |
| `database-path` | string | Path to database directory | - |
| `database-read-only` | bool | Open database in read-only mode | `false` |
| `database-config` | string | Inline database configuration | - |
| `database-config-file` | string | Path to database configuration file | - |
| `use-standalone-database` | bool | Use standalone database instead of shared one | - |
| `inspect-database` | bool | Inspect database on startup | `false` |
| `state-scheme` | string |  EXPERIMENTAL: specifies the database scheme to store state data; can be one of `hash` or `firewood` | `hash` | 

## Transaction Indexing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `transaction-history` | uint64 | Maximum number of blocks from head whose transaction indices are reserved (0 = no limit) | - |
| `tx-lookup-limit` | uint64 | **Deprecated** - use `transaction-history` instead | - |
| `skip-tx-indexing` | bool | Skip indexing transactions entirely | `false` |

## Warp Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `warp-off-chain-messages` | array | Off-chain messages the node should be willing to sign | - |
| `prune-warp-db-enabled` | bool | Clear warp database on startup | `false` |

## Miscellaneous

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `airdrop` | string | Path to airdrop file | - |
| `skip-upgrade-check` | bool | Skip checking that upgrades occur before last accepted block ⚠️ **Warning**: Only use when you understand the implications | `false` |
| `min-delay-target` | integer | The minimum delay between blocks (in milliseconds) that this node will attempt to use when creating blocks | Parent block's target |

## Gossip Constants

The following constants are defined for transaction gossip behavior and cannot be configured without a custom build of Subnet-EVM:

| Constant | Type | Description | Value |
|----------|------|-------------|-------|
| Bloom Filter Min Target Elements | int | Minimum target elements for bloom filter | `8,192` |
| Bloom Filter Target False Positive Rate | float | Target false positive rate | `1%` |
| Bloom Filter Reset False Positive Rate | float | Reset false positive rate | `5%` |
| Bloom Filter Churn Multiplier | int | Churn multiplier | `3` |
| Push Gossip Discarded Elements | int | Number of discarded elements | `16,384` |
| Tx Gossip Target Message Size | size | Target message size for transaction gossip | `20 KiB` |
| Tx Gossip Throttling Period | duration | Throttling period | `10s` |
| Tx Gossip Throttling Limit | int | Throttling limit | `2` |
| Tx Gossip Poll Size | int | Poll size | `1` |

## Validation Notes

- Cannot enable `populate-missing-tries` while pruning or offline pruning is enabled
- Cannot run offline pruning while pruning is disabled  
- Commit interval must be non-zero when pruning is enabled
- `push-gossip-percent-stake` must be in range `[0, 1]`
- Some settings may require node restart to take effect

# Admin RPC (/docs/rpcs/other)

---
title: "Admin RPC"
description: "This page is an overview of the Admin RPC associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/api/admin/service.md
---

The Admin API can be used for measuring node health and debugging.

<Callout title="Note">
The Admin API is disabled by default for security reasons. To run a node with the Admin API enabled, use [`config flag --api-admin-enabled=true`](https://build.lux.network/docs/nodes/configure/configs-flags#--api-admin-enabled-boolean).

This API set is for a specific node, it is unavailable on the [public server](https://build.lux.network/docs/tooling/rpc-providers).
</Callout>

## Format

This API uses the `json 2.0` RPC format. For details, see [here](https://build.lux.network/docs/api-reference/guides/issuing-api-calls).

## Endpoint

```
/ext/admin
```

## Methods

### `admin.alias`

Assign an API endpoint an alias, a different endpoint for the API. The original endpoint will still work. This change only affects this node; other nodes will not know about this alias.

**Signature**:

```
admin.alias({endpoint:string, alias:string}) -> {}
```

- `endpoint` is the original endpoint of the API. `endpoint` should only include the part of the endpoint after `/ext/`.
- The API being aliased can now be called at `ext/alias`.
- `alias` can be at most 512 characters.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.alias",
    "params": {
        "alias":"myAlias",
        "endpoint":"bc/X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

Now, calls to the Exchange-Chain can be made to either `/ext/bc/X` or, equivalently, to `/ext/myAlias`.

### `admin.aliasChain`

Give a blockchain an alias, a different name that can be used any place the blockchain's ID is used.

<Callout title="Note">
Aliasing a chain can also be done via the [Node API](https://build.lux.network/docs/nodes/configure/configs-flags#--chain-aliases-file-string).

Note that the alias is set for each chain on each node individually. In a multi-node Lux L1, the same alias should be configured on each node to use an alias across an Lux L1 successfully. Setting an alias for a chain on one node does not register that alias with other nodes automatically.
</Callout>

**Signature**:

```
admin.aliasChain(
    {
        chain:string,
        alias:string
    }
) -> {}
```

- `chain` is the blockchain's ID.
- `alias` can now be used in place of the blockchain's ID (in API endpoints, for example.)

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.aliasChain",
    "params": {
        "chain":"sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM",
        "alias":"myBlockchainAlias"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

Now, instead of interacting with the blockchain whose ID is `sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM` by making API calls to `/ext/bc/sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM`, one can also make calls to `ext/bc/myBlockchainAlias`.

### `admin.getChainAliases`

Returns the aliases of the chain

**Signature**:

```
admin.getChainAliases(
  {
    chain:string
  }
) -> {aliases:string[]}
```

- `chain` is the blockchain's ID.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.getChainAliases",
    "params": {
        "chain":"sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "aliases": [
      "X",
      "xvm",
      "2eNy1mUFdmaxXNj1eQHUe7Np4gju9sJsEtWQ4MX3ToiNKuADed"
    ]
  },
  "id": 1
}
```

### `admin.getLoggerLevel`

Returns log and display levels of loggers.

**Signature**:

```
admin.getLoggerLevel(
  {
    loggerName:string // optional
  }
) -> {
        loggerLevels: {
          loggerName: {
            logLevel: string,
            displayLevel: string
          }
        }
    }
```

- `loggerName` is the name of the logger to be returned. This is an optional argument. If not specified, it returns all possible loggers.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.getLoggerLevel",
    "params": {
        "loggerName": "C"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "loggerLevels": {
      "C": {
        "logLevel": "DEBUG",
        "displayLevel": "INFO"
      }
    }
  },
  "id": 1
}
```

### `admin.loadVMs`

Dynamically loads any virtual machines installed on the node as plugins. See [here](https://build.lux.network/docs/virtual-machines#installing-a-vm) for more information on how to install a virtual machine on a node.

**Signature**:

```
admin.loadVMs() -> {
  newVMs: map[string][]string
  failedVMs: map[string]string,
}
```

- `failedVMs` is only included in the response if at least one virtual machine fails to be loaded.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.loadVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "newVMs": {
      "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": ["foovm"]
    },
    "failedVMs": {
      "rXJsCSEYXg2TehWxCEEGj6JU2PWKTkd6cBdNLjoe2SpsKD9cy": "error message"
    }
  },
  "id": 1
}
```

### `admin.lockProfile`

Writes a profile of mutex statistics to `lock.profile`.

**Signature**:

```
admin.lockProfile() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.lockProfile",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.memoryProfile`

Writes a memory profile of the to `mem.profile`.

**Signature**:

```
admin.memoryProfile() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.memoryProfile",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.setLoggerLevel`

Sets log and display levels of loggers.

**Signature**:

```
admin.setLoggerLevel(
  {
    loggerName: string, // optional
    logLevel: string, // optional
    displayLevel: string, // optional
  }
) -> {}
```

- `loggerName` is the logger's name to be changed. This is an optional parameter. If not specified, it changes all possible loggers.
- `logLevel` is the log level of written logs, can be omitted.
- `displayLevel` is the log level of displayed logs, can be omitted.

`logLevel` and `displayLevel` cannot be omitted at the same time.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.setLoggerLevel",
    "params": {
        "loggerName": "C",
        "logLevel": "DEBUG",
        "displayLevel": "INFO"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.startCPUProfiler`

Start profiling the CPU utilization of the node. To stop, call `admin.stopCPUProfiler`. On stop, writes the profile to `cpu.profile`.

**Signature**:

```
admin.startCPUProfiler() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.startCPUProfiler",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.stopCPUProfiler`

Stop the CPU profile that was previously started.

**Signature**:

```
admin.stopCPUProfiler() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.stopCPUProfiler"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

# AI & LLM Integration (/docs/tooling/ai-llm)

---
title: AI & LLM Integration
description: Access Lux documentation programmatically for AI applications
icon: Bot
---

The Lux Build provides AI-friendly access to documentation through standardized formats. Whether you're building a chatbot, using Claude/ChatGPT, or integrating with AI development tools, we offer multiple ways to access our docs.

## Endpoints Overview

| Endpoint | Purpose |
| :------- | :------ |
| `/llms.txt` | AI sitemap - structured index of all documentation |
| `/llms-full.txt` | Complete docs in one file for full context loading |
| `/api/llms/page?path=...` | Fetch any single page as markdown |
| `/api/mcp` | MCP server for dynamic search and retrieval |

## llms.txt

A structured markdown index following the [llms.txt standard](https://llmstxt.org/). Use this for content discovery.

```
https://build.lux.network/llms.txt
```

Returns organized sections (Documentation, Academy, Integrations, Blog) with links and descriptions.

## llms-full.txt

All documentation content in a single markdown file for one-time context loading.

```
https://build.lux.network/llms-full.txt
```

Contains 1300+ pages. For models with limited context, use the MCP server or individual page endpoint instead.

## Individual Pages

Fetch any page as markdown:

```
https://build.lux.network/api/llms/page?path=/docs/primary-network/overview
https://build.lux.network/api/llms/page?path=/academy/blockchain-fundamentals/blockchain-intro
```

Supports `/docs/`, `/academy/`, `/integrations/`, and `/blog/` paths.

## MCP Server

The [Model Context Protocol](https://modelcontextprotocol.io/) server enables AI systems to search and retrieve documentation dynamically.

**Endpoint:** `https://build.lux.network/api/mcp`

### Tools

| Tool | Purpose |
| :--- | :------ |
| `lux_docs_search` | Search docs by query with optional source filter |
| `lux_docs_fetch` | Get a specific page by URL path |
| `lux_docs_list_sections` | List all sections with page counts |

### Claude Code Setup

Add the MCP server to your project:

```bash
claude mcp add lux-docs --transport http https://build.lux.network/api/mcp
```

Or add to your `.claude/settings.json`:

```json
{
  "mcpServers": {
    "lux-docs": {
      "transport": {
        "type": "http",
        "url": "https://build.lux.network/api/mcp"
      }
    }
  }
}
```

### Claude Desktop Setup

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lux-docs": {
      "transport": {
        "type": "http",
        "url": "https://build.lux.network/api/mcp"
      }
    }
  }
}
```

### JSON-RPC Protocol

The MCP server uses JSON-RPC 2.0 for communication:

```bash
curl -X POST https://build.lux.network/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"lux_docs_search","arguments":{"query":"create L1","limit":5}}}'
```

**Response format:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"title\":\"Create an L1\",\"url\":\"/docs/lux-l1s/create\",\"description\":\"...\",\"score\":45}]"
      }
    ]
  }
}
```

### Search Tool Examples

**Search all documentation:**

```bash
curl -X POST https://build.lux.network/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "lux_docs_search",
      "arguments": {
        "query": "smart contracts",
        "limit": 10
      }
    }
  }'
```

**Filter by source:**

```bash
# Search only academy content
curl -X POST https://build.lux.network/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "lux_docs_search",
      "arguments": {
        "query": "blockchain basics",
        "source": "academy",
        "limit": 5
      }
    }
  }'
```

**Fetch specific page:**

```bash
curl -X POST https://build.lux.network/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "lux_docs_fetch",
      "arguments": {
        "url": "/docs/primary-network/overview"
      }
    }
  }'
```

## Standards

- [llms.txt](https://llmstxt.org/) - AI sitemap standard
- [Model Context Protocol](https://modelcontextprotocol.io/) - Anthropic's standard for AI tool access
- [JSON-RPC 2.0](https://www.jsonrpc.org/specification) - MCP server protocol


# Exchange-Chain API (/docs/rpcs/x-chain/api)

---
title: "Exchange-Chain API"
description: "This page is an overview of the Exchange-Chain API associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/vms/xvm/service.md
---

The [Exchange-Chain](https://build.lux.network/docs/primary-network#x-chain),
Lux's native platform for creating and trading assets, is an instance of the Lux Virtual
Machine (XVM). This API allows clients to create and trade assets on the Exchange-Chain and other instances
of the XVM.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](https://build.lux.network/docs/rpcs/other/guides/issuing-api-calls).

## Endpoints

`/ext/bc/X` to interact with the Exchange-Chain.

`/ext/bc/blockchainID` to interact with other XVM instances, where `blockchainID` is the ID of a
blockchain running the XVM.

## Methods

### `xvm.getAllBalances`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).
</Callout>

Get the balances of all assets controlled by a given address.

**Signature:**

```sh
xvm.getAllBalances({address:string}) -> {
    balances: []{
        asset: string,
        balance: int
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.getAllBalances",
    "params" :{
        "address":"X-lux1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balances": [
      {
        "asset": "LUX",
        "balance": "102"
      },
      {
        "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79",
        "balance": "10000"
      }
    ]
  },
  "id": 1
}
```

### `xvm.getAssetDescription`

Get information about an asset.

**Signature:**

```sh
xvm.getAssetDescription({assetID: string}) -> {
    assetId: string,
    name: string,
    symbol: string,
    denomination: int
}
```

- `assetID` is the id of the asset for which the information is requested.
- `name` is the asset’s human-readable, not necessarily unique name.
- `symbol` is the asset’s symbol.
- `denomination` determines how balances of this asset are displayed by user interfaces. If
  denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units
  of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as
  .100, etc.

<Callout type="note">
The AssetID for LUX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

For finding the `assetID` of other assets, this [info] might be useful.
Also, `xvm.getUTXOs` returns the `assetID` in its output.
</Callout>

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getAssetDescription",
    "params" :{
        "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
        "name": "Lux",
        "symbol": "LUX",
        "denomination": "9"
    },
    "id": 1
}`
```

### `xvm.getBalance`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).
</Callout>

Get the balance of an asset controlled by a given address.

**Signature:**

```sh
xvm.getBalance({
    address: string,
    assetID: string
}) -> {balance: int}
```

- `address` owner of the asset
- `assetID` id of the asset for which the balance is requested

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"xvm.getBalance",
  "params" :{
      "address":"X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "299999999999900",
    "utxoIDs": [
      {
        "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo",
        "outputIndex": 1
      }
    ]
  }
}
```

### `xvm.getBlock`

Returns the block with the given id.

**Signature:**

```sh
xvm.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getBlock",
    "params": {
        "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2",
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.getBlockByHeight`

Returns block at the given height.

**Signature:**

```sh
xvm.getBlockByHeight({
    height: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockHeight` is the block height. It should be in `string` format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getBlockByHeight",
    "params": {
        "height": "275686313486",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de",
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.getHeight`

Returns the height of the last accepted block.

**Signature:**

```sh
xvm.getHeight() ->
{
    height: uint64,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "5094088"
  },
  "id": 1
}
```

### `xvm.getTx`

Returns the specified transaction. The `encoding` parameter sets the format of the returned
transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`.

**Signature:**

```sh
xvm.getTx({
    txID: string,
    encoding: string, //optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getTx",
    "params" :{
        "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [],
        "inputs": [
          {
            "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2570382395,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "destinationChain": "11111111111111111111111111111111LpoYY",
        "exportedOutputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-lux1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 2569382395,
              "locktime": 0,
              "threshold": 1
            }
          }
        ]
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400"
            ]
          }
        }
      ],
      "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL"
    },
    "encoding": "json"
  },
  "id": 1
}
```

Where:

- `credentials` is a list of this transaction's credentials. Each credential proves that this
  transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a
  list of signatures.
- `unsignedTx` is the non-signature portion of the transaction.
- `networkID` is the ID of the network this transaction happened on. (Lux Mainnet is `1`.)
- `blockchainID` is the ID of the blockchain this transaction happened on. (Lux Mainnet
  Exchange-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.)
- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to
  another chain.
- Each element of `inputs` is an input of this transaction which has not been imported from another
  chain.
- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the
  blockchain ID that assets are being imported from, and the inputs that are being imported.
- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify
  the blockchain ID that assets are being exported to, and the UTXOs that are being exported.

An output contains:

- `assetID`: The ID of the asset being transferred. (The Mainnet Lux ID is
  `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.)
- `fxID`: The ID of the FX this output uses.
- `output`: The FX-specific contents of this output.

Most outputs use the secp256k1 FX, look like this:

```json
{
  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
  "output": {
    "addresses": ["X-lux126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"],
    "amount": 1530084210,
    "locktime": 0,
    "threshold": 1
  }
}
```

The above output can be consumed after Unix time `locktime` by a transaction that has signatures
from `threshold` of the addresses in `addresses`.

### `xvm.getTxFee`

Get the fees of the network.

**Signature**:

```
xvm.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
}
```

- `txFee` is the default fee for making transactions.
- `createAssetTxFee` is the fee for creating a new asset.

All fees are denominated in nLUX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.getTxFee",
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000"
  }
}
```

### `xvm.getTxStatus`

<Callout type="warn">
Deprecated as of **v1.10.0**.
</Callout>

Get the status of a transaction sent to the network.

**Signature:**

```sh
xvm.getTxStatus({txID: string}) -> {status: string}
```

`status` is one of:

- `Accepted`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Rejected`: The transaction will never be accepted by any node in the network
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "Accepted"
  }
}
```

### `xvm.getUTXOs`

Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve
the atomic UTXOs exported from that chain to the X Chain.

**Signature:**

```sh
xvm.getUTXOs({
    addresses: []string,
    limit: int, //optional
    startIndex: { //optional
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string //optional
}) -> {
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :2,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "sourceChain": "P",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.issueTx`

Send a signed transaction to the network. `encoding` specifies the format of the signed transaction.
Can only be `hex` when a value is provided.

**Signature:**

```sh
xvm.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

### `wallet.issueTx`

Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies
the format of the signed transaction. Can only be `hex` when a value is provided.

This call is made to the wallet API endpoint:

`/ext/bc/X/wallet`

:::caution
Endpoint deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

:::

**Signature:**

```sh
wallet.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"wallet.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

# LuxGo Exchange-Chain RPC (/docs/rpcs/x-chain)

---
title: "LuxGo Exchange-Chain RPC"
description: "This page is an overview of the Exchange-Chain RPC associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/vms/xvm/service.md
---

The [Exchange-Chain](https://build.lux.network/docs/quick-start/primary-network#x-chain),
Lux's native platform for creating and trading assets, is an instance of the Lux Virtual
Machine (XVM). This API allows clients to create and trade assets on the Exchange-Chain and other instances
of the XVM.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](https://build.lux.network/docs/api-reference/guides/issuing-api-calls).

## Endpoints

`/ext/bc/X` to interact with the Exchange-Chain.

`/ext/bc/blockchainID` to interact with other XVM instances, where `blockchainID` is the ID of a
blockchain running the XVM.

## Methods

### `xvm.getAllBalances`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).
</Callout>

Get the balances of all assets controlled by a given address.

**Signature:**

```sh
xvm.getAllBalances({address:string}) -> {
    balances: []{
        asset: string,
        balance: int
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.getAllBalances",
    "params" :{
        "address":"X-lux1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balances": [
      {
        "asset": "LUX",
        "balance": "102"
      },
      {
        "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79",
        "balance": "10000"
      }
    ]
  },
  "id": 1
}
```

### `xvm.getAssetDescription`

Get information about an asset.

**Signature:**

```sh
xvm.getAssetDescription({assetID: string}) -> {
    assetId: string,
    name: string,
    symbol: string,
    denomination: int
}
```

- `assetID` is the id of the asset for which the information is requested.
- `name` is the asset’s human-readable, not necessarily unique name.
- `symbol` is the asset’s symbol.
- `denomination` determines how balances of this asset are displayed by user interfaces. If
  denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units
  of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as
  .100, etc.

<Callout type="note">
The AssetID for LUX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

For finding the `assetID` of other assets, this [info] might be useful.
Also, `xvm.getUTXOs` returns the `assetID` in its output.
</Callout>

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getAssetDescription",
    "params" :{
        "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
        "name": "Lux",
        "symbol": "LUX",
        "denomination": "9"
    },
    "id": 1
}`
```

### `xvm.getBalance`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).
</Callout>

Get the balance of an asset controlled by a given address.

**Signature:**

```sh
xvm.getBalance({
    address: string,
    assetID: string
}) -> {balance: int}
```

- `address` owner of the asset
- `assetID` id of the asset for which the balance is requested

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"xvm.getBalance",
  "params" :{
      "address":"X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "299999999999900",
    "utxoIDs": [
      {
        "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo",
        "outputIndex": 1
      }
    ]
  }
}
```

### `xvm.getBlock`

Returns the block with the given id.

**Signature:**

```sh
xvm.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getBlock",
    "params": {
        "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2",
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.getBlockByHeight`

Returns block at the given height.

**Signature:**

```sh
xvm.getBlockByHeight({
    height: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockHeight` is the block height. It should be in `string` format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getBlockByHeight",
    "params": {
        "height": "275686313486",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de",
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.getHeight`

Returns the height of the last accepted block.

**Signature:**

```sh
xvm.getHeight() ->
{
    height: uint64,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "5094088"
  },
  "id": 1
}
```

### `xvm.getTx`

Returns the specified transaction. The `encoding` parameter sets the format of the returned
transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`.

**Signature:**

```sh
xvm.getTx({
    txID: string,
    encoding: string, //optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getTx",
    "params" :{
        "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [],
        "inputs": [
          {
            "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2570382395,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "destinationChain": "11111111111111111111111111111111LpoYY",
        "exportedOutputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-lux1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 2569382395,
              "locktime": 0,
              "threshold": 1
            }
          }
        ]
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400"
            ]
          }
        }
      ],
      "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL"
    },
    "encoding": "json"
  },
  "id": 1
}
```

Where:

- `credentials` is a list of this transaction's credentials. Each credential proves that this
  transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a
  list of signatures.
- `unsignedTx` is the non-signature portion of the transaction.
- `networkID` is the ID of the network this transaction happened on. (Lux Mainnet is `1`.)
- `blockchainID` is the ID of the blockchain this transaction happened on. (Lux Mainnet
  Exchange-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.)
- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to
  another chain.
- Each element of `inputs` is an input of this transaction which has not been imported from another
  chain.
- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the
  blockchain ID that assets are being imported from, and the inputs that are being imported.
- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify
  the blockchain ID that assets are being exported to, and the UTXOs that are being exported.

An output contains:

- `assetID`: The ID of the asset being transferred. (The Mainnet Lux ID is
  `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.)
- `fxID`: The ID of the FX this output uses.
- `output`: The FX-specific contents of this output.

Most outputs use the secp256k1 FX, look like this:

```json
{
  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
  "output": {
    "addresses": ["X-lux126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"],
    "amount": 1530084210,
    "locktime": 0,
    "threshold": 1
  }
}
```

The above output can be consumed after Unix time `locktime` by a transaction that has signatures
from `threshold` of the addresses in `addresses`.

### `xvm.getTxFee`

Get the fees of the network.

**Signature**:

```
xvm.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
}
```

- `txFee` is the default fee for making transactions.
- `createAssetTxFee` is the fee for creating a new asset.

All fees are denominated in nLUX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.getTxFee",
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000"
  }
}
```

### `xvm.getTxStatus`

<Callout type="warn">
Deprecated as of **v1.10.0**.
</Callout>

Get the status of a transaction sent to the network.

**Signature:**

```sh
xvm.getTxStatus({txID: string}) -> {status: string}
```

`status` is one of:

- `Accepted`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Rejected`: The transaction will never be accepted by any node in the network
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "Accepted"
  }
}
```

### `xvm.getUTXOs`

Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve
the atomic UTXOs exported from that chain to the X Chain.

**Signature:**

```sh
xvm.getUTXOs({
    addresses: []string,
    limit: int, //optional
    startIndex: { //optional
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string //optional
}) -> {
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :2,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "sourceChain": "P",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.issueTx`

Send a signed transaction to the network. `encoding` specifies the format of the signed transaction.
Can only be `hex` when a value is provided.

**Signature:**

```sh
xvm.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

### `wallet.issueTx`

Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies
the format of the signed transaction. Can only be `hex` when a value is provided.

This call is made to the wallet API endpoint:

`/ext/bc/X/wallet`

:::caution
Endpoint deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

:::

**Signature:**

```sh
wallet.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"wallet.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

# Exchange-Chain RPC (/docs/rpcs/x-chain/rpc)

---
title: "Exchange-Chain RPC"
description: "This page is an overview of the Exchange-Chain RPC associated with LuxGo."
edit_url: https://github.com/luxfi/luxgo/edit/master/vms/xvm/service.md
---

The [Exchange-Chain](https://build.lux.network/docs/primary-network#x-chain),
Lux's native platform for creating and trading assets, is an instance of the Lux Virtual
Machine (XVM). This API allows clients to create and trade assets on the Exchange-Chain and other instances
of the XVM.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](https://build.lux.network/docs/rpcs/other/guides/issuing-api-calls).

## Endpoints

`/ext/bc/X` to interact with the Exchange-Chain.

`/ext/bc/blockchainID` to interact with other XVM instances, where `blockchainID` is the ID of a
blockchain running the XVM.

## Methods

### `xvm.getAllBalances`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).
</Callout>

Get the balances of all assets controlled by a given address.

**Signature:**

```sh
xvm.getAllBalances({address:string}) -> {
    balances: []{
        asset: string,
        balance: int
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.getAllBalances",
    "params" :{
        "address":"X-lux1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balances": [
      {
        "asset": "LUX",
        "balance": "102"
      },
      {
        "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79",
        "balance": "10000"
      }
    ]
  },
  "id": 1
}
```

### `xvm.getAssetDescription`

Get information about an asset.

**Signature:**

```sh
xvm.getAssetDescription({assetID: string}) -> {
    assetId: string,
    name: string,
    symbol: string,
    denomination: int
}
```

- `assetID` is the id of the asset for which the information is requested.
- `name` is the asset’s human-readable, not necessarily unique name.
- `symbol` is the asset’s symbol.
- `denomination` determines how balances of this asset are displayed by user interfaces. If
  denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units
  of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as
  .100, etc.

<Callout type="note">
The AssetID for LUX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

For finding the `assetID` of other assets, this [info] might be useful.
Also, `xvm.getUTXOs` returns the `assetID` in its output.
</Callout>

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getAssetDescription",
    "params" :{
        "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
        "name": "Lux",
        "symbol": "LUX",
        "denomination": "9"
    },
    "id": 1
}`
```

### `xvm.getBalance`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).
</Callout>

Get the balance of an asset controlled by a given address.

**Signature:**

```sh
xvm.getBalance({
    address: string,
    assetID: string
}) -> {balance: int}
```

- `address` owner of the asset
- `assetID` id of the asset for which the balance is requested

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"xvm.getBalance",
  "params" :{
      "address":"X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "299999999999900",
    "utxoIDs": [
      {
        "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo",
        "outputIndex": 1
      }
    ]
  }
}
```

### `xvm.getBlock`

Returns the block with the given id.

**Signature:**

```sh
xvm.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getBlock",
    "params": {
        "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2",
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.getBlockByHeight`

Returns block at the given height.

**Signature:**

```sh
xvm.getBlockByHeight({
    height: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockHeight` is the block height. It should be in `string` format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getBlockByHeight",
    "params": {
        "height": "275686313486",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de",
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.getHeight`

Returns the height of the last accepted block.

**Signature:**

```sh
xvm.getHeight() ->
{
    height: uint64,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "xvm.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "5094088"
  },
  "id": 1
}
```

### `xvm.getTx`

Returns the specified transaction. The `encoding` parameter sets the format of the returned
transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`.

**Signature:**

```sh
xvm.getTx({
    txID: string,
    encoding: string, //optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getTx",
    "params" :{
        "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [],
        "inputs": [
          {
            "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2570382395,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "destinationChain": "11111111111111111111111111111111LpoYY",
        "exportedOutputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-lux1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 2569382395,
              "locktime": 0,
              "threshold": 1
            }
          }
        ]
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400"
            ]
          }
        }
      ],
      "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL"
    },
    "encoding": "json"
  },
  "id": 1
}
```

Where:

- `credentials` is a list of this transaction's credentials. Each credential proves that this
  transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a
  list of signatures.
- `unsignedTx` is the non-signature portion of the transaction.
- `networkID` is the ID of the network this transaction happened on. (Lux Mainnet is `1`.)
- `blockchainID` is the ID of the blockchain this transaction happened on. (Lux Mainnet
  Exchange-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.)
- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to
  another chain.
- Each element of `inputs` is an input of this transaction which has not been imported from another
  chain.
- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the
  blockchain ID that assets are being imported from, and the inputs that are being imported.
- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify
  the blockchain ID that assets are being exported to, and the UTXOs that are being exported.

An output contains:

- `assetID`: The ID of the asset being transferred. (The Mainnet Lux ID is
  `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.)
- `fxID`: The ID of the FX this output uses.
- `output`: The FX-specific contents of this output.

Most outputs use the secp256k1 FX, look like this:

```json
{
  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
  "output": {
    "addresses": ["X-lux126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"],
    "amount": 1530084210,
    "locktime": 0,
    "threshold": 1
  }
}
```

The above output can be consumed after Unix time `locktime` by a transaction that has signatures
from `threshold` of the addresses in `addresses`.

### `xvm.getTxFee`

Get the fees of the network.

**Signature**:

```
xvm.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
}
```

- `txFee` is the default fee for making transactions.
- `createAssetTxFee` is the fee for creating a new asset.

All fees are denominated in nLUX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.getTxFee",
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000"
  }
}
```

### `xvm.getTxStatus`

<Callout type="warn">
Deprecated as of **v1.10.0**.
</Callout>

Get the status of a transaction sent to the network.

**Signature:**

```sh
xvm.getTxStatus({txID: string}) -> {status: string}
```

`status` is one of:

- `Accepted`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Rejected`: The transaction will never be accepted by any node in the network
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "Accepted"
  }
}
```

### `xvm.getUTXOs`

Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve
the atomic UTXOs exported from that chain to the X Chain.

**Signature:**

```sh
xvm.getUTXOs({
    addresses: []string,
    limit: int, //optional
    startIndex: { //optional
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string //optional
}) -> {
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :2,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"xvm.getUTXOs",
    "params" :{
        "addresses":["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-lux1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "sourceChain": "P",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819"
    ],
    "endIndex": {
      "address": "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `xvm.issueTx`

Send a signed transaction to the network. `encoding` specifies the format of the signed transaction.
Can only be `hex` when a value is provided.

**Signature:**

```sh
xvm.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"xvm.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

### `wallet.issueTx`

Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies
the format of the signed transaction. Can only be `hex` when a value is provided.

This call is made to the wallet API endpoint:

`/ext/bc/X/wallet`

:::caution
Endpoint deprecated as of [**v1.9.12**](https://github.com/luxfi/luxgo/releases/tag/v1.9.12).

:::

**Signature:**

```sh
wallet.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"wallet.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

# Transaction Format (/docs/rpcs/x-chain/txn-format)

---
title: Transaction Format
---

This file is meant to be the single source of truth for how we serialize
transactions in the Lux Virtual Machine (XVM). This document uses the
[primitive serialization](/docs/rpcs/other/standards/serialization-primitives) format for packing and
[secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) for cryptographic
user identification.

## Codec ID

Some data is prepended with a codec ID (unt16) that denotes how the data should
be deserialized. Right now, the only valid codec ID is 0 (`0x00 0x00`).

## Transferable Output

Transferable outputs wrap an output with an asset ID.

### What Transferable Output Contains

A transferable output contains an `AssetID` and an [`Output`](/docs/rpcs/x-chain/txn-format#outputs).

- **`AssetID`** is a 32-byte array that defines which asset this output references.
- **`Output`** is an output, as defined
  [below](/docs/rpcs/x-chain/txn-format#outputs). Outputs have four possible types:
  [`SECP256K1TransferOutput`](/docs/rpcs/x-chain/txn-format#secp256k1-transfer-output),
  [`SECP256K1MintOutput`](/docs/rpcs/x-chain/txn-format#secp256k1-mint-output),
  [`NFTTransferOutput`](/docs/rpcs/x-chain/txn-format#nft-transfer-output)
  and [`NFTMintOutput`](/docs/rpcs/x-chain/txn-format#nft-mint-output).

### Gantt Transferable Output Specification

```text
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| output   : Output   |      size(output) bytes |
+----------+----------+-------------------------+
                      | 32 + size(output) bytes |
                      +-------------------------+
```

### Proto Transferable Output Specification

```text
message TransferableOutput {
    bytes asset_id = 1; // 32 bytes
    Output output = 2;  // size(output)
}
```

### Transferable Output Example

Let's make a transferable output:

- `AssetID`: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `Output`: `"Example SECP256K1 Transfer Output from below"`

```text
[
    AssetID <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output  <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
]
=
[
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Transferable Input

Transferable inputs describe a specific UTXO with a provided transfer input.

### What Transferable Input Contains

A transferable input contains a `TxID`, `UTXOIndex` `AssetID` and an `Input`.

- **`TxID`** is a 32-byte array that defines which transaction this input is
  consuming an output from. Transaction IDs are calculated by taking sha256 of
  the bytes of the signed transaction.
- **`UTXOIndex`** is an int that defines which UTXO this input is consuming in the specified transaction.
- **`AssetID`** is a 32-byte array that defines which asset this input references.
- **`Input`** is an input, as defined below. This can currently only be a [SECP256K1 transfer input](/docs/rpcs/x-chain/txn-format#secp256k1-transfer-input)

### Gantt Transferable Input Specification

```text
+------------+----------+------------------------+
| tx_id      : [32]byte |               32 bytes |
+------------+----------+------------------------+
| utxo_index : int      |               04 bytes |
+------------+----------+------------------------+
| asset_id   : [32]byte |               32 bytes |
+------------+----------+------------------------+
| input      : Input    |      size(input) bytes |
+------------+----------+------------------------+
                        | 68 + size(input) bytes |
                        +------------------------+
```

### Proto Transferable Input Specification

```text
message TransferableInput {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
    bytes asset_id = 3;    // 32 bytes
    Input input = 4;       // size(input)
}
```

### Transferable Input Example

Let's make a transferable input:

- `TxID`: `0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000`
- `UTXOIndex`: `5`
- `AssetID`: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `Input`: `"Example SECP256K1 Transfer Input from below"`

```text
[
    TxID      <- 0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000
    UTXOIndex <- 0x00000005
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Input     <- 0x0000000500000000075bcd15000000020000000700000003
]
=
[
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07
]
```

## Transferable Op

Transferable operations describe a set of UTXOs with a provided transfer
operation. Only one Asset ID is able to be referenced per operation.

### What Transferable Op Contains

A transferable operation contains an `AssetID`, `UTXOIDs`, and a `TransferOp`.

- **`AssetID`** is a 32-byte array that defines which asset this operation changes.
- **`UTXOIDs`** is an array of TxID-OutputIndex tuples. This array must be
  sorted in lexicographical order.
- **`TransferOp`** is a [transferable operation object](/docs/rpcs/x-chain/txn-format#operations).

### Gantt Transferable Op Specification

```text
+-------------+------------+------------------------------+
| asset_id    : [32]byte   |                     32 bytes |
+-------------+------------+------------------------------+
| utxo_ids    : []UTXOID   | 4 + 36 * len(utxo_ids) bytes |
+-------------+------------+------------------------------+
| transfer_op : TransferOp |      size(transfer_op) bytes |
+-------------+------------+------------------------------+
                           |   36 + 36 * len(utxo_ids)    |
                           |    + size(transfer_op) bytes |
                           +------------------------------+
```

### Proto Transferable Op Specification

```text
message UTXOID {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
}
message TransferableOp {
    bytes asset_id = 1;           // 32 bytes
    repeated UTXOID utxo_ids = 2; // 4 + 36 * len(utxo_ids) bytes
    TransferOp transfer_op = 3;   // size(transfer_op)
}
```

### Transferable Op Example

Let's make a transferable operation:

- `AssetID`: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `UTXOIDs`:
  - `UTXOID`:
    - `TxID`: `0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000`
    - `UTXOIndex`: `5`
- `Op`: `"Example Transfer Op from below"`

```text
[
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    UTXOIDs   <- [
        {
            TxID:0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000
            UTXOIndex:5
        }
    ]
    Op     <- 0x0000000d0000000200000003000000070000303900000003431100000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // number of utxoIDs:
    0x00, 0x00, 0x00, 0x01,
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // op:
    0x00, 0x00, 0x00, 0x0d, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x03,
    0x43, 0x11, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00,
    0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61, 0xfb,
    0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8, 0x34,
    0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55, 0xc3,
    0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e, 0xde,
    0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89, 0x43,
    0xab, 0x08, 0x59,
]
```

## Outputs

Outputs have four possible types:
[`SECP256K1TransferOutput`](/docs/rpcs/x-chain/txn-format#secp256k1-transfer-output),
[`SECP256K1MintOutput`](/docs/rpcs/x-chain/txn-format#secp256k1-mint-output),
[`NFTTransferOutput`](/docs/rpcs/x-chain/txn-format#nft-transfer-output) and
[`NFTMintOutput`](/docs/rpcs/x-chain/txn-format#nft-mint-output).

## SECP256K1 Mint Output

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) mint output is
an output that is owned by a collection of addresses.

### What SECP256K1 Mint Output Contains

A secp256k1 Mint output contains a `TypeID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000006`.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Mint Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                       4 bytes  |
+-----------+------------+--------------------------------+
| locktime  : long       |                       8 bytes  |
+-----------+------------+--------------------------------+
| threshold : int        |                       4 bytes  |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 20 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Mint Output Specification

```text
message SECP256K1MintOutput {
    uint32 typeID = 1;            // 04 bytes
    uint64 locktime = 2;          // 08 bytes
    uint32 threshold = 3;         // 04 bytes
    repeated bytes addresses = 4; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Mint Output Example

Let's make a SECP256K1 mint output with:

- **`TypeID`**: `6`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x00000006
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x06,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## SECP256K1 Transfer Output

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) transfer output
allows for sending a quantity of an asset to a collection of addresses after a
specified Unix time.

### What SECP256K1 Transfer Output Contains

A secp256k1 transfer output contains a `TypeID`, `Amount`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000007`.
- **`Amount`** is a long that specifies the quantity of the asset that this output owns. Must be positive.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Transfer Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| amount    : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 28 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Transfer Output Specification

```text
message SECP256K1TransferOutput {
    uint32 typeID = 1;            // 04 bytes
    uint64 amount = 2;            // 08 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Transfer Output Example

Let's make a secp256k1 transfer output with:

- **`TypeID`**: `7`
- **`Amount`**: `12345`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x00000007
    Amount    <- 0x0000000000003039
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x07,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Mint Output

An NFT mint output is an NFT that is owned by a collection of addresses.

### What NFT Mint Output Contains

An NFT Mint output contains a `TypeID`, `GroupID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x0000000a`.
- **`GroupID`** is an int that specifies the group this NFT is issued to.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt NFT Mint Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| group_id  : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 24 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto NFT Mint Output Specification

```text
message NFTMintOutput {
    uint32 typeID = 1;            // 04 bytes
    uint32 group_id = 2;          // 04 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### NFT Mint Output Example

Let's make an NFT mint output with:

- **`TypeID`**: `10`
- **`GroupID`**: `12345`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x0000000a
    GroupID   <- 0x00003039
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // TypeID
    0x00, 0x00, 0x00, 0x0a,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Transfer Output

An NFT transfer output is an NFT that is owned by a collection of addresses.

### What NFT Transfer Output Contains

An NFT transfer output contains a `TypeID`, `GroupID`, `Payload`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x0000000b`.
- **`GroupID`** is an int that specifies the group this NFT was issued with.
- **`Payload`** is an arbitrary string of bytes no long longer than 1024 bytes.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt NFT Transfer Output Specification

```text
+-----------+------------+-------------------------------+
| type_id   : int        |                       4 bytes |
+-----------+------------+-------------------------------+
| group_id  : int        |                       4 bytes |
+-----------+------------+-------------------------------+
| payload   : []byte     |        4 + len(payload) bytes |
+-----------+------------+-------------------------------+
| locktime  : long       |                       8 bytes |
+-----------+------------+-------------------------------+
| threshold : int        |                       4 bytes |
+-----------+------------+-------------------------------+
| addresses : [][20]byte | 4 + 20 * len(addresses) bytes |
+-----------+------------+-------------------------------+
                         |             28 + len(payload) |
                         |  + 20 * len(addresses) bytes  |
                         +-------------------------------+
```

### Proto NFT Transfer Output Specification

```text
message NFTTransferOutput {
    uint32 typeID = 1;            // 04 bytes
    uint32 group_id = 2;          // 04 bytes
    bytes payload = 3;            // 04 bytes + len(payload)
    uint64 locktime = 4           // 08 bytes
    uint32 threshold = 5;         // 04 bytes
    repeated bytes addresses = 6; // 04 bytes + 20 bytes * len(addresses)
}
```

### NFT Transfer Output Example

Let's make an NFT transfer output with:

- **`TypeID`**: `11`
- **`GroupID`**: `12345`
- **`Payload`**: `NFT Payload`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x0000000b
    GroupID   <- 0x00003039
    Payload   <- 0x4e4654205061796c6f6164
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // TypeID:
    0x00, 0x00, 0x00, 0x0b,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // length of payload:
    0x00, 0x00, 0x00, 0x0b,
    // payload:
    0x4e, 0x46, 0x54, 0x20, 0x50, 0x61, 0x79, 0x6c,
    0x6f, 0x61, 0x64,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Inputs

Inputs have one possible type: `SECP256K1TransferInput`.

## SECP256K1 Transfer Input

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) transfer input
allows for spending an unspent secp256k1 transfer output.

### What SECP256K1 Transfer Input Contains

A secp256k1 transfer input contains an `Amount` and `AddressIndices`.

- **`TypeID`** is the ID for this input type. It is `0x00000005`.
- **`Amount`** is a long that specifies the quantity that this input should be
  consuming from the UTXO. Must be positive. Must be equal to the amount
  specified in the UTXO.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.

### Gantt SECP256K1 Transfer Input Specification

```text
+-------------------------+-------------------------------------+
| type_id         : int   |                             4 bytes |
+-----------------+-------+-------------------------------------+
| amount          : long  |                             8 bytes |
+-----------------+-------+-------------------------------------+
| address_indices : []int |  4 + 4 * len(address_indices) bytes |
+-----------------+-------+-------------------------------------+
                          | 16 + 4 * len(address_indices) bytes |
                          +-------------------------------------+
```

### Proto SECP256K1 Transfer Input Specification

```text
message SECP256K1TransferInput {
    uint32 typeID = 1;                   // 04 bytes
    uint64 amount = 2;                   // 08 bytes
    repeated uint32 address_indices = 3; // 04 bytes + 04 bytes * len(address_indices)
}
```

### SECP256K1 Transfer Input Example

Let's make a payment input with:

- **`TypeId`**: `5`
- **`Amount`**: `123456789`
- **`AddressIndices`**: \[`3`,`7`\]

```text
[
    TypeID         <- 0x00000005
    Amount         <- 123456789 = 0x00000000075bcd15,
    AddressIndices <- [0x00000003, 0x00000007]
]
=
[
    // type id:
    0x00, 0x00, 0x00, 0x05,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    // length:
    0x00, 0x00, 0x00, 0x02,
    // sig[0]
    0x00, 0x00, 0x00, 0x03,
    // sig[1]
    0x00, 0x00, 0x00, 0x07,
]
```

## Operations

Operations have three possible types: `SECP256K1MintOperation`, `NFTMintOp`, and `NFTTransferOp`.

## SECP256K1 Mint Operation

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) mint operation
consumes a SECP256K1 mint output, creates a new mint output and sends a transfer
output to a new set of owners.

### What SECP256K1 Mint Operation Contains

A secp256k1 Mint operation contains a `TypeID`, `AddressIndices`, `MintOutput`, and `TransferOutput`.

- **`TypeID`** is the ID for this output type. It is `0x00000008`.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the
  [UTXO](/docs/rpcs/x-chain/txn-format#utxo). Each UTXO has an array of
  addresses that can spend the UTXO. Each int represents the index in this
  address array that will sign this transaction. The array must be sorted low to
  high.
- **`MintOutput`** is a [SECP256K1 Mint output](/docs/rpcs/x-chain/txn-format#secp256k1-mint-output).
- **`TransferOutput`** is a [SECP256K1 Transfer output](/docs/rpcs/x-chain/txn-format#secp256k1-transfer-output).

### Gantt SECP256K1 Mint Operation Specification

```text
+----------------------------------+------------------------------------+
| type_id         : int            |                            4 bytes |
+----------------------------------+------------------------------------+
| address_indices : []int          | 4 + 4 * len(address_indices) bytes |
+----------------------------------+------------------------------------+
| mint_output     : MintOutput     |            size(mint_output) bytes |
+----------------------------------+------------------------------------+
| transfer_output : TransferOutput |        size(transfer_output) bytes |
+----------------------------------+------------------------------------+
                                   |       8 + 4 * len(address_indices) |
                                   |                + size(mint_output) |
                                   |      + size(transfer_output) bytes |
                                   +------------------------------------+
```

### Proto SECP256K1 Mint Operation Specification

```text
message SECP256K1MintOperation {
    uint32 typeID = 1;                   // 4 bytes
    repeated uint32 address_indices = 2; // 04 bytes + 04 bytes * len(address_indices)
    MintOutput mint_output = 3;          // size(mint_output
    TransferOutput transfer_output = 4;  // size(transfer_output)
}
```

### SECP256K1 Mint Operation Example

Let's make a [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) mint
operation with:

- **`TypeId`**: `8`
- **`AddressIndices`**:
- `0x00000003`
- `0x00000007`
- **`MintOutput`**: `"Example SECP256K1 Mint Output from above"`
- **`TransferOutput`**: `"Example SECP256K1 Transfer Output from above"`

```text
[
    TypeID <- 0x00000008
    AddressIndices <- [0x00000003, 0x00000007]
    MintOutput <- 0x00000006000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c89
    TransferOutput <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // typeID
    0x00, 0x00, 0x00, 0x08,
    // number of address_indices:
    0x00, 0x00, 0x00, 0x02,
    // address_indices[0]:
    0x00, 0x00, 0x00, 0x03,
    // address_indices[1]:
    0x00, 0x00, 0x00, 0x07,
    // mint output
    0x00, 0x00, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
    // transfer output
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Mint Op

An NFT mint operation consumes an NFT mint output and sends an unspent output to a new set of owners.

### What NFT Mint Op Contains

An NFT mint operation contains a `TypeID`, `AddressIndices`, `GroupID`, `Payload`, and `Output` of addresses.

- **`TypeID`** is the ID for this operation type. It is `0x0000000c`.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.
- **`GroupID`** is an int that specifies the group this NFT is issued to.
- **`Payload`** is an arbitrary string of bytes no longer than 1024 bytes.
- **`Output`** is not a `TransferableOutput`, but rather is a lock time,
  threshold, and an array of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt NFT Mint Op Specification

```text
+------------------------------+------------------------------------+
| type_id         : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| address_indices : []int      | 4 + 4 * len(address_indices) bytes |
+-----------------+------------+------------------------------------+
| group_id        : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| payload         : []byte     |             4 + len(payload) bytes |
+-----------------+------------+------------------------------------+
| outputs         : []Output   |            4 + size(outputs) bytes |
+-----------------+------------+------------------------------------+
                               |                               20 + |
                               |         4 * len(address_indices) + |
                               |                     len(payload) + |
                               |                size(outputs) bytes |
                               +------------------------------------+
```

### Proto NFT Mint Op Specification

```text
message NFTMintOp {
    uint32 typeID = 1;                   // 04 bytes
    repeated uint32 address_indices = 2; // 04 bytes + 04 bytes * len(address_indices)
    uint32 group_id = 3;                 // 04 bytes
    bytes payload = 4;                   // 04 bytes + len(payload)
    repeated bytes outputs = 5;          // 04 bytes + size(outputs)
}
```

### NFT Mint Op Example

Let's make an NFT mint operation with:

- **`TypeId`**: `12`
- **`AddressIndices`**:
  - `0x00000003`
  - `0x00000007`
- **`GroupID`**: `12345`
- **`Payload`**: `0x431100`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID         <- 0x0000000c
    AddressIndices <- [
        0x00000003,
        0x00000007,
    ]
    GroupID        <- 0x00003039
    Payload        <- 0x431100
    Locktime       <- 0x000000000000d431
    Threshold      <- 0x00000001
    Addresses      <- [
        0xc3344128e060128ede3523a24a461c8943ab0859
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x0c,
    // number of address indices:
    0x00, 0x00, 0x00, 0x02,
    // address index 0:
    0x00, 0x00, 0x00, 0x03,
    // address index 1:
    0x00, 0x00, 0x00, 0x07,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // length of payload:
    0x00, 0x00, 0x00, 0x03,
    // payload:
    0x43, 0x11, 0x00,
    // number of outputs:
    0x00, 0x00, 0x00, 0x01,
    // outputs[0]
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Transfer Op

An NFT transfer operation sends an unspent NFT transfer output to a new set of owners.

### What NFT Transfer Op Contains

An NFT transfer operation contains a `TypeID`, `AddressIndices` and an untyped `NFTTransferOutput`.

- **`TypeID`** is the ID for this output type. It is `0x0000000d`.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.
- **`NFTTransferOutput`** is the output of this operation and must be an [NFT Transfer Output](/docs/rpcs/x-chain/txn-format#nft-transfer-output). This
  output doesn't have the **`TypeId`**, because the type is known by the context
  of being in this operation.

### Gantt NFT Transfer Op Specification

```text
+------------------------------+------------------------------------+
| type_id         : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| address_indices : []int      | 4 + 4 * len(address_indices) bytes |
+-----------------+------------+------------------------------------+
| group_id        : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| payload         : []byte     |             4 + len(payload) bytes |
+-----------------+------------+------------------------------------+
| locktime        : long       |                            8 bytes |
+-----------+------------+------------------------------------------+
| threshold       : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| addresses       : [][20]byte |      4 + 20 * len(addresses) bytes |
+-----------------+------------+------------------------------------+
                               |                  36 + len(payload) |
                               |        + 4 * len(address_indices)  |
                               |        + 20 * len(addresses) bytes |
                               +------------------------------------+
```

### Proto NFT Transfer Op Specification

```text
message NFTTransferOp {
    uint32 typeID = 1;                   // 04 bytes
    repeated uint32 address_indices = 2; // 04 bytes + 04 bytes * len(address_indices)
    uint32 group_id = 3;                 // 04 bytes
    bytes payload = 4;                   // 04 bytes + len(payload)
    uint64 locktime = 5;                 // 08 bytes
    uint32 threshold = 6;                // 04 bytes
    repeated bytes addresses = 7;        // 04 bytes + 20 bytes * len(addresses)
}
```

### NFT Transfer Op Example

Let's make an NFT transfer operation with:

- **`TypeID`**: `13`
- **`AddressIndices`**:
- `0x00000007`
- `0x00000003`
- **`GroupID`**: `12345`
- **`Payload`**: `0x431100`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0xc3344128e060128ede3523a24a461c8943ab0859`
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`

```text
[
    TypeID         <- 0x0000000d
    AddressIndices <- [
        0x00000007,
        0x00000003,
    ]
    GroupID        <- 0x00003039
    Payload        <- 0x431100
    Locktime       <- 0x000000000000d431
    Threshold      <- 00000001
    Addresses      <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x0d,
    // number of address indices:
    0x00, 0x00, 0x00, 0x02,
    // address index 0:
    0x00, 0x00, 0x00, 0x07,
    // address index 1:
    0x00, 0x00, 0x00, 0x03,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // length of payload:
    0x00, 0x00, 0x00, 0x03,
    // payload:
    0x43, 0x11, 0x00,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Initial State

Initial state describes the initial state of an asset when it is created. It
contains the ID of the feature extension that the asset uses, and a variable
length array of outputs that denote the genesis UTXO set of the asset.

### What Initial State Contains

Initial state contains a `FxID` and an array of `Output`.

- **`FxID`** is an int that defines which feature extension this state is part
  of. For SECP256K1 assets, this is `0x00000000`. For NFT assets, this is
  `0x00000001`.
- **`Outputs`** is a variable length array of
  [outputs](/docs/rpcs/x-chain/txn-format#outputs), as defined above.

### Gantt Initial State Specification

```text
+---------------+----------+-------------------------------+
| fx_id         : int      |                       4 bytes |
+---------------+----------+-------------------------------+
| outputs       : []Output |       4 + size(outputs) bytes |
+---------------+----------+-------------------------------+
                           |       8 + size(outputs) bytes |
                           +-------------------------------+
```

### Proto Initial State Specification

```text
message InitialState {
    uint32 fx_id = 1;                  // 04 bytes
    repeated Output outputs = 2;       // 04 + size(outputs) bytes
}
```

### Initial State Example

Let's make an initial state:

- `FxID`: `0x00000000`
- `InitialState`: `["Example SECP256K1 Transfer Output from above"]`

```text
[
    FxID <- 0x00000000
    InitialState  <- [
        0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // fxID:
    0x00, 0x00, 0x00, 0x00,
    // num outputs:
    0x00, 0x00, 0x00, 0x01,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Credentials

Credentials have two possible types: `SECP256K1Credential`, and `NFTCredential`.
Each credential is paired with an Input or Operation. The order of the
credentials match the order of the inputs or operations.

## SECP256K1 Credential

A [secp256k1](/docs/rpcs/other/standards/cryptographic-primitives#secp256k1-addresses) credential
contains a list of 65-byte recoverable signatures.

### What SECP256K1 Credential Contains

- **`TypeID`** is the ID for this type. It is `0x00000009`.
- **`Signatures`** is an array of 65-byte recoverable signatures. The order of
  the signatures must match the input's signature indices.

### Gantt SECP256K1 Credential Specification

```text
+------------------------------+---------------------------------+
| type_id         : int        |                         4 bytes |
+-----------------+------------+---------------------------------+
| signatures      : [][65]byte |  4 + 65 * len(signatures) bytes |
+-----------------+------------+---------------------------------+
                               |  8 + 65 * len(signatures) bytes |
                               +---------------------------------+
```

### Proto SECP256K1 Credential Specification

```text
message SECP256K1Credential {
    uint32 typeID = 1;             // 4 bytes
    repeated bytes signatures = 2; // 4 bytes + 65 bytes * len(signatures)
}
```

### SECP256K1 Credential Example

Let's make a payment input with:

- **`TypeID`**: `9`
- **`signatures`**:
- `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00`
- `0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    TypeID         <- 0x00000009
    Signatures <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00,
        0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x09,
    // length:
    0x00, 0x00, 0x00, 0x02,
    // sig[0]
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00,
    // sig[1]
    0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
    0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f,
    0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57,
    0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d, 0x5f,
    0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
    0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d, 0x6f,
    0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
    0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
    0x00,
]
```

## NFT Credential

An NFT credential is the same as an [secp256k1 credential](/docs/rpcs/x-chain/txn-format#secp256k1-credential) with a
different TypeID. The TypeID for an NFT credential is `0x0000000e`.

## Unsigned Transactions

Unsigned transactions contain the full content of a transaction with only the
signatures missing. Unsigned transactions have four possible types:
[`CreateAssetTx`](/docs/rpcs/x-chain/txn-format#what-unsigned-create-asset-tx-contains),
[`OperationTx`](/docs/rpcs/x-chain/txn-format#what-unsigned-operation-tx-contains),
[`ImportTx`](/docs/rpcs/x-chain/txn-format#what-unsigned-import-tx-contains),
and
[`ExportTx`](/docs/rpcs/x-chain/txn-format#what-unsigned-export-tx-contains).
They all embed
[`BaseTx`](/docs/rpcs/x-chain/txn-format#what-base-tx-contains), which
contains common fields and operations.

## Unsigned BaseTx

### What Base TX Contains

A base TX contains a `TypeID`, `NetworkID`, `BlockchainID`, `Outputs`, `Inputs`, and `Memo`.

- **`TypeID`** is the ID for this type. It is `0x00000000`.
- **`NetworkID`** is an int that defines which network this transaction is meant
  to be issued to. This value is meant to support transaction routing and is not
  designed for replay attack prevention.
- **`BlockchainID`** is a 32-byte array that defines which blockchain this
  transaction was issued to. This is used for replay attack prevention for
  transactions that could potentially be valid across network or blockchain.
- **`Outputs`** is an array of [transferable output objects](/docs/rpcs/x-chain/txn-format#transferable-output). Outputs must
  be sorted lexicographically by their serialized representation. The total
  quantity of the assets created in these outputs must be less than or equal to
  the total quantity of each asset consumed in the inputs minus the transaction
  fee.
- **`Inputs`** is an array of [transferable input objects](/docs/rpcs/x-chain/txn-format#transferable-input). Inputs must be
  sorted and unique. Inputs are sorted first lexicographically by their
  **`TxID`** and then by the **`UTXOIndex`** from low to high. If there are
  inputs that have the same **`TxID`** and **`UTXOIndex`**, then the transaction
  is invalid as this would result in a double spend.
- **`Memo`** Memo field contains arbitrary bytes, up to 256 bytes.

### Gantt Base TX Specification

```text
+--------------------------------------+-----------------------------------------+
| type_id       : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| network_id    : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| blockchain_id : [32]byte             |                                32 bytes |
+---------------+----------------------+-----------------------------------------+
| outputs       : []TransferableOutput |                 4 + size(outputs) bytes |
+---------------+----------------------+-----------------------------------------+
| inputs        : []TransferableInput  |                  4 + size(inputs) bytes |
+---------------+----------------------+-----------------------------------------+
| memo          : [256]byte            |                    4 + size(memo) bytes |
+---------------+----------------------+-----------------------------------------+
                          | 52 + size(outputs) + size(inputs) + size(memo) bytes |
                          +------------------------------------------------------+
```

### Proto Base TX Specification

```text
message BaseTx {
    uint32 typeID = 1;           // 04 bytes
    uint32 network_id = 2;       // 04 bytes
    bytes blockchain_id = 3;     // 32 bytes
    repeated Output outputs = 4; // 04 bytes + size(outs)
    repeated Input inputs = 5;   // 04 bytes + size(ins)
    bytes memo = 6;              // 04 bytes + size(memo)
}
```

### Base TX Example

Let's make an base TX that uses the inputs and outputs from the previous examples:

- **`TypeID`**: `0`
- **`NetworkID`**: `4`
- **`BlockchainID`**: `0xffffffffeeeeeeeeddddddddcccccccbbbbbbbbaaaaaaaa9999999988888888`
- **`Outputs`**:
  - `"Example Transferable Output as defined above"`
- **`Inputs`**:
  - `"Example Transferable Input as defined above"`
- **`Memo`**: `0x00010203`

```text
[
    TypeID       <- 0x00000000
    NetworkID    <- 0x00000004
    BlockchainID <- 0xffffffffeeeeeeeeddddddddcccccccbbbbbbbbaaaaaaaa9999999988888888
    Outputs      <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
    ]
    Inputs       <- [
        0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd15000000020000000700000003
    ]
    Memo <- 0x00010203
]
=
[
    // typeID
    0x00, 0x00, 0x00, 0x00,
    // networkID:
    0x00, 0x00, 0x00, 0x04,
    // blockchainID:
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd, 0xcc, 0xcc, 0xcc, 0xcc,
    0xbb, 0xbb, 0xbb, 0xbb, 0xaa, 0xaa, 0xaa, 0xaa,
    0x99, 0x99, 0x99, 0x99, 0x88, 0x88, 0x88, 0x88,
    // number of outputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable output:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
    // number of inputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable input:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03,
    // Memo length:
    0x00, 0x00, 0x00, 0x04,
    // Memo:
    0x00, 0x01, 0x02, 0x03,
]
```

## Unsigned CreateAssetTx

### What Unsigned Create Asset TX Contains

An unsigned create asset TX contains a `BaseTx`, `Name`, `Symbol`,
`Denomination`, and `InitialStates`. The `TypeID` is `0x00000001`.

- **`BaseTx`**
- **`Name`** is a human readable string that defines the name of the asset this
  transaction will create. The name is not guaranteed to be unique. The name
  must consist of only printable ASCII characters and must be no longer than 128
  characters.
- **`Symbol`** is a human readable string that defines the symbol of the asset
  this transaction will create. The symbol is not guaranteed to be unique. The
  symbol must consist of only printable ASCII characters and must be no longer
  than 4 characters.
- **`Denomination`** is a byte that defines the divisibility of the asset this
  transaction will create. For example, the LUX token is divisible into
  billionths. Therefore, the denomination of the LUX token is 9. The
  denomination must be no more than 32.
- **`InitialStates`** is a variable length array that defines the feature
  extensions this asset supports, and the [initial state](/docs/rpcs/x-chain/txn-format#initial-state) of those feature
  extensions.

### Gantt Unsigned Create Asset TX Specification

```text
+----------------+----------------+--------------------------------------+
| base_tx        : BaseTx         |                  size(base_tx) bytes |
+----------------+----------------+--------------------------------------+
| name           : string         |                  2 + len(name) bytes |
+----------------+----------------+--------------------------------------+
| symbol         : string         |                2 + len(symbol) bytes |
+----------------+----------------+--------------------------------------+
| denomination   : byte           |                              1 bytes |
+----------------+----------------+--------------------------------------+
| initial_states : []InitialState |       4 + size(initial_states) bytes |
+----------------+----------------+--------------------------------------+
                                  | size(base_tx) + size(initial_states) |
                                  |  + 9 + len(name) + len(symbol) bytes |
                                  +--------------------------------------+
```

### Proto Unsigned Create Asset TX Specification

```text
message CreateAssetTx {
    BaseTx base_tx = 1;                       // size(base_tx)
    string name = 2;                          // 2 bytes + len(name)
    name symbol = 3;                          // 2 bytes + len(symbol)
    uint8 denomination = 4;                   // 1 bytes
    repeated InitialState initial_states = 5; // 4 bytes + size(initial_states)
}
```

### Unsigned Create Asset TX Example

Let's make an unsigned base TX that uses the inputs and outputs from the previous examples:

- `BaseTx`: `"Example BaseTx as defined above with ID set to 1"`
- `Name`: `Volatility Index`
- `Symbol`: `VIX`
- `Denomination`: `2`
- **`InitialStates`**:
- `"Example Initial State as defined above"`

```text
[
    BaseTx        <- 0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Name          <- 0x0010566f6c6174696c69747920496e646578
    Symbol        <- 0x0003564958
    Denomination  <- 0x02
    InitialStates <- [
        0x0000000000000001000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x04,
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // name:
    0x00, 0x10, 0x56, 0x6f, 0x6c, 0x61, 0x74, 0x69,
    0x6c, 0x69, 0x74, 0x79, 0x20, 0x49, 0x6e, 0x64,
    0x65, 0x78,
    // symbol length:
    0x00, 0x03,
    // symbol:
    0x56, 0x49, 0x58,
    // denomination:
    0x02,
    // number of InitialStates:
    0x00, 0x00, 0x00, 0x01,
    // InitialStates[0]:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Unsigned OperationTx

### What Unsigned Operation TX Contains

An unsigned operation TX contains a `BaseTx`, and `Ops`. The `TypeID` for this type is `0x00000002`.

- **`BaseTx`**
- **`Ops`** is a variable-length array of [Transferable Ops](/docs/rpcs/x-chain/txn-format#transferable-op).

### Gantt Unsigned Operation TX Specification

```text
+---------+------------------+-------------------------------------+
| base_tx : BaseTx           |                 size(base_tx) bytes |
+---------+------------------+-------------------------------------+
| ops     : []TransferableOp |                 4 + size(ops) bytes |
+---------+------------------+-------------------------------------+
                             | 4 + size(ops) + size(base_tx) bytes |
                             +-------------------------------------+
```

### Proto Unsigned Operation TX Specification

```text
message OperationTx {
    BaseTx base_tx = 1;          // size(base_tx)
    repeated TransferOp ops = 2; // 4 bytes + size(ops)
}
```

### Unsigned Operation TX Example

Let's make an unsigned operation TX that uses the inputs and outputs from the previous examples:

- `BaseTx`: `"Example BaseTx above" with TypeID set to 2`
- **`Ops`**: \[`"Example Transferable Op as defined above"`\]

```text
[
    BaseTx <- 0x0000000200000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Ops <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f00000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000000000050000000d0000000200000003000000070000303900000003431100000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // number of operations:
    0x00, 0x00, 0x00, 0x01,
    // transfer operation:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x01, 0xf1, 0xe1, 0xd1, 0xc1,
    0xb1, 0xa1, 0x91, 0x81, 0x71, 0x61, 0x51, 0x41,
    0x31, 0x21, 0x11, 0x01, 0xf0, 0xe0, 0xd0, 0xc0,
    0xb0, 0xa0, 0x90, 0x80, 0x70, 0x60, 0x50, 0x40,
    0x30, 0x20, 0x10, 0x00, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x0d, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x03,
    0x43, 0x11, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00,
    0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61, 0xfb,
    0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8, 0x34,
    0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55, 0xc3,
    0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e, 0xde,
    0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89, 0x43,
    0xab, 0x08, 0x59,
]
```

## Unsigned ImportTx

### What Unsigned Import TX Contains

An unsigned import TX contains a `BaseTx`, `SourceChain` and `Ins`. \* The `TypeID`for this type is `0x00000003`.

- **`BaseTx`**
- **`SourceChain`** is a 32-byte source blockchain ID.
- **`Ins`** is a variable length array of [Transferable Inputs](/docs/rpcs/x-chain/txn-format#transferable-input).

### Gantt Unsigned Import TX Specification

```text
+---------+----------------------+-----------------------------+
| base_tx : BaseTx               |         size(base_tx) bytes |
+-----------------+--------------+-----------------------------+
| source_chain    : [32]byte     |                    32 bytes |
+---------+----------------------+-----------------------------+
| ins     : []TransferIn         |         4 + size(ins) bytes |
+---------+----------------------+-----------------------------+
                        | 36 + size(ins) + size(base_tx) bytes |
                        +--------------------------------------+
```

### Proto Unsigned Import TX Specification

```text
message ImportTx {
    BaseTx base_tx = 1;          // size(base_tx)
    bytes source_chain = 2;      // 32 bytes
    repeated TransferIn ins = 3; // 4 bytes + size(ins)
}
```

### Unsigned Import TX Example

Let's make an unsigned import TX that uses the inputs from the previous examples:

- `BaseTx`: `"Example BaseTx as defined above"`, but with `TypeID` set to `3`
- `SourceChain`: `0x0000000000000000000000000000000000000000000000000000000000000000`
- `Ins`: `"Example SECP256K1 Transfer Input as defined above"`

```text
[
    BaseTx        <- 0x0000000300000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    SourceChain <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Ins <- [
        f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd15000000020000000300000007,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x03,
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // source chain:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // input count:
    0x00, 0x00, 0x00, 0x01,
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
]
```

## Unsigned ExportTx

### What Unsigned Export TX Contains

An unsigned export TX contains a `BaseTx`, `DestinationChain`, and `Outs`. The
`TypeID` for this type is `0x00000004`.

- **`DestinationChain`** is the 32 byte ID of the chain where the funds are being exported to.
- **`Outs`** is a variable length array of [Transferable Outputs](/docs/rpcs/x-chain/txn-format#transferable-output).

### Gantt Unsigned Export TX Specification

```text
+-------------------+---------------+--------------------------------------+
| base_tx           : BaseTx        |                  size(base_tx) bytes |
+-------------------+---------------+--------------------------------------+
| destination_chain : [32]byte      |                             32 bytes |
+-------------------+---------------+--------------------------------------+
| outs              : []TransferOut |                 4 + size(outs) bytes |
+-------------------+---------------+--------------------------------------+
                          | 36 + size(outs) + size(base_tx) bytes |
                          +---------------------------------------+
```

### Proto Unsigned Export TX Specification

```text
message ExportTx {
    BaseTx base_tx = 1;            // size(base_tx)
    bytes destination_chain = 2;   // 32 bytes
    repeated TransferOut outs = 3; // 4 bytes + size(outs)
}
```

### Unsigned Export TX Example

Let's make an unsigned export TX that uses the outputs from the previous examples:

- `BaseTx`: `"Example BaseTx as defined above"`, but with `TypeID` set to `4`
- `DestinationChain`: `0x0000000000000000000000000000000000000000000000000000000000000000`
- `Outs`: `"Example SECP256K1 Transfer Output as defined above"`

```text
[
    BaseTx           <- 0x0000000400000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    DestinationChain <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Outs <- [
        000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x04
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // destination_chain:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // outs[] count:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
]
```

## Signed Transaction

A signed transaction is an unsigned transaction with the addition of an array of [credentials](/docs/rpcs/x-chain/txn-format#credentials).

### What Signed Transaction Contains

A signed transaction contains a `CodecID`, `UnsignedTx`, and `Credentials`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`UnsignedTx`** is an unsigned transaction, as described above.
- **`Credentials`** is an array of
  [credentials](/docs/rpcs/x-chain/txn-format#credentials). Each credential
  will be paired with the input in the same index at this credential.

### Gantt Signed Transaction Specification

```text
+---------------------+--------------+------------------------------------------------+
| codec_id            : uint16       |                                        2 bytes |
+---------------------+--------------+------------------------------------------------+
| unsigned_tx         : UnsignedTx   |                        size(unsigned_tx) bytes |
+---------------------+--------------+------------------------------------------------+
| credentials         : []Credential |                    4 + size(credentials) bytes |
+---------------------+--------------+------------------------------------------------+
                                     | 6 + size(unsigned_tx) + len(credentials) bytes |
                                     +------------------------------------------------+
```

### Proto Signed Transaction Specification

```text
message Tx {
    uint16 codec_id = 1;                 // 2 bytes
    UnsignedTx unsigned_tx = 2;          // size(unsigned_tx)
    repeated Credential credentials = 3; // 4 bytes + size(credentials)
}
```

### Signed Transaction Example

Let's make a signed transaction that uses the unsigned transaction and
credentials from the previous examples.

- **`CodecID`**: `0`
- **`UnsignedTx`**: `0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203`
- **`Credentials`** `0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    CodecID     <- 0x0000
    UnsignedTx  <- 0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Credentials <- [
        0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Codec ID
    0x00, 0x00,
    // unsigned transaction:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x04,
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd, 0xcc, 0xcc, 0xcc, 0xcc,
    0xbb, 0xbb, 0xbb, 0xbb, 0xaa, 0xaa, 0xaa, 0xaa,
    0x99, 0x99, 0x99, 0x99, 0x88, 0x88, 0x88, 0x88,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
    0x00, 0x00, 0x00, 0x01, 0xf1, 0xe1, 0xd1, 0xc1,
    0xb1, 0xa1, 0x91, 0x81, 0x71, 0x61, 0x51, 0x41,
    0x31, 0x21, 0x11, 0x01, 0xf0, 0xe0, 0xd0, 0xc0,
    0xb0, 0xa0, 0x90, 0x80, 0x70, 0x60, 0x50, 0x40,
    0x30, 0x20, 0x10, 0x00, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x03,
    0x00, 0x00, 0x00, 0x04, 0x00, 0x01, 0x02, 0x03
    // number of credentials:
    0x00, 0x00, 0x00, 0x01,
    // credential[0]:
    0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46,
    0x47, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e,
    0x4f, 0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56,
    0x57, 0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d,
    0x5f, 0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
    0x67, 0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d,
    0x6f, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76,
    0x77, 0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e,
    0x7f, 0x00,
```

## UTXO

A UTXO is a standalone representation of a transaction output.

### What UTXO Contains

A UTXO contains a `CodecID`, `TxID`, `UTXOIndex`, `AssetID`, and `Output`.

- **`CodecID`** The only valid `CodecID` is `00 00`
- **`TxID`** is a 32-byte transaction ID. Transaction IDs are calculated by
  taking sha256 of the bytes of the signed transaction.
- **`UTXOIndex`** is an int that specifies which output in the transaction
  specified by **`TxID`** that this UTXO was created by.
- **`AssetID`** is a 32-byte array that defines which asset this UTXO
  references.
- **`Output`** is the output object that created this UTXO. The serialization of
  Outputs was defined above. Valid output types are [SECP Mint Output](/docs/rpcs/x-chain/txn-format#secp256k1-mint-output), [SECP Transfer Output](/docs/rpcs/x-chain/txn-format#secp256k1-transfer-output),
  [NFT Mint Output](/docs/rpcs/x-chain/txn-format#nft-mint-output), [NFT Transfer Output](/docs/rpcs/x-chain/txn-format#nft-transfer-output).

### Gantt UTXO Specification

```text
+--------------+----------+-------------------------+
| codec_id     : uint16   |                 2 bytes |
+--------------+----------+-------------------------+
| tx_id        : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output_index : int      |                 4 bytes |
+--------------+----------+-------------------------+
| asset_id     : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output       : Output   |      size(output) bytes |
+--------------+----------+-------------------------+
                          | 70 + size(output) bytes |
                          +-------------------------+
```

### Proto UTXO Specification

```text
message Utxo {
    uint16 codec_id = 1;     // 02 bytes
    bytes tx_id = 2;         // 32 bytes
    uint32 output_index = 3; // 04 bytes
    bytes asset_id = 4;      // 32 bytes
    Output output = 5;       // size(output)
}
```

### UTXO Examples

Let's make a UTXO with a SECP Mint Output:

- **`CodecID`**: `0`
- **`TxID`**: `0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f`
- **`UTXOIndex`**: `0` = `0x00000001`
- **`AssetID`**: `0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f`
- **`Output`**: `0x00000006000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f
    UTXOIndex <- 0x00000001
    AssetID   <- 0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f
    Output    <- 00000006000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0x47, 0xc9, 0x2e, 0xd6, 0x2d, 0x18, 0xe3, 0xcc,
    0xcd, 0xa5, 0x12, 0xf6, 0x0a, 0x0d, 0x5b, 0x1e,
    0x93, 0x9b, 0x6a, 0xb7, 0x3f, 0xb2, 0xd0, 0x11,
    0xe5, 0xe3, 0x06, 0xe7, 0x9b, 0xd0, 0x44, 0x8f,
    // utxo index:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x47, 0xc9, 0x2e, 0xd6, 0x2d, 0x18, 0xe3, 0xcc,
    0xcd, 0xa5, 0x12, 0xf6, 0x0a, 0x0d, 0x5b, 0x1e,
    0x93, 0x9b, 0x6a, 0xb7, 0x3f, 0xb2, 0xd0, 0x11,
    0xe5, 0xe3, 0x06, 0xe7, 0x9b, 0xd0, 0x44, 0x8f,
    // secp mint output:
    0x00, 0x00, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
    0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
    0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
    0x62, 0x76, 0xaa, 0x2a,
]
```

Let's make a UTXO with a SECP Transfer Output from the signed transaction created above:

- **`CodecID`**: `0`
- **`TxID`**: `0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7`
- **`UTXOIndex`**: `0` = `0x00000000`
- **`AssetID`**: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- **`Output`**: `"Example SECP256K1 Transferable Output as defined above"`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7
    UTXOIndex <- 0x00000000
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output    <-     0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0xf9, 0x66, 0x75, 0x0f, 0x43, 0x88, 0x67, 0xc3,
    0xc9, 0x82, 0x8d, 0xdc, 0xdb, 0xe6, 0x60, 0xe2,
    0x1c, 0xcd, 0xbb, 0x36, 0xa9, 0x27, 0x69, 0x58,
    0xf0, 0x11, 0xba, 0x47, 0x2f, 0x75, 0xd4, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x00,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // secp transfer output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21, 0x22, 0x23,
    0x24, 0x25, 0x26, 0x27,
]
```

Let's make a UTXO with an NFT Mint Output:

- **`CodecID`**: `0`
- **`TxID`**: `0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7`
- **`UTXOIndex`**: `0` = `0x00000001`
- **`AssetID`**: `0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7`
- **`Output`**: `0x0000000a00000000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7
    UTXOIndex <- 0x00000001
    AssetID   <- 0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7
    Output    <- 0000000a00000000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0x03, 0xc6, 0x86, 0xef, 0xe8, 0xd8, 0x0c, 0x51,
    0x9f, 0x35, 0x69, 0x29, 0xf6, 0xda, 0x94, 0x5f,
    0x7f, 0xf9, 0x03, 0x78, 0xf0, 0x04, 0x4b, 0xb0,
    0xe1, 0xa5, 0xd6, 0xc1, 0xad, 0x06, 0xba, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x03, 0xc6, 0x86, 0xef, 0xe8, 0xd8, 0x0c, 0x51,
    0x9f, 0x35, 0x69, 0x29, 0xf6, 0xda, 0x94, 0x5f,
    0x7f, 0xf9, 0x03, 0x78, 0xf0, 0x04, 0x4b, 0xb0,
    0xe1, 0xa5, 0xd6, 0xc1, 0xad, 0x06, 0xba, 0xe7,
    // nft mint output:
    0x00, 0x00, 0x00, 0x0a, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
    0x3c, 0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a,
    0x0e, 0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68,
    0x61, 0xe1, 0xb2, 0x9c, 0x62, 0x76, 0xaa, 0x2a,
]
```

Let's make a UTXO with an NFT Transfer Output:

- **`CodecID`**: `0`
- **`TxID`**: `0xa68f794a7de7bdfc5db7ba5b73654304731dd586bbf4a6d7b05be6e49de2f936`
- **`UTXOIndex`**: `0` = `0x00000001`
- **`AssetID`**: `0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7`
- **`Output`**: `0x0000000b000000000000000b4e4654205061796c6f6164000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xa68f794a7de7bdfc5db7ba5b73654304731dd586bbf4a6d7b05be6e49de2f936
    UTXOIndex <- 0x00000001
    AssetID   <- 0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7
    Output    <- 0000000b000000000000000b4e4654205061796c6f6164000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0xa6, 0x8f, 0x79, 0x4a, 0x7d, 0xe7, 0xbd, 0xfc,
    0x5d, 0xb7, 0xba, 0x5b, 0x73, 0x65, 0x43, 0x04,
    0x73, 0x1d, 0xd5, 0x86, 0xbb, 0xf4, 0xa6, 0xd7,
    0xb0, 0x5b, 0xe6, 0xe4, 0x9d, 0xe2, 0xf9, 0x36,
    // utxo index:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x03, 0xc6, 0x86, 0xef, 0xe8, 0xd8, 0x0c, 0x51,
    0x9f, 0x35, 0x69, 0x29, 0xf6, 0xda, 0x94, 0x5f,
    0x7f, 0xf9, 0x03, 0x78, 0xf0, 0x04, 0x4b, 0xb0,
    0xe1, 0xa5, 0xd6, 0xc1, 0xad, 0x06, 0xba, 0xe7,
    // nft transfer output:
    0x00, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x0b, 0x4e, 0x46, 0x54, 0x20,
    0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, 0x64, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x3c,
    0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a, 0x0e,
    0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68, 0x61,
    0xe1, 0xb2, 0x9c, 0x62, 0x76, 0xaa, 0x2a,
]
```

## GenesisAsset

An asset to be issued in an instance of the XVM's Genesis

### What GenesisAsset Contains

An instance of a GenesisAsset contains an `Alias`, `NetworkID`, `BlockchainID`,
`Outputs`, `Inputs`, `Memo`, `Name`, `Symbol`, `Denomination`, and
`InitialStates`.

- **`Alias`** is the alias for this asset.
- **`NetworkID`** defines which network this transaction is meant to be issued
  to. This value is meant to support transaction routing and is not designed for
  replay attack prevention.
- **`BlockchainID`** is the ID (32-byte array) that defines which blockchain
  this transaction was issued to. This is used for replay attack prevention for
  transactions that could potentially be valid across network or blockchain.
- **`Outputs`** is an array of [transferable output objects](/docs/rpcs/x-chain/txn-format#transferable-output). Outputs must
  be sorted lexicographically by their serialized representation. The total
  quantity of the assets created in these outputs must be less than or equal to
  the total quantity of each asset consumed in the inputs minus the transaction
  fee.
- **`Inputs`** is an array of [transferable input objects](/docs/rpcs/x-chain/txn-format#transferable-input). Inputs must be
  sorted and unique. Inputs are sorted first lexicographically by their
  **`TxID`** and then by the **`UTXOIndex`** from low to high. If there are
  inputs that have the same **`TxID`** and **`UTXOIndex`**, then the transaction
  is invalid as this would result in a double spend.
- **`Memo`** is a memo field that contains arbitrary bytes, up to 256 bytes.
- **`Name`** is a human readable string that defines the name of the asset this
  transaction will create. The name is not guaranteed to be unique. The name
  must consist of only printable ASCII characters and must be no longer than 128
  characters.
- **`Symbol`** is a human readable string that defines the symbol of the asset
  this transaction will create. The symbol is not guaranteed to be unique. The
  symbol must consist of only printable ASCII characters and must be no longer
  than 4 characters.
- **`Denomination`** is a byte that defines the divisibility of the asset this
  transaction will create. For example, the LUX token is divisible into
  billionths. Therefore, the denomination of the LUX token is 9. The
  denomination must be no more than 32.
- **`InitialStates`** is a variable length array that defines the feature
  extensions this asset supports, and the [initial state](/docs/rpcs/x-chain/txn-format#initial-state) of those feature
  extensions.

### Gantt GenesisAsset Specification

````text
+----------------+----------------------+--------------------------------+
| alias          : string               |           2 + len(alias) bytes |
+----------------+----------------------+--------------------------------+
| network_id     : int                  |                        4 bytes |
+----------------+----------------------+--------------------------------+
| blockchain_id  : [32]byte             |                       32 bytes |
+----------------+----------------------+--------------------------------+
| outputs        : []TransferableOutput |        4 + size(outputs) bytes |
+----------------+----------------------+--------------------------------+
| inputs         : []TransferableInput  |         4 + size(inputs) bytes |
+----------------+----------------------+--------------------------------+
| memo           : [256]byte            |           4 + size(memo) bytes |
+----------------+----------------------+--------------------------------+
| name           : string               |            2 + len(name) bytes |
+----------------+----------------------+--------------------------------+
| symbol         : string               |          2 + len(symbol) bytes |
+----------------+----------------------+--------------------------------+
| denomination   : byte                 |                        1 bytes |
+----------------+----------------------+--------------------------------+
| initial_states : []InitialState       | 4 + size(initial_states) bytes |
+----------------+----------------------+--------------------------------+
|           59 + size(alias) + size(outputs) + size(inputs) + size(memo) |
|                 + len(name) + len(symbol) + size(initial_states) bytes |
+------------------------------------------------------------------------+

### Proto GenesisAsset Specification

```text
message GenesisAsset {
    string alias = 1;                          // 2 bytes + len(alias)
    uint32 network_id = 2;                     // 04 bytes
    bytes blockchain_id = 3;                   // 32 bytes
    repeated Output outputs = 4;               // 04 bytes + size(outputs)
    repeated Input inputs = 5;                 // 04 bytes + size(inputs)
    bytes memo = 6;                            // 04 bytes + size(memo)
    string name = 7;                           // 2 bytes + len(name)
    name symbol = 8;                           // 2 bytes + len(symbol)
    uint8 denomination = 9;                    // 1 bytes
    repeated InitialState initial_states = 10; // 4 bytes + size(initial_states)
}
````

### GenesisAsset Example

Let's make a GenesisAsset:

- **`Alias`**: `asset1`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x0000000000000000000000000000000000000000000000000000000000000000`
- **`Outputs`**: \[\]
- **`Inputs`**: \[\]
- **`Memo`**: `2Zc54v4ek37TEwu4LiV3j41PUMRd6acDDU3ZCVSxE7X`
- **`Name`**: `asset1`
- **`Symbol`**: `MFCA`
- **`Denomination`**: `1`
- **`InitialStates`**:
- `"Example Initial State as defined above"`

```text
[
    Alias         <- 0x617373657431
    NetworkID     <- 0x00003039
    BlockchainID  <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Outputs       <- []
    Inputs        <- []
    Memo          <- 0x66x726f6d20736e6f77666c616b6520746f206176616c616e636865
    Name          <- 0x617373657431
    Symbol        <- 0x66x726f6d20736e6f77666c616b6520746f206176616c616e636865
    Denomination  <- 0x66x726f6d20736e6f77666c616b6520746f206176616c616e636865
    InitialStates <- [
        0x0000000000000001000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
    ]
]
=
[
    // asset alias len:
    0x00, 0x06,
    // asset alias:
    0x61, 0x73, 0x73, 0x65, 0x74, 0x31,
    // network_id:
    0x00, 0x00, 0x30, 0x39,
    // blockchain_id:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // output_len:
    0x00, 0x00, 0x00, 0x00,
    // input_len:
    0x00, 0x00, 0x00, 0x00,
    // memo_len:
    0x00, 0x00, 0x00, 0x1b,
    // memo:
    0x66, 0x72, 0x6f, 0x6d, 0x20, 0x73, 0x6e, 0x6f, 0x77, 0x66, 0x6c, 0x61,
    0x6b, 0x65, 0x20, 0x74, 0x6f, 0x20, 0x61, 0x76, 0x61, 0x6c, 0x61, 0x6e, 0x63, 0x68, 0x65,
    // asset_name_len:
    0x00, 0x0f,
    // asset_name:
    0x6d, 0x79, 0x46, 0x69, 0x78, 0x65, 0x64, 0x43, 0x61, 0x70, 0x41, 0x73, 0x73, 0x65, 0x74,
    // symbol_len:
    0x00, 0x04,
    // symbol:
    0x4d, 0x46, 0x43, 0x41,
    // denomination:
    0x07,
    // number of InitialStates:
    0x00, 0x00, 0x00, 0x01,
    // InitialStates[0]:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```



# CLI Commands (/docs/tooling/avalanche-cli/cli-commands)

---
title: "CLI Commands"
description: "Complete list of Lux CLI commands and their usage."
edit_url: https://github.com/luxfi/lux-cli/edit/main/cmd/commands.md
---

<a id="lux-blockchain"></a>
## lux blockchain

The blockchain command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the blockchain create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the blockchain deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

**Usage:**
```bash
lux blockchain [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#lux-blockchain-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the Platform-Chain.

This command currently only works on Blockchains deployed to either the Testnet
Testnet or Mainnet.
- [`changeOwner`](#lux-blockchain-changeowner): The blockchain changeOwner changes the owner of the deployed Blockchain.
- [`changeWeight`](#lux-blockchain-changeweight): The blockchain changeWeight command changes the weight of a L1 Validator.

The L1 has to be a Proof of Authority L1.
- [`configure`](#lux-blockchain-configure): LuxGo nodes support several different configuration files.
Each network (a Subnet or an L1) has their own config which applies to all blockchains/VMs in the network (see https://build.lux.network/docs/nodes/configure/lux-l1-configs)
Each blockchain within the network can have its own chain config (see https://build.lux.network/docs/nodes/chain-configs/primary-network/c-chain https://github.com/luxfi/subnet-evm/blob/master/plugin/evm/config/config.go for subnet-evm options).
A chain can also have special requirements for the LuxGo node configuration itself (see https://build.lux.network/docs/nodes/configure/configs-flags).
This command allows you to set all those files.
- [`create`](#lux-blockchain-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#lux-blockchain-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#lux-blockchain-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Testnet Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Lux-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Testnet, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
lux network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Blockchain and deploy it on Testnet or Mainnet.
- [`describe`](#lux-blockchain-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#lux-blockchain-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#lux-blockchain-import): Import blockchain configurations into lux-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#lux-blockchain-join): The blockchain join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Blockchain's admins must add
the NodeID of your validator to the Blockchain's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --luxgo-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Testnet Testnet and Mainnet.
- [`list`](#lux-blockchain-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#lux-blockchain-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#lux-blockchain-removevalidator): The blockchain removeValidator command stops a whitelisted blockchain network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#lux-blockchain-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#lux-blockchain-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#lux-blockchain-validators): The blockchain validators command lists the validators of a blockchain and provides
several statistics about them.
- [`vmid`](#lux-blockchain-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help             help for blockchain
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the Platform-Chain.

This command currently only works on Blockchains deployed to either the Testnet
Testnet or Mainnet.

**Usage:**
```bash
lux blockchain addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers        allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings    endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string           log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout              use stdout for signature aggregator logs
--balance float                         set the LUX balance of the validator that will be used for continuous fee on Platform-Chain
--blockchain-genesis-key                use genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                 CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string         private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string        set the BLS proof of possession of the validator to add
--bls-public-key string                 set the BLS public key of the validator to add
--cluster string                        operate on the given cluster
--create-local-validator                create additional local validator and add it to existing running local node
--default-duration                      (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                    (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for testnet & mainnet, 30 seconds later for devnet)
--default-validator-params              (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                 (PoS only) delegation fee (in bips) (default 100)
--devnet                                operate on a devnet network
--disable-owner string                  Platform-Chain address that will able to disable the validator with a Platform-Chain transaction
--endpoint string                       use the given endpoint for network operations
-e, --ewoq                              use ewoq key [testnet/devnet only]
-f, --testnet                              testnet                         operate on testnet (alias to testnet
-h, --help                              help for addValidator
-k, --key string                        select the key to use [testnet/devnet only]
-g, --ledger                            use ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings                  use the given ledger addresses
-l, --local                             operate on a local network
-m, --mainnet                           operate on mainnet
--node-endpoint string                  gather node id/bls from publicly available luxgo apis on the given endpoint
--node-id string                        node-id of the validator to add
--output-tx-path string                 (for Subnets, not L1s) file path of the add validator tx
--partial-sync                          set primary network partial sync for new validators (default true)
--remaining-balance-owner string        Platform-Chain address that will receive any leftover LUX from the validator when it is removed from Subnet
--rpc string                            connect to validator manager at the given rpc endpoint
--stake-amount uint                     (PoS only) amount of tokens to stake
--staking-period duration               how long this validator will be staking
--start-time string                     (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings              (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet                           testnet                         operate on testnet (alias to testnet)
--wait-for-tx-acceptance                (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                           set the staking weight of the validator to add (default 20)
--config string                         config file (default is $HOME/.lux-cli/config.json)
--log-level string                      log level for the application (default "ERROR")
--skip-update-check                     skip check for new versions
```

<a id="lux-blockchain-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the deployed Blockchain.

**Usage:**
```bash
lux blockchain changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--auth-keys strings        control keys that will be used to authenticate transfer blockchain ownership tx
--cluster string           operate on the given cluster
--control-keys strings     addresses that may make blockchain changes
--devnet                   operate on a devnet network
--endpoint string          use the given endpoint for network operations
-e, --ewoq                 use ewoq key [testnet/devnet]
-f, --testnet                 testnet            operate on testnet (alias to testnet
-h, --help                 help for changeOwner
-k, --key string           select the key to use [testnet/devnet]
-g, --ledger               use ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings     use the given ledger addresses
-l, --local                operate on a local network
-m, --mainnet              operate on mainnet
--output-tx-path string    file path of the transfer blockchain ownership tx
-s, --same-control-key     use the fee-paying key as control key
-t, --testnet              testnet            operate on testnet (alias to testnet)
--threshold uint32         required number of control key signatures to make blockchain changes
--config string            config file (default is $HOME/.lux-cli/config.json)
--log-level string         log level for the application (default "ERROR")
--skip-update-check        skip check for new versions
```

<a id="lux-blockchain-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a L1 Validator.

The L1 has to be a Proof of Authority L1.

**Usage:**
```bash
lux blockchain changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-e, --ewoq                use ewoq key [testnet/devnet only]
-f, --testnet                testnet           operate on testnet (alias to testnet
-h, --help                help for changeWeight
-k, --key string          select the key to use [testnet/devnet only]
-g, --ledger              use ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings    use the given ledger addresses
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-endpoint string    gather node id/bls from publicly available luxgo apis on the given endpoint
--node-id string          node-id of the validator
-t, --testnet             testnet           operate on testnet (alias to testnet)
--weight uint             set the new staking weight of the validator
--config string           config file (default is $HOME/.lux-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="lux-blockchain-configure"></a>
### configure

LuxGo nodes support several different configuration files.
Each network (a Subnet or an L1) has their own config which applies to all blockchains/VMs in the network (see https://build.lux.network/docs/nodes/configure/lux-l1-configs)
Each blockchain within the network can have its own chain config (see https://build.lux.network/docs/nodes/chain-configs/primary-network/c-chain https://github.com/luxfi/subnet-evm/blob/master/plugin/evm/config/config.go for subnet-evm options).
A chain can also have special requirements for the LuxGo node configuration itself (see https://build.lux.network/docs/nodes/configure/configs-flags).
This command allows you to set all those files.

**Usage:**
```bash
lux blockchain configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help                        help for configure
--node-config string              path to luxgo node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.lux-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check               skip check for new versions
```

<a id="lux-blockchain-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
lux blockchain create [subcommand] [flags]
```

**Flags:**

```bash
--custom                            use a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug                             enable blockchain debugging (default true)
--evm                               use the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults                      deprecation notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token                use a gas token from another blockchain
-f, --force                         overwrite the existing configuration if one exists
--from-github-repo                  generate custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help                          help for create
--icm                               interoperate with other blockchains using ICM
--icm-registry-at-genesis           setup ICM registry smart contract on genesis [experimental]
--latest                            use latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release                       use latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults               use default production settings for your blockchain
--proof-of-authority                use proof of authority(PoA) for validator management
--proof-of-stake                    use proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign                         set to false if creating non-sovereign blockchain (default true)
--teleporter                        interoperate with other blockchains using ICM
--test-defaults                     use default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp                              generate a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check                 skip check for new versions
```

<a id="lux-blockchain-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
lux blockchain delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for delete
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration to Local Network, to Testnet Testnet, DevNet or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the L1 / Subnet.

When deploying an L1, Lux-CLI lets you use your local machine as a bootstrap validator, so you don't need to run separate Lux nodes.
This is controlled by the --use-local-machine flag (enabled by default on Local Network).

If --use-local-machine is set to true:
- Lux-CLI will call CreateSubnetTx, CreateChainTx, ConvertSubnetToL1Tx, followed by syncing the local machine bootstrap validator to the L1 and initialize
  Validator Manager Contract on the L1

If using your own Lux Nodes as bootstrap validators:
- Lux-CLI will call CreateSubnetTx, CreateChainTx, ConvertSubnetToL1Tx
- You will have to sync your bootstrap validators to the L1
- Next, Initialize Validator Manager contract on the L1 using lux contract initValidatorManager [L1_Name]

Lux-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (Local Network, Testnet, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
lux network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Blockchain and deploy it on Testnet or Mainnet.

**Usage:**
```bash
lux blockchain deploy [subcommand] [flags]
```

**Flags:**

```bash
 --convert-only              avoid node track, restart and poa manager setup
  -e, --ewoq                      use ewoq key [local/devnet deploy only]
  -h, --help                      help for deploy
  -k, --key string                select the key to use [testnet/devnet deploy only]
  -g, --ledger                    use ledger instead of key
      --ledger-addrs strings      use the given ledger addresses
      --mainnet-chain-id uint32   use different ChainID for mainnet deployment
      --output-tx-path string     file path of the blockchain creation tx (for multi-sig signing)
  -u, --subnet-id string          do not create a subnet, deploy the blockchain into the given subnet id
      --subnet-only               command stops after CreateSubnetTx and returns SubnetID

Network Flags (Select One):
  --cluster string   operate on the given cluster
  --devnet           operate on a devnet network
  --endpoint string  use the given endpoint for network operations
  --testnet             operate on testnet (alias to `testnet`)
  --local            operate on a local network
  --mainnet          operate on mainnet
  --testnet          operate on testnet (alias to `testnet`)

Bootstrap Validators Flags:
  --balance float64                  set the LUX balance of each bootstrap validator that will be used for continuous fee on Platform-Chain (setting balance=1 equals to 1 LUX for each bootstrap validator)
  --bootstrap-endpoints stringSlice  take validator node info from the given endpoints
  --bootstrap-filepath string        JSON file path that provides details about bootstrap validators
  --change-owner-address string      address that will receive change if node is no longer L1 validator
  --generate-node-id                 set to true to generate Node IDs for bootstrap validators when none are set up. Use these Node IDs to set up your Lux Nodes.
  --num-bootstrap-validators int     number of bootstrap validators to set up in sovereign L1 validator)

Local Machine Flags (Use Local Machine as Bootstrap Validator):
  --luxgo-path string              use this luxgo binary path
  --luxgo-version string           use this version of luxgo (ex: v1.17.12)
  --http-port uintSlice                  http port for node(s)
  --partial-sync                         set primary network partial sync for new validators
  --staking-cert-key-path stringSlice    path to provided staking cert key for node(s)
  --staking-port uintSlice               staking port for node(s)
  --staking-signer-key-path stringSlice  path to provided staking signer key for node(s)
  --staking-tls-key-path stringSlice     path to provided staking TLS key for node(s)
  --use-local-machine                    use local machine as a blockchain validator

Local Network Flags:
  --luxgo-path string     use this luxgo binary path
  --luxgo-version string  use this version of luxgo (ex: v1.17.12)
  --num-nodes uint32            number of nodes to be created on local network deploy

Non Subnet-Only-Validators (Non-SOV) Flags:
  --auth-keys stringSlice     control keys that will be used to authenticate chain creation
  --control-keys stringSlice  addresses that may make blockchain changes
  --same-control-key          use the fee-paying key as control key
  --threshold uint32          required number of control key signatures to make blockchain changes

ICM Flags:
  --cchain-funding-key string                          key to be used to fund relayer account on cchain
  --cchain-icm-key string                              key to be used to pay for ICM deploys on LUExchange-Chain
  --icm-key string                                     key to be used to pay for ICM deploys
  --icm-version string                                 ICM version to deploy
  --relay-cchain                                       relay LUExchange-Chain as source and destination
  --relayer-allow-private-ips                          allow relayer to connec to private ips
  --relayer-amount float64                             automatically fund relayer fee payments with the given amount
  --relayer-key string                                 key to be used by default both for rewards and to pay fees
  --relayer-log-level string                           log level to be used for relayer logs
  --relayer-path string                                relayer binary to use
  --relayer-version string                             relayer version to deploy
  --skip-icm-deploy                                    Skip automatic ICM deploy
  --skip-relayer                                       skip relayer deploy
  --teleporter-messenger-contract-address-path string  path to an ICM Messenger contract address file
  --teleporter-messenger-deployer-address-path string  path to an ICM Messenger deployer address file
  --teleporter-messenger-deployer-tx-path string       path to an ICM Messenger deployer tx file
  --teleporter-registry-bytecode-path string           path to an ICM Registry bytecode file

Proof Of Stake Flags:
  --pos-maximum-stake-amount uint64     maximum stake amount
  --pos-maximum-stake-multiplier uint8  maximum stake multiplier
  --pos-minimum-delegation-fee uint16   minimum delegation fee
  --pos-minimum-stake-amount uint64     minimum stake amount
  --pos-minimum-stake-duration uint64   minimum stake duration (in seconds)
  --pos-weight-to-value-factor uint64   weight to value factor

Signature Aggregator Flags:
  --aggregator-log-level string  log level to use with signature aggregator
  --aggregator-log-to-stdout     use stdout for signature aggregator logs
```

<a id="lux-blockchain-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
lux blockchain describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis          Print the genesis to the console directly instead of the summary
-h, --help             help for describe
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
lux blockchain export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help                         help for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.lux-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check                skip check for new versions
```

<a id="lux-blockchain-import"></a>
### import

Import blockchain configurations into lux-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
lux blockchain import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#lux-blockchain-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#lux-blockchain-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help             help for import
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
lux blockchain import file [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    the blockchain configuration to import from the provided repo
--branch string        the repo branch to use if downloading a new repo
-f, --force            overwrite the existing configuration if one exists
-h, --help             help for file
--repo string          the repo to import (ex: luxfi/lux-plugins-core) or url to download the repo from
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
lux blockchain import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string    the blockchain ID
--cluster string          operate on the given cluster
--custom                  use a custom VM template
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
--evm                     import a subnet-evm
--force                   overwrite the existing configuration if one exists
-f, --testnet                testnet           operate on testnet (alias to testnet
-h, --help                help for public
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-url string         [optional] URL of an already running validator
-t, --testnet             testnet           operate on testnet (alias to testnet)
--config string           config file (default is $HOME/.lux-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="lux-blockchain-join"></a>
### join

The blockchain join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Blockchain's admins must add
the NodeID of your validator to the Blockchain's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --luxgo-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Testnet Testnet and Mainnet.

**Usage:**
```bash
lux blockchain join [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-config string    file path of the luxgo config file
--cluster string               operate on the given cluster
--data-dir string              path of luxgo's data dir directory
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write                  if true, skip to prompt to overwrite the config file
-f, --testnet                     testnet                operate on testnet (alias to testnet
-h, --help                     help for join
-k, --key string               select the key to use [testnet only]
-g, --ledger                   use ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings         use the given ledger addresses
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of luxgo's plugin directory
--print                        if true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet                  testnet                operate on testnet (alias to testnet)
--config string                config file (default is $HOME/.lux-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="lux-blockchain-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
lux blockchain list [subcommand] [flags]
```

**Flags:**

```bash
--deployed             show additional deploy information
-h, --help             help for list
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
lux blockchain publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force                      If true, ignores if the blockchain has been published in the past, and attempts a forced publish.
-h, --help                   help for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Blockchain description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="lux-blockchain-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted blockchain network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
lux blockchain removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers        allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings    endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string           log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout              use stdout for signature aggregator logs
--auth-keys strings                     (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
--blockchain-genesis-key                use genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                 CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string         private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                        operate on the given cluster
--devnet                                operate on a devnet network
--endpoint string                       use the given endpoint for network operations
--force                                 force validator removal even if it's not getting rewarded
-f, --testnet                              testnet                         operate on testnet (alias to testnet
-h, --help                              help for removeValidator
-k, --key string                        select the key to use [testnet deploy only]
-g, --ledger                            use ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings                  use the given ledger addresses
-l, --local                             operate on a local network
-m, --mainnet                           operate on mainnet
--node-endpoint string                  remove validator that responds to the given endpoint
--node-id string                        node-id of the validator
--output-tx-path string                 (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                            connect to validator manager at the given rpc endpoint
-t, --testnet                           testnet                         operate on testnet (alias to testnet)
--uptime uint                           validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                         config file (default is $HOME/.lux-cli/config.json)
--log-level string                      log level for the application (default "ERROR")
--skip-update-check                     skip check for new versions
```

<a id="lux-blockchain-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
lux blockchain stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --testnet             testnet      operate on testnet (alias to testnet
-h, --help             help for stats
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          testnet      operate on testnet (alias to testnet)
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
lux blockchain upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#lux-blockchain-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Testnet Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --luxgo-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.lux.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#lux-blockchain-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#lux-blockchain-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#lux-blockchain-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#lux-blockchain-upgrade-print): Print the upgrade.json file content
- [`vm`](#lux-blockchain-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Testnet and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help             help for upgrade
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Testnet Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --luxgo-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.lux.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
lux blockchain upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-chain-config-dir string    luxgo's chain config file directory (default "/home/runner/.luxgo/chains")
--config                                 create upgrade config for future subnet deployments (same as generate)
--force                                  If true, don't prompt for confirmation of timestamps in the past
--testnet                                   testnet                             apply upgrade existing testnet deployment (alias for `testnet`)
-h, --help                               help for apply
--local                                  local                           apply upgrade existing local deployment
--mainnet                                mainnet                       apply upgrade existing mainnet deployment
--print                                  if true, print the manual config without prompting (for public networks only)
--testnet                                testnet                       apply upgrade existing testnet deployment (alias for `testnet`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check                      skip check for new versions
```

<a id="lux-blockchain-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
lux blockchain upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force                      If true, overwrite a possibly existing file without prompting
-h, --help                   help for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="lux-blockchain-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
lux blockchain upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for generate
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
lux blockchain upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                   help for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="lux-blockchain-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
lux blockchain upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for print
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Testnet and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
lux blockchain upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string        Upgrade to custom binary
--config               upgrade config for future subnet deployments
--testnet                 testnet           upgrade existing testnet deployment (alias for `testnet`)
-h, --help             help for vm
--latest               upgrade to latest version
--local                local         upgrade existing local deployment
--mainnet              mainnet     upgrade existing mainnet deployment
--plugin-dir string    plugin directory to automatically upgrade VM
--print                print instructions for upgrading
--testnet              testnet     upgrade existing testnet deployment (alias for `testnet`)
--version string       Upgrade to custom version
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain and provides
several statistics about them.

**Usage:**
```bash
lux blockchain validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --testnet             testnet      operate on testnet (alias to testnet
-h, --help             help for validators
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          testnet      operate on testnet (alias to testnet)
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-blockchain-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
lux blockchain vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for vmid
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-config"></a>
## lux config

Customize configuration for Lux-CLI

**Usage:**
```bash
lux config [subcommand] [flags]
```

**Subcommands:**

- [`authorize-cloud-access`](#lux-config-authorize-cloud-access): set preferences to authorize access to cloud resources
- [`metrics`](#lux-config-metrics): set user metrics collection preferences
- [`migrate`](#lux-config-migrate): migrate command migrates old ~/.lux-cli.json and ~/.lux-cli/config to /.lux-cli/config.json..
- [`snapshotsAutoSave`](#lux-config-snapshotsautosave): set user preference between auto saving local network snapshots or not
- [`update`](#lux-config-update): set user preference between update check or not

**Flags:**

```bash
-h, --help             help for config
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-config-authorize-cloud-access"></a>
### authorize-cloud-access

set preferences to authorize access to cloud resources

**Usage:**
```bash
lux config authorize-cloud-access [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for authorize-cloud-access
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-config-metrics"></a>
### metrics

set user metrics collection preferences

**Usage:**
```bash
lux config metrics [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for metrics
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-config-migrate"></a>
### migrate

migrate command migrates old ~/.lux-cli.json and ~/.lux-cli/config to /.lux-cli/config.json..

**Usage:**
```bash
lux config migrate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for migrate
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-config-snapshotsautosave"></a>
### snapshotsAutoSave

set user preference between auto saving local network snapshots or not

**Usage:**
```bash
lux config snapshotsAutoSave [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for snapshotsAutoSave
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-config-update"></a>
### update

set user preference between update check or not

**Usage:**
```bash
lux config update [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for update
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-contract"></a>
## lux contract

The contract command suite provides a collection of tools for deploying
and interacting with smart contracts.

**Usage:**
```bash
lux contract [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-contract-deploy): The contract command suite provides a collection of tools for deploying
smart contracts.
- [`initValidatorManager`](#lux-contract-initvalidatormanager): Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager

**Flags:**

```bash
-h, --help             help for contract
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-contract-deploy"></a>
### deploy

The contract command suite provides a collection of tools for deploying
smart contracts.

**Usage:**
```bash
lux contract deploy [subcommand] [flags]
```

**Subcommands:**

- [`erc20`](#lux-contract-deploy-erc20): Deploy an ERC20 token into a given Network and Blockchain

**Flags:**

```bash
-h, --help             help for deploy
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-contract-deploy-erc20"></a>
#### deploy erc20

Deploy an ERC20 token into a given Network and Blockchain

**Usage:**
```bash
lux contract deploy erc20 [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string       deploy the ERC20 contract into the given CLI blockchain
--blockchain-id string    deploy the ERC20 contract into the given blockchain ID/Alias
--c-chain                 deploy the ERC20 contract into LUExchange-Chain
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --testnet                testnet           operate on testnet (alias to testnet
--funded string           set the funded address
--genesis-key             use genesis allocated key as contract deployer
-h, --help                help for erc20
--key string              CLI stored key to use as contract deployer
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--private-key string      private key to use as contract deployer
--rpc string              deploy the contract into the given rpc endpoint
--supply uint             set the token supply
--symbol string           set the token symbol
-t, --testnet             testnet           operate on testnet (alias to testnet)
--config string           config file (default is $HOME/.lux-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="lux-contract-initvalidatormanager"></a>
### initValidatorManager

Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager

**Usage:**
```bash
lux contract initValidatorManager [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers          allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout                dump signature aggregator logs to stdout
--cluster string                          operate on the given cluster
--devnet                                  operate on a devnet network
--endpoint string                         use the given endpoint for network operations
-f, --testnet                                testnet                           operate on testnet (alias to testnet
--genesis-key                             use genesis allocated key as contract deployer
-h, --help                                help for initValidatorManager
--key string                              CLI stored key to use as contract deployer
-l, --local                               operate on a local network
-m, --mainnet                             operate on mainnet
--pos-maximum-stake-amount uint           (PoS only) maximum stake amount (default 1000)
--pos-maximum-stake-multiplier            uint8     (PoS only )maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16       (PoS only) minimum delegation fee (default 1)
--pos-minimum-stake-amount uint           (PoS only) minimum stake amount (default 1)
--pos-minimum-stake-duration uint         (PoS only) minimum stake duration (in seconds) (default 100)
--pos-reward-calculator-address string    (PoS only) initialize the ValidatorManager with reward calculator address
--pos-weight-to-value-factor uint         (PoS only) weight to value factor (default 1)
--private-key string                      private key to use as contract deployer
--rpc string                              deploy the contract into the given rpc endpoint
-t, --testnet                             testnet                           operate on testnet (alias to testnet)
--config string                           config file (default is $HOME/.lux-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check                       skip check for new versions
```

<a id="lux-help"></a>
## lux help

Help provides help for any command in the application.
Simply type lux help [path to command] for full details.

**Usage:**
```bash
lux help [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for help
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-icm"></a>
## lux icm

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
lux icm [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-icm-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#lux-icm-sendmsg): Sends and wait reception for a ICM msg between two blockchains.

**Flags:**

```bash
-h, --help             help for icm
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-icm-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

For Local Networks, it also deploys into LUExchange-Chain.

**Usage:**
```bash
lux icm deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain                                   deploy ICM into LUExchange-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to LUExchange-Chain
--cluster string                            operate on the given cluster
--deploy-messenger                          deploy ICM Messenger (default true)
--deploy-registry                           deploy ICM Registry (default true)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy                     deploy ICM Registry even if Messenger has already been deployed
-f, --testnet                                  testnet                             operate on testnet (alias to testnet
--genesis-key                               use genesis allocated key to fund ICM deploy
-h, --help                                  help for deploy
--include-cchain                            deploy ICM also to LUExchange-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet                               testnet                             operate on testnet (alias to testnet)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="lux-icm-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two blockchains.

**Usage:**
```bash
lux icm sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet                      testnet                 operate on testnet (alias to testnet
--genesis-key                   use genesis allocated key as message originator and to pay source blockchain fees
-h, --help                      help for sendMsg
--hex-encoded                   given message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local                     operate on a local network
-m, --mainnet                   operate on mainnet
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet                   testnet                 operate on testnet (alias to testnet)
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="lux-ictt"></a>
## lux ictt

The ictt command suite provides tools to deploy and manage Interchain Token Transferrers.

**Usage:**
```bash
lux ictt [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-ictt-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help             help for ictt
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-ictt-deploy"></a>
### deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
lux ictt deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home                 set the Transferrer's Home Chain into LUExchange-Chain
--c-chain-remote               set the Transferrer's Remote Chain into LUExchange-Chain
--cluster string               operate on the given cluster
--deploy-erc20-home string     deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home           deploy a Transferrer Home for the Chain's Native Token
--deploy-native-remote         deploy a Transferrer Remote for the Chain's Native Token
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
-f, --testnet                     testnet                  operate on testnet (alias to testnet
-h, --help                     help for deploy
--home-blockchain string       set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key             use genesis allocated key to deploy Transferrer Home
--home-key string              CLI stored key to use to deploy Transferrer Home
--home-private-key string      private key to use to deploy Transferrer Home
--home-rpc string              use the given RPC URL to connect to the home blockchain
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--remote-blockchain string     set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key           use genesis allocated key to deploy Transferrer Remote
--remote-key string            CLI stored key to use to deploy Transferrer Remote
--remote-private-key string    private key to use to deploy Transferrer Remote
--remote-rpc string            use the given RPC URL to connect to the remote blockchain
--remote-token-decimals        uint8   use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin          remove the native minter precompile admin found on remote blockchain genesis
-t, --testnet                  testnet                  operate on testnet (alias to testnet)
--use-home string              use the given Transferrer's Home Address
--version string               tag/branch/commit of Lux Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                config file (default is $HOME/.lux-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="lux-interchain"></a>
## lux interchain

The interchain command suite provides a collection of tools to
set and manage interoperability between blockchains.

**Usage:**
```bash
lux interchain [subcommand] [flags]
```

**Subcommands:**

- [`messenger`](#lux-interchain-messenger): The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.
- [`relayer`](#lux-interchain-relayer): The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.
- [`tokenTransferrer`](#lux-interchain-tokentransferrer): The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Flags:**

```bash
-h, --help             help for interchain
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-messenger"></a>
### messenger

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
lux interchain messenger [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-interchain-messenger-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#lux-interchain-messenger-sendmsg): Sends and wait reception for a ICM msg between two blockchains.

**Flags:**

```bash
-h, --help             help for messenger
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-messenger-deploy"></a>
#### messenger deploy

Deploys ICM Messenger and Registry into a given L1.

For Local Networks, it also deploys into LUExchange-Chain.

**Usage:**
```bash
lux interchain messenger deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain                                   deploy ICM into LUExchange-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to LUExchange-Chain
--cluster string                            operate on the given cluster
--deploy-messenger                          deploy ICM Messenger (default true)
--deploy-registry                           deploy ICM Registry (default true)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy                     deploy ICM Registry even if Messenger has already been deployed
-f, --testnet                                  testnet                             operate on testnet (alias to testnet
--genesis-key                               use genesis allocated key to fund ICM deploy
-h, --help                                  help for deploy
--include-cchain                            deploy ICM also to LUExchange-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet                               testnet                             operate on testnet (alias to testnet)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="lux-interchain-messenger-sendmsg"></a>
#### messenger sendMsg

Sends and wait reception for a ICM msg between two blockchains.

**Usage:**
```bash
lux interchain messenger sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet                      testnet                 operate on testnet (alias to testnet
--genesis-key                   use genesis allocated key as message originator and to pay source blockchain fees
-h, --help                      help for sendMsg
--hex-encoded                   given message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local                     operate on a local network
-m, --mainnet                   operate on mainnet
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet                   testnet                 operate on testnet (alias to testnet)
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="lux-interchain-relayer"></a>
### relayer

The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.

**Usage:**
```bash
lux interchain relayer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-interchain-relayer-deploy): Deploys an ICM Relayer for the given Network.
- [`logs`](#lux-interchain-relayer-logs): Shows pretty formatted AWM relayer logs
- [`start`](#lux-interchain-relayer-start): Starts AWM relayer on the specified network (Currently only for local network).
- [`stop`](#lux-interchain-relayer-stop): Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Flags:**

```bash
-h, --help             help for relayer
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-relayer-deploy"></a>
#### relayer deploy

Deploys an ICM Relayer for the given Network.

**Usage:**
```bash
lux interchain relayer deploy [subcommand] [flags]
```

**Flags:**

```bash
--allow-private-ips                allow relayer to connec to private ips (default true)
--amount float                     automatically fund l1s fee payments with the given amount
--bin-path string                  use the given relayer binary
--blockchain-funding-key string    key to be used to fund relayer account on all l1s
--blockchains strings              blockchains to relay as source and destination
--cchain                           relay LUExchange-Chain as source and destination
--cchain-amount float              automatically fund cchain fee payments with the given amount
--cchain-funding-key string        key to be used to fund relayer account on cchain
--cluster string                   operate on the given cluster
--devnet                           operate on a devnet network
--endpoint string                  use the given endpoint for network operations
-f, --testnet                         testnet                    operate on testnet (alias to testnet
-h, --help                         help for deploy
--key string                       key to be used by default both for rewards and to pay fees
-l, --local                        operate on a local network
--log-level string                 log level to use for relayer logs
-t, --testnet                      testnet                    operate on testnet (alias to testnet)
--version string                   version to deploy (default "latest-prerelease")
--config string                    config file (default is $HOME/.lux-cli/config.json)
--skip-update-check                skip check for new versions
```

<a id="lux-interchain-relayer-logs"></a>
#### relayer logs

Shows pretty formatted AWM relayer logs

**Usage:**
```bash
lux interchain relayer logs [subcommand] [flags]
```

**Flags:**

```bash
--endpoint string      use the given endpoint for network operations
--first uint           output first N log lines
-f, --testnet             testnet      operate on testnet (alias to testnet
-h, --help             help for logs
--last uint            output last N log lines
-l, --local            operate on a local network
--raw                  raw logs output
-t, --testnet          testnet      operate on testnet (alias to testnet)
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-relayer-start"></a>
#### relayer start

Starts AWM relayer on the specified network (Currently only for local network).

**Usage:**
```bash
lux interchain relayer start [subcommand] [flags]
```

**Flags:**

```bash
--bin-path string      use the given relayer binary
--cluster string       operate on the given cluster
--endpoint string      use the given endpoint for network operations
-f, --testnet             testnet      operate on testnet (alias to testnet
-h, --help             help for start
-l, --local            operate on a local network
-t, --testnet          testnet      operate on testnet (alias to testnet)
--version string       version to use (default "latest-prerelease")
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-relayer-stop"></a>
#### relayer stop

Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Usage:**
```bash
lux interchain relayer stop [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--endpoint string      use the given endpoint for network operations
-f, --testnet             testnet      operate on testnet (alias to testnet
-h, --help             help for stop
-l, --local            operate on a local network
-t, --testnet          testnet      operate on testnet (alias to testnet)
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-tokentransferrer"></a>
### tokenTransferrer

The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Usage:**
```bash
lux interchain tokenTransferrer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-interchain-tokentransferrer-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help             help for tokenTransferrer
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-interchain-tokentransferrer-deploy"></a>
#### tokenTransferrer deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
lux interchain tokenTransferrer deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home                 set the Transferrer's Home Chain into LUExchange-Chain
--c-chain-remote               set the Transferrer's Remote Chain into LUExchange-Chain
--cluster string               operate on the given cluster
--deploy-erc20-home string     deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home           deploy a Transferrer Home for the Chain's Native Token
--deploy-native-remote         deploy a Transferrer Remote for the Chain's Native Token
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
-f, --testnet                     testnet                  operate on testnet (alias to testnet
-h, --help                     help for deploy
--home-blockchain string       set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key             use genesis allocated key to deploy Transferrer Home
--home-key string              CLI stored key to use to deploy Transferrer Home
--home-private-key string      private key to use to deploy Transferrer Home
--home-rpc string              use the given RPC URL to connect to the home blockchain
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--remote-blockchain string     set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key           use genesis allocated key to deploy Transferrer Remote
--remote-key string            CLI stored key to use to deploy Transferrer Remote
--remote-private-key string    private key to use to deploy Transferrer Remote
--remote-rpc string            use the given RPC URL to connect to the remote blockchain
--remote-token-decimals        uint8   use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin          remove the native minter precompile admin found on remote blockchain genesis
-t, --testnet                  testnet                  operate on testnet (alias to testnet)
--use-home string              use the given Transferrer's Home Address
--version string               tag/branch/commit of Lux Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                config file (default is $HOME/.lux-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="lux-key"></a>
## lux key

The key command suite provides a collection of tools for creating and managing
signing keys. You can use these keys to deploy Subnets to the Testnet Testnet,
but these keys are NOT suitable to use in production environments. DO NOT use
these keys on Mainnet.

To get started, use the key create command.

**Usage:**
```bash
lux key [subcommand] [flags]
```

**Subcommands:**

- [`create`](#lux-key-create): The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.
- [`delete`](#lux-key-delete): The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.
- [`export`](#lux-key-export): The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Lux-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.
- [`list`](#lux-key-list): The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.
- [`transfer`](#lux-key-transfer): The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Flags:**

```bash
-h, --help             help for key
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-key-create"></a>
### create

The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.

**Usage:**
```bash
lux key create [subcommand] [flags]
```

**Flags:**

```bash
--file string          import the key from an existing key file
-f, --force            overwrite an existing key with the same name
-h, --help             help for create
--skip-balances        do not query public network balances for an imported key
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-key-delete"></a>
### delete

The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.

**Usage:**
```bash
lux key delete [subcommand] [flags]
```

**Flags:**

```bash
-f, --force            delete the key without confirmation
-h, --help             help for delete
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-key-export"></a>
### export

The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Lux-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.

**Usage:**
```bash
lux key export [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for export
-o, --output string    write the key to the provided file path
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-key-list"></a>
### list

The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.

**Usage:**
```bash
lux key list [subcommand] [flags]
```

**Flags:**

```bash
-a, --all-networks       list all network addresses
--blockchains strings    blockchains to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-c, --cchain             list LUExchange-Chain addresses (default true)
--cluster string         operate on the given cluster
--devnet                 operate on a devnet network
--endpoint string        use the given endpoint for network operations
-f, --testnet               testnet          operate on testnet (alias to testnet
-h, --help               help for list
--keys strings           list addresses for the given keys
-g, --ledger             uints          list ledger addresses for the given indices (default [])
-l, --local              operate on a local network
-m, --mainnet            operate on mainnet
--pchain                 list Platform-Chain addresses (default true)
--subnets strings        subnets to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-t, --testnet            testnet          operate on testnet (alias to testnet)
--tokens strings         provide balance information for the given token contract addresses (Evm only) (default [Native])
--use-gwei               use gwei for EVM balances
-n, --use-nano-lux      use nano Lux for balances
--xchain                 list Exchange-Chain addresses (default true)
--config string          config file (default is $HOME/.lux-cli/config.json)
--log-level string       log level for the application (default "ERROR")
--skip-update-check      skip check for new versions
```

<a id="lux-key-transfer"></a>
### transfer

The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Usage:**
```bash
lux key transfer [subcommand] [flags]
```

**Flags:**

```bash
-o, --amount float                          amount to send or receive (LUX or TOKEN units)
--c-chain-receiver                          receive at LUExchange-Chain
--c-chain-sender                            send from LUExchange-Chain
--cluster string                            operate on the given cluster
-a, --destination-addr string               destination address
--destination-key string                    key associated to a destination address
--destination-subnet string                 subnet where the funds will be sent (token transferrer experimental)
--destination-transferrer-address string    token transferrer address at the destination subnet (token transferrer experimental)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --testnet                                  testnet                             operate on testnet (alias to testnet
-h, --help                                  help for transfer
-k, --key string                            key associated to the sender or receiver address
-i, --ledger uint32                         ledger index associated to the sender or receiver address (default 32768)
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--origin-subnet string                      subnet where the funds belong (token transferrer experimental)
--origin-transferrer-address string         token transferrer address at the origin subnet (token transferrer experimental)
--p-chain-receiver                          receive at Platform-Chain
--p-chain-sender                            send from Platform-Chain
--receiver-blockchain string                receive at the given CLI blockchain
--receiver-blockchain-id string             receive at the given blockchain ID/Alias
--sender-blockchain string                  send from the given CLI blockchain
--sender-blockchain-id string               send from the given blockchain ID/Alias
-t, --testnet                               testnet                             operate on testnet (alias to testnet)
--x-chain-receiver                          receive at Exchange-Chain
--x-chain-sender                            send from Exchange-Chain
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="lux-network"></a>
## lux network

The network command suite provides a collection of tools for managing local Blockchain
deployments.

When you deploy a Blockchain locally, it runs on a local, multi-node Lux network. The
blockchain deploy command starts this network in the background. This command suite allows you
to shutdown, restart, and clear that network.

This network currently supports multiple, concurrently deployed Blockchains.

**Usage:**
```bash
lux network [subcommand] [flags]
```

**Subcommands:**

- [`clean`](#lux-network-clean): The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.
- [`start`](#lux-network-start): The network start command starts a local, multi-node Lux network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.
- [`status`](#lux-network-status): The network status command prints whether or not a local Lux
network is running and some basic stats about the network.
- [`stop`](#lux-network-stop): The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Flags:**

```bash
-h, --help             help for network
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-network-clean"></a>
### clean

The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.

**Usage:**
```bash
lux network clean [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for clean
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-network-start"></a>
### start

The network start command starts a local, multi-node Lux network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.

**Usage:**
```bash
lux network start [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-path string       use this luxgo binary path
--luxgo-version string    use this version of luxgo (ex: v1.17.12) (default "latest-prerelease")
-h, --help                      help for start
--num-nodes uint32              number of nodes to be created on local network (default 2)
--relayer-path string           use this relayer binary path
--relayer-version string        use this relayer version (default "latest-prerelease")
--snapshot-name string          name of snapshot to use to start the network from (default "default")
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="lux-network-status"></a>
### status

The network status command prints whether or not a local Lux
network is running and some basic stats about the network.

**Usage:**
```bash
lux network status [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for status
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-network-stop"></a>
### stop

The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Usage:**
```bash
lux network stop [subcommand] [flags]
```

**Flags:**

```bash
--dont-save               do not save snapshot, just stop the network
-h, --help                help for stop
--snapshot-name string    name of snapshot to use to save network state into (default "default")
--config string           config file (default is $HOME/.lux-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="lux-node"></a>
## lux node

The node command suite provides a collection of tools for creating and maintaining 
validators on Lux Network.

To get started, use the node create command wizard to walk through the
configuration to make your node a primary validator on Lux public network. You can use the 
rest of the commands to maintain your node and make your node a Subnet Validator.

**Usage:**
```bash
lux node [subcommand] [flags]
```

**Subcommands:**

- [`addDashboard`](#lux-node-adddashboard): (ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.
- [`create`](#lux-node-create): (ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Lux Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running lux node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster
- [`destroy`](#lux-node-destroy): (ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.
- [`devnet`](#lux-node-devnet): (ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling lux node status `clusterName`
- [`export`](#lux-node-export): (ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.
- [`import`](#lux-node-import): (ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use lux-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by lux-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.
- [`list`](#lux-node-list): (ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.
- [`loadtest`](#lux-node-loadtest): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.
- [`local`](#lux-node-local): The node local command suite provides a collection of commands related to local nodes
- [`refresh-ips`](#lux-node-refresh-ips): (ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.
- [`resize`](#lux-node-resize): (ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.
- [`scp`](#lux-node-scp): (ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ lux node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ lux node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ lux node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt
- [`ssh`](#lux-node-ssh): (ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.
- [`status`](#lux-node-status): (ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag
- [`sync`](#lux-node-sync): (ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling lux node status `clusterName` --blockchain `blockchainName`
- [`update`](#lux-node-update): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM config.

You can check the status after update by calling lux node status
- [`upgrade`](#lux-node-upgrade): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM version.

You can check the status after upgrade by calling lux node status
- [`validate`](#lux-node-validate): (ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling lux node status `clusterName`
- [`whitelist`](#lux-node-whitelist): (ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Flags:**

```bash
-h, --help             help for node
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-adddashboard"></a>
### addDashboard

(ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.

**Usage:**
```bash
lux node addDashboard [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string    path to additional grafana dashboard json file
-h, --help                        help for addDashboard
--subnet string                   subnet that the dasbhoard is intended for (if any)
--config string                   config file (default is $HOME/.lux-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check               skip check for new versions
```

<a id="lux-node-create"></a>
### create

(ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Lux Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running lux node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster

**Usage:**
```bash
lux node create [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string              path to additional grafana dashboard json file
--alternative-key-pair-name string          key pair name to use if default one generates conflicts
--authorize-access                          authorize CLI to create cloud resources
--auto-replace-keypair                      automatically replaces key pair to access node if previous key pair is not found
--luxgo-version-from-subnet string    install latest luxgo version, that is compatible with the given subnet, on node/s
--aws                                       create node/s in AWS cloud
--aws-profile string                        aws profile to use (default "default")
--aws-volume-iops int                       AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                       AWS volume size in GB (default 1000)
--aws-volume-throughput int                 AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                    AWS volume type (default "gp3")
--bootstrap-ids                             stringArray                nodeIDs of bootstrap nodes
--bootstrap-ips                             stringArray                IP:port pairs of bootstrap nodes
--cluster string                            operate on the given cluster
--custom-luxgo-version string         install given luxgo version on node/s
--devnet                                    operate on a devnet network
--enable-monitoring                         set up Prometheus monitoring for created nodes. This option creates a separate monitoring cloud instance and incures additional cost
--endpoint string                           use the given endpoint for network operations
-f, --testnet                                  testnet                             operate on testnet (alias to testnet
--gcp                                       create node/s in GCP cloud
--gcp-credentials string                    use given GCP credentials
--gcp-project string                        use given GCP project
--genesis string                            path to genesis file
--grafana-pkg string                        use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help                                  help for create
--latest-luxgo-pre-release-version    install latest luxgo pre-release version on node/s
--latest-luxgo-version                install latest luxgo release version on node/s
-m, --mainnet                               operate on mainnet
--node-type string                          cloud instance type. Use 'default' to use recommended default instance type
--num-apis                                  ints                            number of API nodes(nodes without stake) to create in the new Devnet
--num-validators                            ints                      number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--partial-sync                              primary network partial sync (default true)
--public-http-port                          allow public access to luxgo HTTP port
--region strings                            create node(s) in given region(s). Use comma to separate multiple regions
--ssh-agent-identity string                 use given ssh identity(only for ssh agent). If not set, default will be used
-t, --testnet                               testnet                             operate on testnet (alias to testnet)
--upgrade string                            path to upgrade file
--use-ssh-agent                             use ssh agent(ex: Yubikey) for ssh auth
--use-static-ip                             attach static Public IP on cloud servers (default true)
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="lux-node-destroy"></a>
### destroy

(ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.

**Usage:**
```bash
lux node destroy [subcommand] [flags]
```

**Flags:**

```bash
--all                   destroy all existing clusters created by Lux CLI
--authorize-access      authorize CLI to release cloud resources
-y, --authorize-all     authorize all CLI requests
--authorize-remove      authorize CLI to remove all local files related to cloud nodes
--aws-profile string    aws profile to use (default "default")
-h, --help              help for destroy
--config string         config file (default is $HOME/.lux-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="lux-node-devnet"></a>
### devnet

(ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling lux node status `clusterName`

**Usage:**
```bash
lux node devnet [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#lux-node-devnet-deploy): (ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.
- [`wiz`](#lux-node-devnet-wiz): (ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Flags:**

```bash
-h, --help             help for devnet
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-devnet-deploy"></a>
#### devnet deploy

(ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.

**Usage:**
```bash
lux node devnet deploy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                  help for deploy
--no-checks                 do not check for healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-only               only create a subnet
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check         skip check for new versions
```

<a id="lux-node-devnet-wiz"></a>
#### devnet wiz

(ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Usage:**
```bash
lux node devnet wiz [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                         path to additional grafana dashboard json file
--alternative-key-pair-name string                     key pair name to use if default one generates conflicts
--authorize-access                                     authorize CLI to create cloud resources
--auto-replace-keypair                                 automatically replaces key pair to access node if previous key pair is not found
--aws                                                  create node/s in AWS cloud
--aws-profile string                                   aws profile to use (default "default")
--aws-volume-iops int                                  AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                                  AWS volume size in GB (default 1000)
--aws-volume-throughput int                            AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                               AWS volume type (default "gp3")
--chain-config string                                  path to the chain configuration for subnet
--custom-luxgo-version string                    install given luxgo version on node/s
--custom-subnet                                        use a custom VM as the subnet virtual machine
--custom-vm-branch string                              custom vm branch or commit
--custom-vm-build-script string                        custom vm build-script
--custom-vm-repo-url string                            custom vm repository url
--default-validator-params                             use default weight/start/duration params for subnet validator
--deploy-icm-messenger                                 deploy Interchain Messenger (default true)
--deploy-icm-registry                                  deploy Interchain Registry (default true)
--deploy-teleporter-messenger                          deploy Interchain Messenger (default true)
--deploy-teleporter-registry                           deploy Interchain Registry (default true)
--enable-monitoring                                    set up Prometheus monitoring for created nodes. Please note that this option creates a separate monitoring instance and incures additional cost
--evm-chain-id uint                                    chain ID to use with Subnet-EVM
--evm-defaults                                         use default production settings with Subnet-EVM
--evm-production-defaults                              use default production settings for your blockchain
--evm-subnet                                           use Subnet-EVM as the subnet virtual machine
--evm-test-defaults                                    use default test settings for your blockchain
--evm-token string                                     token name to use with Subnet-EVM
--evm-version string                                   version of Subnet-EVM to use
--force-subnet-create                                  overwrite the existing subnet configuration if one exists
--gcp                                                  create node/s in GCP cloud
--gcp-credentials string                               use given GCP credentials
--gcp-project string                                   use given GCP project
--grafana-pkg string                                   use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help                                             help for wiz
--icm                                                  generate an icm-ready vm
--icm-messenger-contract-address-path string           path to an icm messenger contract address file
--icm-messenger-deployer-address-path string           path to an icm messenger deployer address file
--icm-messenger-deployer-tx-path string                path to an icm messenger deployer tx file
--icm-registry-bytecode-path string                    path to an icm registry bytecode file
--icm-version string                                   icm version to deploy (default "latest")
--latest-luxgo-pre-release-version               install latest luxgo pre-release version on node/s
--latest-luxgo-version                           install latest luxgo release version on node/s
--latest-evm-version                                   use latest Subnet-EVM released version
--latest-pre-released-evm-version                      use latest Subnet-EVM pre-released version
--node-config string                                   path to luxgo node configuration for subnet
--node-type string                                     cloud instance type. Use 'default' to use recommended default instance type
--num-apis                                             ints                                       number of API nodes(nodes without stake) to create in the new Devnet
--num-validators                                       ints                                 number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--public-http-port                                     allow public access to luxgo HTTP port
--region strings                                       create node/s in given region(s). Use comma to separate multiple regions
--relayer                                              run AWM relayer when deploying the vm
--ssh-agent-identity string                            use given ssh identity(only for ssh agent). If not set, default will be used.
--subnet-aliases strings                               additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-config string                                 path to the subnet configuration for subnet
--subnet-genesis string                                file path of the subnet genesis
--teleporter                                           generate an icm-ready vm
--teleporter-messenger-contract-address-path string    path to an icm messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an icm messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an icm messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an icm registry bytecode file
--teleporter-version string                            icm version to deploy (default "latest")
--use-ssh-agent                                        use ssh agent for ssh
--use-static-ip                                        attach static Public IP on cloud servers (default true)
--validators strings                                   deploy subnet into given comma separated list of validators. defaults to all cluster nodes
--config string                                        config file (default is $HOME/.lux-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check                                    skip check for new versions
```

<a id="lux-node-export"></a>
### export

(ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.

**Usage:**
```bash
lux node export [subcommand] [flags]
```

**Flags:**

```bash
--file string          specify the file to export the cluster configuration to
--force                overwrite the file if it exists
-h, --help             help for export
--include-secrets      include keys in the export
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-import"></a>
### import

(ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use lux-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by lux-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.

**Usage:**
```bash
lux node import [subcommand] [flags]
```

**Flags:**

```bash
--file string          specify the file to export the cluster configuration to
-h, --help             help for import
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-list"></a>
### list

(ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.

**Usage:**
```bash
lux node list [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for list
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-loadtest"></a>
### loadtest

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.

**Usage:**
```bash
lux node loadtest [subcommand] [flags]
```

**Subcommands:**

- [`start`](#lux-node-loadtest-start): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.
- [`stop`](#lux-node-loadtest-stop): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Flags:**

```bash
-h, --help             help for loadtest
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-loadtest-start"></a>
#### loadtest start

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.

**Usage:**
```bash
lux node loadtest start [subcommand] [flags]
```

**Flags:**

```bash
--authorize-access              authorize CLI to create cloud resources
--aws                           create loadtest node in AWS cloud
--aws-profile string            aws profile to use (default "default")
--gcp                           create loadtest in GCP cloud
-h, --help                      help for start
--load-test-branch string       load test branch or commit
--load-test-build-cmd string    command to build load test binary
--load-test-cmd string          command to run load test
--load-test-repo string         load test repo url to use
--node-type string              cloud instance type for loadtest script
--region string                 create load test node in a given region
--ssh-agent-identity string     use given ssh identity(only for ssh agent). If not set, default will be used
--use-ssh-agent                 use ssh agent(ex: Yubikey) for ssh auth
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="lux-node-loadtest-stop"></a>
#### loadtest stop

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Usage:**
```bash
lux node loadtest stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for stop
--load-test strings    stop specified load test node(s). Use comma to separate multiple load test instance names
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-local"></a>
### local

The node local command suite provides a collection of commands related to local nodes

**Usage:**
```bash
lux node local [subcommand] [flags]
```

**Subcommands:**

- [`destroy`](#lux-node-local-destroy): Cleanup local node.
- [`start`](#lux-node-local-start): The node local start command creates Lux nodes on the local machine.
Once this command is completed, you will have to wait for the Lux node
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. 

You can check the bootstrapping status by running lux node status local.
- [`status`](#lux-node-local-status): Get status of local node.
- [`stop`](#lux-node-local-stop): Stop local node.
- [`track`](#lux-node-local-track): Track specified blockchain with local node
- [`validate`](#lux-node-local-validate): Use Lux Node set up on local machine to set up specified L1 by providing the
RPC URL of the L1. 

This command can only be used to validate Proof of Stake L1.

**Flags:**

```bash
-h, --help             help for local
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-local-destroy"></a>
#### local destroy

Cleanup local node.

**Usage:**
```bash
lux node local destroy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for destroy
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-local-start"></a>
#### local start

The node local start command creates Lux nodes on the local machine.
Once this command is completed, you will have to wait for the Lux node
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. 

You can check the bootstrapping status by running lux node status local.

**Usage:**
```bash
lux node local start [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-path string                   use this luxgo binary path
--bootstrap-id                              stringArray                 nodeIDs of bootstrap nodes
--bootstrap-ip                              stringArray                 IP:port pairs of bootstrap nodes
--cluster string                            operate on the given cluster
--custom-luxgo-version string         install given luxgo version on node/s
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --testnet                                  testnet                             operate on testnet (alias to testnet
--genesis string                            path to genesis file
-h, --help                                  help for start
--latest-luxgo-pre-release-version    install latest luxgo pre-release version on node/s (default true)
--latest-luxgo-version                install latest luxgo release version on node/s
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--node-config string                        path to common luxgo config settings for all nodes
--num-nodes uint32                          number of Lux nodes to create on local machine (default 1)
--partial-sync                              primary network partial sync (default true)
--staking-cert-key-path string              path to provided staking cert key for node
--staking-signer-key-path string            path to provided staking signer key for node
--staking-tls-key-path string               path to provided staking tls key for node
-t, --testnet                               testnet                             operate on testnet (alias to testnet)
--upgrade string                            path to upgrade file
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="lux-node-local-status"></a>
#### local status

Get status of local node.

**Usage:**
```bash
lux node local status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    specify the blockchain the node is syncing with
-h, --help             help for status
--l1 string            specify the blockchain the node is syncing with
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-local-stop"></a>
#### local stop

Stop local node.

**Usage:**
```bash
lux node local stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for stop
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-local-track"></a>
#### local track

Track specified blockchain with local node

**Usage:**
```bash
lux node local track [subcommand] [flags]
```

**Flags:**

```bash
--luxgo-path string                   use this luxgo binary path
--custom-luxgo-version string         install given luxgo version on node/s
-h, --help                                  help for track
--latest-luxgo-pre-release-version    install latest luxgo pre-release version on node/s (default true)
--latest-luxgo-version                install latest luxgo release version on node/s
--config string                             config file (default is $HOME/.lux-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="lux-node-local-validate"></a>
#### local validate

Use Lux Node set up on local machine to set up specified L1 by providing the
RPC URL of the L1. 

This command can only be used to validate Proof of Stake L1.

**Usage:**
```bash
lux node local validate [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-log-level string       log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout          use stdout for signature aggregator logs
--balance float                     amount of LUX to increase validator's balance by
--blockchain string                 specify the blockchain the node is syncing with
--delegation-fee uint16             delegation fee (in bips) (default 100)
--disable-owner string              Platform-Chain address that will able to disable the validator with a Platform-Chain transaction
-h, --help                          help for validate
--l1 string                         specify the blockchain the node is syncing with
--minimum-stake-duration uint       minimum stake duration (in seconds) (default 100)
--remaining-balance-owner string    Platform-Chain address that will receive any leftover LUX from the validator when it is removed from Subnet
--rpc string                        connect to validator manager at the given rpc endpoint
--stake-amount uint                 amount of tokens to stake
--config string                     config file (default is $HOME/.lux-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check                 skip check for new versions
```

<a id="lux-node-refresh-ips"></a>
### refresh-ips

(ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.

**Usage:**
```bash
lux node refresh-ips [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string    aws profile to use (default "default")
-h, --help              help for refresh-ips
--config string         config file (default is $HOME/.lux-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="lux-node-resize"></a>
### resize

(ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.

**Usage:**
```bash
lux node resize [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string    aws profile to use (default "default")
--disk-size string      Disk size to resize in Gb (e.g. 1000Gb)
-h, --help              help for resize
--node-type string      Node type to resize (e.g. t3.2xlarge)
--config string         config file (default is $HOME/.lux-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="lux-node-scp"></a>
### scp

(ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ lux node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ lux node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ lux node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt

**Usage:**
```bash
lux node scp [subcommand] [flags]
```

**Flags:**

```bash
--compress             use compression for ssh
-h, --help             help for scp
--recursive            copy directories recursively
--with-loadtest        include loadtest node for scp cluster operations
--with-monitor         include monitoring node for scp cluster operations
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-ssh"></a>
### ssh

(ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.

**Usage:**
```bash
lux node ssh [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for ssh
--parallel             run ssh command on all nodes in parallel
--with-loadtest        include loadtest node for ssh cluster operations
--with-monitor         include monitoring node for ssh cluster operations
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-status"></a>
### status

(ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag

**Usage:**
```bash
lux node status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    specify the blockchain the node is syncing with
-h, --help             help for status
--subnet string        specify the blockchain the node is syncing with
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-sync"></a>
### sync

(ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling lux node status `clusterName` --blockchain `blockchainName`

**Usage:**
```bash
lux node sync [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                  help for sync
--no-checks                 do not check for bootstrapped/healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    subnet alias to be used for RPC calls. defaults to subnet blockchain ID
--validators strings        sync subnet into given comma separated list of validators. defaults to all cluster nodes
--config string             config file (default is $HOME/.lux-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check         skip check for new versions
```

<a id="lux-node-update"></a>
### update

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM config.

You can check the status after update by calling lux node status

**Usage:**
```bash
lux node update [subcommand] [flags]
```

**Subcommands:**

- [`subnet`](#lux-node-update-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling lux node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help             help for update
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-update-subnet"></a>
#### update subnet

(ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling lux node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
lux node update subnet [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for subnet
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-upgrade"></a>
### upgrade

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their luxgo or VM version.

You can check the status after upgrade by calling lux node status

**Usage:**
```bash
lux node upgrade [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for upgrade
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-validate"></a>
### validate

(ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling lux node status `clusterName`

**Usage:**
```bash
lux node validate [subcommand] [flags]
```

**Subcommands:**

- [`primary`](#lux-node-validate-primary): (ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.
- [`subnet`](#lux-node-validate-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling lux node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling lux node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help             help for validate
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-node-validate-primary"></a>
#### validate primary

(ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.

**Usage:**
```bash
lux node validate primary [subcommand] [flags]
```

**Flags:**

```bash
-e, --ewoq                   use ewoq key [testnet/devnet only]
-h, --help                   help for primary
-k, --key string             select the key to use [testnet only]
-g, --ledger                 use ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings       use the given ledger addresses
--stake-amount uint          how many LUX to stake in the validator
--staking-period duration    how long validator validates for after start time
--start-time string          UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--config string              config file (default is $HOME/.lux-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="lux-node-validate-subnet"></a>
#### validate subnet

(ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling lux node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling lux node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
lux node validate subnet [subcommand] [flags]
```

**Flags:**

```bash
--default-validator-params    use default weight/start/duration params for subnet validator
-e, --ewoq                    use ewoq key [testnet/devnet only]
-h, --help                    help for subnet
-k, --key string              select the key to use [testnet/devnet only]
-g, --ledger                  use ledger instead of key (always true on mainnet, defaults to false on testnet/devnet)
--ledger-addrs strings        use the given ledger addresses
--no-checks                   do not check for bootstrapped status or healthy status
--no-validation-checks        do not check if subnet is already synced or validated (default true)
--stake-amount uint           how many LUX to stake in the validator
--staking-period duration     how long validator validates for after start time
--start-time string           UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--validators strings          validate subnet for the given comma separated list of validators. defaults to all cluster nodes
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="lux-node-whitelist"></a>
### whitelist

(ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Usage:**
```bash
lux node whitelist [subcommand] [flags]
```

**Flags:**

```bash
-y, --current-ip       whitelist current host ip
-h, --help             help for whitelist
--ip string            ip address to whitelist
--ssh string           ssh public key to whitelist
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-primary"></a>
## lux primary

The primary command suite provides a collection of tools for interacting with the
Primary Network

**Usage:**
```bash
lux primary [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#lux-primary-addvalidator): The primary addValidator command adds a node as a validator 
in the Primary Network
- [`describe`](#lux-primary-describe): The subnet describe command prints details of the primary network configuration to the console.

**Flags:**

```bash
-h, --help             help for primary
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-primary-addvalidator"></a>
### addValidator

The primary addValidator command adds a node as a validator 
in the Primary Network

**Usage:**
```bash
lux primary addValidator [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--delegation-fee uint32         set the delegation fee (20 000 is equivalent to 2%)
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --testnet                      testnet                 operate on testnet (alias to testnet
-h, --help                      help for addValidator
-k, --key string                select the key to use [testnet only]
-g, --ledger                    use ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings          use the given ledger addresses
-m, --mainnet                   operate on mainnet
--nodeID string                 set the NodeID of the validator to add
--proof-of-possession string    set the BLS proof of possession of the validator to add
--public-key string             set the BLS public key of the validator to add
--staking-period duration       how long this validator will be staking
--start-time string             UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
-t, --testnet                   testnet                 operate on testnet (alias to testnet)
--weight uint                   set the staking weight of the validator to add
--config string                 config file (default is $HOME/.lux-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="lux-primary-describe"></a>
### describe

The subnet describe command prints details of the primary network configuration to the console.

**Usage:**
```bash
lux primary describe [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
-h, --help             help for describe
-l, --local            operate on a local network
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-transaction"></a>
## lux transaction

The transaction command suite provides all of the utilities required to sign multisig transactions.

**Usage:**
```bash
lux transaction [subcommand] [flags]
```

**Subcommands:**

- [`commit`](#lux-transaction-commit): The transaction commit command commits a transaction by submitting it to the Platform-Chain.
- [`sign`](#lux-transaction-sign): The transaction sign command signs a multisig transaction.

**Flags:**

```bash
-h, --help             help for transaction
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-transaction-commit"></a>
### commit

The transaction commit command commits a transaction by submitting it to the Platform-Chain.

**Usage:**
```bash
lux transaction commit [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                    help for commit
--input-tx-filepath string    Path to the transaction signed by all signatories
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="lux-transaction-sign"></a>
### sign

The transaction sign command signs a multisig transaction.

**Usage:**
```bash
lux transaction sign [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                    help for sign
--input-tx-filepath string    Path to the transaction file for signing
-k, --key string              select the key to use [testnet only]
-g, --ledger                  use ledger instead of key (always true on mainnet, defaults to false on testnet)
--ledger-addrs strings        use the given ledger addresses
--config string               config file (default is $HOME/.lux-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="lux-update"></a>
## lux update

Check if an update is available, and prompt the user to install it

**Usage:**
```bash
lux update [subcommand] [flags]
```

**Flags:**

```bash
-c, --confirm          Assume yes for installation
-h, --help             help for update
-v, --version          version for update
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-validator"></a>
## lux validator

The validator command suite provides a collection of tools for managing validator
balance on Platform-Chain.

Validator's balance is used to pay for continuous fee to the Platform-Chain. When this Balance reaches 0, 
the validator will be considered inactive and will no longer participate in validating the L1

**Usage:**
```bash
lux validator [subcommand] [flags]
```

**Subcommands:**

- [`getBalance`](#lux-validator-getbalance): This command gets the remaining validator Platform-Chain balance that is available to pay
Platform-Chain continuous fee
- [`increaseBalance`](#lux-validator-increasebalance): This command increases the validator Platform-Chain balance
- [`list`](#lux-validator-list): This command gets a list of the validators of the L1

**Flags:**

```bash
-h, --help             help for validator
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="lux-validator-getbalance"></a>
### getBalance

This command gets the remaining validator Platform-Chain balance that is available to pay
Platform-Chain continuous fee

**Usage:**
```bash
lux validator getBalance [subcommand] [flags]
```

**Flags:**

```bash
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --testnet                testnet           operate on testnet (alias to testnet
-h, --help                help for getBalance
--l1 string               name of L1
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-id string          node ID of the validator
-t, --testnet             testnet           operate on testnet (alias to testnet)
--validation-id string    validation ID of the validator
--config string           config file (default is $HOME/.lux-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="lux-validator-increasebalance"></a>
### increaseBalance

This command increases the validator Platform-Chain balance

**Usage:**
```bash
lux validator increaseBalance [subcommand] [flags]
```

**Flags:**

```bash
--balance float           amount of LUX to increase validator's balance by
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --testnet                testnet           operate on testnet (alias to testnet
-h, --help                help for increaseBalance
-k, --key string          select the key to use [testnet/devnet deploy only]
--l1 string               name of L1 (to increase balance of bootstrap validators only)
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-id string          node ID of the validator
-t, --testnet             testnet           operate on testnet (alias to testnet)
--validation-id string    validationIDStr of the validator
--config string           config file (default is $HOME/.lux-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="lux-validator-list"></a>
### list

This command gets a list of the validators of the L1

**Usage:**
```bash
lux validator list [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --testnet             testnet      operate on testnet (alias to testnet
-h, --help             help for list
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          testnet      operate on testnet (alias to testnet)
--config string        config file (default is $HOME/.lux-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

# Create Lux L1 (/docs/tooling/avalanche-cli/create-avalanche-l1)

---
title: Create Lux L1
description: This page demonstrates how to create an Lux L1 using Lux-CLI.
---

This tutorial walks you through the process of using Lux-CLI to create an Lux L1, deploy it to a local network, and connect to it with Core wallet.

The first step of learning Lux L1 development is learning to use [Lux-CLI](https://github.com/luxfi/lux-cli).

Installation[​](#installation "Direct link to heading")
-------------------------------------------------------

The fastest way to install the latest Lux-CLI binary is by running the install script:

```bash
curl -sSfL https://raw.githubusercontent.com/luxfi/lux-cli/main/scripts/install.sh | sh -s
```

The binary installs inside the `~/bin` directory. If the directory doesn't exist, it will be created.

You can run all of the commands in this tutorial by calling `~/bin/lux`.

You can also add the command to your system path by running:

```bash
export PATH=~/bin:$PATH
```

To make this change permanent, add this line to your shell’s initialization file (e.g., `~/.bashrc` or `~/.zshrc`). For example:

```bash
echo 'export PATH=~/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

Once you add it to your path, you should be able to call the program anywhere with just: `lux`

For more detailed installation instructions, see [Lux-CLI Installation](/docs/tooling/lux-cli).

Create Your Lux L1 Configuration[​](#create-your-lux-l1-configuration "Direct link to heading")
-----------------------------------------------------------------------------------------------

This tutorial teaches you how to create an Ethereum Virtual Machine (EVM) based Lux L1. To do so, you use Subnet-EVM, Lux's L1 fork of the EVM. It supports airdrops, custom fee tokens, configurable gas parameters, and multiple stateful precompiles. To learn more, take a look at [Subnet-EVM](https://github.com/luxfi/subnet-evm). The goal of your first command is to create a Subnet-EVM configuration.

The `lux-cli` command suite provides a collection of tools for developing and deploying Lux L1s.

The Creation Wizard walks you through the process of creating your Lux L1. To get started, first pick a name for your Lux L1. This tutorial uses `myblockchain`, but feel free to substitute that with any name you like. Once you've picked your name, run:

```bash
lux blockchain create myblockchain
```

The following sections walk through each question in the wizard.

### Choose Your VM

```bash
? Which Virtual Machine would you like to use?: 
  ▸ Subnet-EVM
    Custom VM
    Explain the difference
```
Select `Subnet-EVM`.

### Choose Validator Manager

```text
? Which validator management type would you like to use in your blockchain?: 
  ▸ Proof Of Authority
    Proof Of Stake
    Explain the difference
```
Select `Proof Of Authority`.

```text
? Which address do you want to enable as controller of ValidatorManager contract?: 
  ▸ Get address from an existing stored key (created from lux key create or lux key import)
    Custom
```
Select `Get address from an existing stored key`.

```text
? Which stored key should be used enable as controller of ValidatorManager contract?: 
  ▸ ewoq
    cli-awm-relayer
    cli-teleporter-deployer
```
Select `ewoq`.

This key is used to manage (add/remove) the validator set.

<Callout>
Do not use EWOQ key in a testnet or production setup. The EWOQ private key is publicly exposed.
</Callout>

To learn more about different validator management types, see [PoA vs PoS](/docs/lux-l1s/validator-manager/contract).

### Choose Blockchain Configuration

```text
? Do you want to use default values for the Blockchain configuration?: 
  ▸ I want to use defaults for a test environment
    I want to use defaults for a production environment
    I don't want to use default values
    Explain the difference
```

Select `I want to use defaults for a test environment`.
This will automatically setup the configuration for a test environment, including an airdrop to the EWOQ key and Lux ICM.

### Enter Your Lux L1's ChainID

```text
✗ Chain ID: 
```

Choose a positive integer for your EVM-style ChainID.

In production environments, this ChainID needs to be unique and not shared with any other chain. You can visit [chainlist](https://chainlist.org/) to verify that your selection is unique. Because this is a development Lux L1, feel free to pick any number. Stay away from well-known ChainIDs such as 1 (Ethereum) or 43114 (Lux LUExchange-Chain) as those may cause issues with other tools.

### Token Symbol

```text
✗ Token Symbol: 
```

Enter a string to name your Lux L1's native token. The token symbol doesn't necessarily need to be unique. Example token symbols are LUX, JOE, and BTC.

### Wrapping Up

If all worked successfully, the command prints:
```bash
✓ Successfully created blockchain configuration
```

To view the Genesis configuration, use the following command:
```bash
lux blockchain describe myblockchain --genesis
```

You've successfully created your first Lux L1 configuration. Now it's time to deploy it.


# Installation (/docs/tooling/avalanche-cli/get-avalanche-cli)

---
title: Installation
description: Instructions for installing and setting up the Lux-CLI.
---

## Compatibility

Lux-CLI runs on Linux and Mac. Windows is currently not supported.

## Instructions

To download a binary for the latest release, run:

```bash
curl -sSfL https://raw.githubusercontent.com/luxfi/lux-cli/main/scripts/install.sh | sh -s
```

The script installs the binary inside the `~/bin` directory. If the directory doesn't exist, it will be created.

## Adding Lux-CLI to Your PATH

To call the `lux` binary from anywhere, you'll need to add it to your system path. If you installed the binary into the default location, you can run the following snippet to add it to your path.

To add it to your path permanently, add an export command to your shell initialization script. If you run `bash`, use `.bashrc`. If you run `zsh`, use `.zshrc`.

For example:

```bash
export PATH=~/bin:$PATH >> .bashrc
```

## Checking Your Installation

You can test your installation by running `lux --version`. The tool should print the running version.

## Updating

To update your installation, you need to delete your current binary and download the latest version using the preceding steps.

## Building from Source

The source code is available in this [GitHub repository](https://github.com/luxfi/lux-cli).

After you've cloned the repository, checkout the tag you'd like to run. You can compile the code by running `./scripts/build.sh` from the top level directory.

The build script names the binary `./bin/lux`.

# Lux-CLI Overview (/docs/tooling/avalanche-cli)

---
title: Lux-CLI Overview
description: Build, deploy, and manage Lux L1s with the Lux-CLI
---

The Lux-CLI is a powerful command-line tool that streamlines the process of building, deploying, and managing Lux L1 blockchains (formerly known as Subnets).

## Key Features

- **Create & Deploy L1s**: Quickly create and deploy new Lux L1 blockchains to local, testnet, or mainnet environments
- **VM Management**: Deploy L1s with Subnet-EVM or custom Virtual Machines
- **Node Operations**: Run and manage validator nodes across different cloud providers
- **Cross-Chain Messaging**: Set up Teleporter for cross-chain communication
- **Transaction Management**: Handle native token transfers and Platform-Chain operations

## Getting Started

To get started with Lux-CLI:

1. [Install Lux-CLI](/docs/tooling/lux-cli/get-lux-cli) on your system
2. Review the [CLI Commands Reference](/docs/tooling/lux-cli/cli-commands) for available commands
3. Follow the guide to [Create an Lux L1](/docs/tooling/lux-cli/create-lux-l1)

## Quick Links

<Cards>
  <Card title="Installation" href="/docs/tooling/lux-cli/get-lux-cli">
    Get Lux-CLI installed on your system
  </Card>
  <Card title="Create L1s" href="/docs/tooling/lux-cli/create-lux-l1">
    Learn how to create your first Lux L1
  </Card>
  <Card title="Deploy L1s" href="/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-locally">
    Deploy L1s to various environments
  </Card>
  <Card title="CLI Reference" href="/docs/tooling/lux-cli/cli-commands">
    Complete reference for all CLI commands
  </Card>
</Cards>

## Common Use Cases

### Local Development
Deploy and test your L1 locally before moving to testnet or mainnet.

### Production Deployment
Deploy L1s to Testnet testnet for testing, then to mainnet for production use.

### Validator Management
Add and remove validators, manage staking, and monitor node health.

### Cross-Chain Integration
Enable cross-chain messaging between your L1 and other chains using Teleporter.

## Support

- [GitHub Repository](https://github.com/luxfi/lux-cli)
- [Discord Community](https://chat.avalabs.org/)
- [Documentation](https://docs.lux.network/)


# Overview (/docs/tooling/avalanche-sdk)

---
title: Overview
description: Build applications and interact with Lux networks programmatically
icon: Rocket
---

The **Lux SDK for TypeScript** is a modular suite of tools designed for building powerful applications on the Lux ecosystem. Whether you're building DeFi applications, NFT platforms, or cross-chain bridges, our SDKs provide everything you need.

<img src="https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=1e10ff983be444a989bf30e2dedf1cb8" data-og-width="1984" width="1984" data-og-height="604" height="604" data-path="images/lux_sdk.jpg" data-optimize="true" data-opv="3" srcSet="https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?w=280&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=ddf429244d37623020bd754cd793dc92 280w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?w=560&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=57ad5a44d41025b567fc1564894e80ca 560w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?w=840&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=5b51ef1d5cf23ccce207b632610d12df 840w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?w=1100&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=c986a3608d6e29b7ad0c4f1f29df7845 1100w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?w=1650&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=55b096c77f3dc0505293b8308974a2b9 1650w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/lux_sdk.jpg?w=2500&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=f15b10a3cc43b734a0777b239511af74 2500w" />

### Core Capabilities

* **Direct Chain Access** - RPC calls, wallet integration, and transaction management.
* **Indexed Data & Metrics** - Access Glacier Data API & Metrics API with type safety.
* **Interchain Messaging** - Build cross-L1 applications with ICM/Teleporter.

<Callout type="warning">
  **Developer Preview**: This suite of SDKs is currently in beta and is subject to change. Use in production at your own risk.
</Callout>

<Callout>
  We'd love to hear about your experience! **<a href="https://forms.gle/kpunVSkA9nuCa1wM9" target="_blank" rel="noopener noreferrer">Please share your feedback here</a>.**
</Callout>

<Cards>
  <Card title="Open Source on GitHub" icon="github" href="https://github.com/luxfi/lux-sdk-typescript">
    Check out the code, contribute, or report issues. The Lux SDK TypeScript is fully open source.
  </Card>
</Cards>

## Which SDK Should I Use?

Choose the right SDK based on your specific needs:

| SDK Package                                                                  | Description                                                      |
| :--------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| [`@lux-sdk/client`](/lux-sdk/client-sdk/getting-started)         | Direct blockchain interaction - transactions, wallets, RPC calls |
| [`@lux-sdk/chainkit`](/lux-sdk/chainkit-sdk/getting-started)     | Complete suite: Data, Metrics and Webhooks API                   |
| [`@lux-sdk/interchain`](/lux-sdk/interchain-sdk/getting-started) | Send messages between Lux L1s using ICM/Teleporter         |

## Quick Start

<Tabs items={['npm', 'yarn', 'pnpm']}>
  <Tab value="npm">
    ```bash  theme={null}
    npm install @lux-sdk/client
    ```
  </Tab>

  <Tab value="yarn">
    ```bash  theme={null}
    yarn add @lux-sdk/client
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash  theme={null}
    pnpm add @lux-sdk/client
    ```
  </Tab>
</Tabs>

### Basic Example

```typescript  theme={null}
import { createClient } from '@lux-sdk/client';

// Initialize the client
const client = createClient({
  network: 'mainnet'
});

// Get balance
const balance = await client.getBalance({
  address: '0x...',
  chainId: 43114
});

console.log('Balance:', balance);
```

## Available SDKs

### Client SDK

The main Lux client SDK for interacting with Lux nodes and building blockchain applications.

**Key Features:**

* **Complete API coverage** for Platform-Chain, Exchange-Chain, and LUExchange-Chain.
* **Full viem compatibility** - anything you can do with viem works here.
* **TypeScript-first design** with full type safety.
* **Smart contract interactions** with first-class APIs.
* **Wallet integration** and transaction management.
* **Cross-chain transfers** between X, P and C chains.

**Common Use Cases:**

* Retrieve balances and UTXOs for addresses
* Build, sign, and issue transactions to any chain
* Add validators and delegators
* Create subnets and blockchains.
* Convert subnets to L1s.

<Card title="Get Started with Client SDK" icon="arrow-right" href="/lux-sdk/client-sdk/getting-started">
  Learn how to integrate blockchain functionality into your application
</Card>

### ChainKit SDK

Combined SDK with full typed coverage of Lux Data (Glacier) and Metrics APIs.

**Key Features:**

* **Full endpoint coverage** for Glacier Data API and Metrics API
* **Strongly-typed models** with automatic TypeScript inference
* **Built-in pagination** helpers and automatic retries/backoff
* **High-level helpers** for transactions, blocks, addresses, tokens, NFTs
* **Metrics insights** including network health, validator stats, throughput
* **Webhook support** with payload shapes and signature verification

**API Endpoints:**

* Glacier API: <a href="https://glacier-api.lux.network/api" target="_blank" rel="noopener noreferrer">[https://glacier-api.lux.network/api](https://glacier-api.lux.network/api)</a>
* Metrics API: <a href="https://metrics.lux.network/api" target="_blank" rel="noopener noreferrer">[https://metrics.lux.network/api](https://metrics.lux.network/api)</a>

<Card title="Get Started with ChainKit SDK" icon="arrow-right" href="/lux-sdk/chainkit-sdk/getting-started">
  Access comprehensive blockchain data and analytics
</Card>

### Interchain SDK

SDK for building cross-L1 applications and bridges.

**Key Features:**

* **Type-safe ICM client** for sending cross-chain messages
* **Seamless wallet integration** with existing wallet clients
* **Built-in support** for Lux LUExchange-Chain and custom subnets
* **Message tracking** and delivery confirmation
* **Gas estimation** for cross-chain operations

**Use Cases:**

* Cross-chain token bridges
* Multi-L1 governance systems
* Interchain data oracles
* Cross-subnet liquidity pools

<Card title="Get Started with Interchain SDK" icon="arrow-right" href="/lux-sdk/interchain-sdk/getting-started">
  Build powerful cross-chain applications
</Card>

## Support

### Community & Help

* <a href="https://discord.gg/lux" target="_blank" rel="noopener noreferrer">Discord</a> - Get real-time help in the #lux-sdk channel
* <a href="https://t.me/+KDajA4iToKY2ZjBk" target="_blank" rel="noopener noreferrer">Telegram</a> - Join discussions
* <a href="https://x.com/LuxDevelopers" target="_blank" rel="noopener noreferrer">Twitter</a> - Stay updated

### Feedback Sessions

* <a href="https://calendar.google.com/calendar/appointments/schedules/AcZssZ1RkNFpny9hBimkOmBXghLkGJ8RXV0GgHZb2tfrIRoZ9Su3s1wYZOP2R_OjXpwG2aQw_zlHf2JQ?gv=true" target="_blank" rel="noopener noreferrer">Book a Google Meet Feedback Session</a> - Schedule a 1-on-1 session to share your feedback and suggestions

### Issue Tracking

* <a href="https://github.com/luxfi/lux-sdk-typescript/issues/new?template=bug_report.md" target="_blank" rel="noopener noreferrer">Report a Bug</a>
* <a href="https://github.com/luxfi/lux-sdk-typescript/issues/new?template=feature_request.md" target="_blank" rel="noopener noreferrer">Request a Feature</a>
* <a href="https://github.com/luxfi/lux-sdk-typescript/issues" target="_blank" rel="noopener noreferrer">View All Issues</a>

### Direct Support

* Technical Issues: <a href="https://github.com/luxfi/lux-sdk-typescript/issues" target="_blank" rel="noopener noreferrer">GitHub Issues</a>
* Security Issues: <a href="mailto:security@luxfi.org">[security@luxfi.org](mailto:security@luxfi.org)</a>
* General Inquiries: <a href="mailto:data-platform@luxfi.org">[data-platform@luxfi.org](mailto:data-platform@luxfi.org)</a>

# Data Visualization (/docs/tooling/avalanche-postman/data-visualization)

---
title: Data Visualization
description: Data visualization for Lux APIs using Postman
---

Data visualization is available for a number of API calls whose responses are transformed and presented in tabular format for easy reference.

Please check out [Installing Postman Collection](/docs/tooling/lux-postman/index) and [Making API Calls](/docs/tooling/lux-postman/making-api-calls) beforehand, as this guide assumes that the user has already gone through these steps.

Data visualizations are available for following API calls:

### LUExchange-Chain[​](#c-chain "Direct link to heading")

- [`eth_baseFee`](/docs/rpcs/c-chain#eth_basefee)
- [`eth_blockNumber`](https://www.quicknode.com/docs/ethereum/eth_blockNumber)
- [`eth_chainId`](https://www.quicknode.com/docs/ethereum/eth_chainId)
- [`eth_getBalance`](https://www.quicknode.com/docs/ethereum/eth_getBalance)
- [`eth_getBlockByHash`](https://www.quicknode.com/docs/ethereum/eth_getBlockByHash)
- [`eth_getBlockByNumber`](https://www.quicknode.com/docs/ethereum/eth_getBlockByNumber)
- [`eth_getTransactionByHash`](https://www.quicknode.com/docs/ethereum/eth_getTransactionByHash)
- [`eth_getTransactionReceipt`](https://www.quicknode.com/docs/ethereum/eth_getTransactionReceipt)
- [`lux.getAtomicTx`](/docs/rpcs/c-chain#luxgetatomictx)

### Platform-Chain[​](#p-chain "Direct link to heading")

- [`platform.getCurrentValidators`](/docs/rpcs/p-chain#platformgetcurrentvalidators)

### Exchange-Chain[​](#x-chain "Direct link to heading")

- [`xvm.getAssetDescription`](/docs/rpcs/x-chain#avmgetassetdescription)
- [`xvm.getBlock`](/docs/rpcs/x-chain#avmgetblock)
- [`xvm.getBlockByHeight`](/docs/rpcs/x-chain#avmgetblockbyheight)
- [`xvm.getTx`](/docs/rpcs/x-chain#avmgettx)

<YouTube id="2jS5EFWLoGs" fullSize={false}/>

Data Visualization Features[​](#data-visualization-features "Direct link to heading")
-------------------------------------------------------------------------------------

- The response output is displayed in tabular format, each data category having a different color.

![Data Visualization Feature](/images/visualize1.png)

- Unix timestamps are converted to date and time.

![Data Visualization Feature](/images/visualize2.png)

- Hexadecimal to decimal conversions.

![Data Visualization Feature](/images/visualize3.png)

- Native token amounts shown as LUX and/or gwei and wei.

![Data Visualization Feature](/images/visualize4.png)

- The name of the transaction type added besides the transaction type ID.

![Data Visualization Feature](/images/visualize5.png)

- Percentages added for the amount of gas used. This percent represents what percentage of gas was used our of the `gasLimit`.

![Data Visualization Feature](/images/visualize6.png)

- Convert the output for atomic transactions from hexadecimal to user readable.

<Callout title="Note">
Please note that this only works for LUExchange-Chain Mainnet, not Testnet.
</Callout>

![Data Visualization Feature](/images/visualize7.png)

How to Visualize Responses[​](#how-to-visualize-responses "Direct link to heading")
-----------------------------------------------------------------------------------

1. After [installing Postman](/docs/tooling/lux-postman#postman-installation) and importing the [Lux collection](/docs/tooling/lux-postman#collection-import), choose an API to make the call. 
2. Make the call.
3. Click on the **Visualize** tab.
4. Now all data from the output is displayed in tabular format.

![Data Visualization Feature](/images/visualize8.png) ![Data Visualization Feature](/images/visualize9.png)

Examples[​](#examples "Direct link to heading")
-----------------------------------------------

### `eth_getTransactionByHash`[​](#eth_gettransactionbyhash "Direct link to heading")

<YouTube id="M83WhbXq5R0" fullSize={false}/>

### `xvm.getBlock`[​](#avmgetblock "Direct link to heading")

<YouTube id="d5E2pHXFInE" fullSize={false}/>

### `platform.getCurrentValidators`[​](#platformgetcurrentvalidators "Direct link to heading")

<YouTube id="Pkf84edkw_0" fullSize={false}/>

### `lux.getAtomicTx`[​](#luxgetatomictx "Direct link to heading")

<YouTube id="AYIgdQomHqc" fullSize={false}/>

### `eth_getBalance`[​](#eth_getbalance "Direct link to heading")

<YouTube id="M3n7cm1DYLE" fullSize={false}/>

# Installing Postman Collection (/docs/tooling/avalanche-postman)

---
title: Installing Postman Collection
description: Installing Postman collection for Lux APIs
---

We have made a Postman collection for Lux, that includes all the public API calls that are available on an [LuxGo instance](https://github.com/luxfi/luxgo/releases/), including environment variables, allowing developers to quickly issue commands to a node and see the response, without having to copy and paste long and complicated `curl` commands.

[Link to GitHub](https://github.com/luxfi/lux-postman-collection/)

What Is Postman?[​](#what-is-postman "Direct link to heading")
--------------------------------------------------------------

Postman is a free tool used by developers to quickly and easily send REST, SOAP, and GraphQL requests and test APIs. It is available as both an online tool and an application for Linux, MacOS and Windows. Postman allows you to quickly issue API calls and see the responses in a nicely formatted, searchable form.

Along with the API collection, there is also the example Lux environment for Postman, that defines common variables such as IP address of the node, Lux addresses and similar common elements of the queries, so you don't have to enter them multiple times.

Combined, they will allow you to easily keep tabs on an Lux node, check on its state and do quick queries to find out details about its operation.

Setup[​](#setup "Direct link to heading")
-----------------------------------------

### Postman Installation[​](#postman-installation "Direct link to heading")

Postman can be installed locally or used as a web app. We recommend installing the application, as it simplifies operation. You can download Postman from its [website](https://www.postman.com/downloads/). It is recommended that you sign up using your email address as then your workspace can be easily backed up and shared between the web app and the app installed on your computer.

![Download Postman](/images/postman1.png)

When you run Postman for the first time, it will prompt you to create an account or log in. Again, it is not necessary, but recommended.

### Collection Import[​](#collection-import "Direct link to heading")

Select `Create workspace` from Workspaces tab and follow the prompts to create a new workspace. This will be where the rest of the work will be done.

![Create workspace](/images/postman2.png)

We're ready to import the collection. On the top-left corner of the Workspaces tab select `Import` and switch to `Link` tab.

![Import collection](/images/postman3.png)

There, in the URL input field paste the link below to the collection:

```bash
https://raw.githubusercontent.com/luxfi/lux-postman-collection/master/Lux.postman_collection.json
```

Postman will recognize the format of the file content and offer to import the file as a collection. Complete the import. Now you will have Lux collection in your Workspace.

![Collection content](/images/postman4.png)

### Environment Import[​](#environment-import "Direct link to heading")

Next, we have to import the environment variables. Again, on the top-left corner of the Workspaces tab select `Import` and switch to `Link` tab. This time, paste the link below to the environment JSON:

```bash
https://raw.githubusercontent.com/luxfi/lux-postman-collection/master/Example-Lux-Environment.postman_environment.json
```

Postman will recognize the format of the file:

![Environment import](/images/postman5.png)

Import it to your workspace. Now, we will need to edit that environment to suit the actual parameters of your particular installation. These are the parameters that differ from the defaults in the imported file.

Select the Environments tab, choose the Lux environment which was just added. You can directly edit any values here:

![Environment content](/images/postman6.png)

As a minimum, you will need to change the IP address of your node, which is the value of the `host` variable. Change it to the IP of your node (change both the `initial` and `current` values). Also, if your node is not running on the same machine where you installed Postman, make sure your node is accepting the connections on the API port from the outside by checking the appropriate [command line option](/docs/nodes/configure/configs-flags#http-server).

Now we sorted everything out, and we're ready to query the node.

Conclusion[​](#conclusion "Direct link to heading")
---------------------------------------------------

If you have completed the tutorial, you are now able to quickly [issue API calls](/docs/tooling/lux-postman/making-api-calls) to your node without messing with the curl commands in the terminal. This allows you to quickly see the state of your node, track changes or double-check the health or liveness of your node.

Contributing[​](#contributing "Direct link to heading")
-------------------------------------------------------

We're hoping to continuously keep this collection up-to-date with the [Lux APIs](/docs/rpcs/p-chain). If you're able to help improve the Lux Postman Collection in any way, first create a feature branch by branching off of `master`, next make the improvements on your feature branch and lastly create a [pull request](https://github.com/luxfi/lux-build/pulls) to merge your work back in to `master`.

If you have any other questions or suggestions, come [talk to us](https://chat.avalabs.org/).

# Making API Calls (/docs/tooling/avalanche-postman/making-api-calls)

---
title: Making API Calls
description: Making API calls using Postman
---

After [installing Postman Collection](/docs/tooling/lux-postman/index) and importing the [Lux collection](/docs/tooling/lux-postman/index#collection-import), you can choose an API to make the call.

You should also make sure the URL is the correct one for the call. This URL consists of the base URL and the endpoint:

- The base URL is set by an environment variable called `baseURL`, and it is by default Lux's [public API](/docs/rpcs#mainnet-rpc---public-api-server). If you need to make a local API call, simply change the URL to localhost. This can be done by changing the value of the `baseURL` variable or changing the URL directly on the call tab. Check out the [RPC providers](/docs/rpcs) to see all public URLs.  
- The API endpoint depends on which API is used. Please check out [our APIs](/docs/rpcs/c-chain) to find the proper endpoint.
    
The last step is to add the needed parameters for the call. For example, if a user wants to fetch data about a certain transaction, the transaction hash is needed. For fetching data about a block, depending on the call used, the block hash or number will be required.

After clicking the **Send** button, if the call is successfully, the output will be displayed in the **Body** tab.

<Callout title="Note">
Data visualization is available for a number of methods. Learn how to use it with the help of [this](/docs/tooling/lux-postman/data-visualization) guide.
</Callout>

![Make Call](/images/api-call1.png)

Examples[​](#examples "Direct link to heading")
-----------------------------------------------

### LUExchange-Chain Public API Call[​](#c-chain-public-api-call "Direct link to heading")

Fetching data about a LUExchange-Chain transaction using `eth_getTransactionByHash`.

<YouTube id="M83WhbXq5R0" fullSize={false}/>

### Exchange-Chain Public API Call[​](#x-chain-public-api-call "Direct link to heading")

Fetching data about an Exchange-Chain block using `xvm.getBlock`.

<YouTube id="4Yu2G3Zvrdo" fullSize={false} params="start=2"/>

### Platform-Chain Public API Call[​](#p-chain-public-api-call "Direct link to heading")

Getting the current Platform-Chain height using `platform.getHeight`.

<YouTube id="9d5VPNcODDw" fullSize={false}/>

### API Call Using Variables[​](#api-call-using-variables "Direct link to heading")

Let's say we want fetch data about this `0x20cb0c03dbbe39e934c7bb04979e3073cc2c93defa30feec41198fde8fabc9b8` LUExchange-Chain transaction using both:

- `eth_getTransactionReceipt` 
- `eth_getTransactionByHash`
    
We can set up an environment variable with the transaction hash as value and use it on both calls.

<Callout title="Note">
Find out more about variables [here](/docs/tooling/lux-postman/variables).
</Callout>

<YouTube id="26xCiawBRjM" fullSize={false}x/>


# Variable Types (/docs/tooling/avalanche-postman/variables)

---
title: Variable Types
description: Variable types for Lux APIs using Postman
---

Variables at different scopes are supported by Postman, as it follows:

- **Global variables**: A global variable can be used with every collection. Basically, it allows user to access data between collections. 
- **Collection variables**: They are available for a certain collection and are independent of an environment.
- **Environment variables**: An environment allows you to use a set of variables, which are called environment variables. Every collection can use an environment at a time, but the same environment can be used with multiple collections. This type of variables make the most sense to use with the Lux Postman collection, therefore an environment file with preset variables is provided
- **Data variables**: Provided by external CSV and JSON files.  
- **Local variables**: Temporary variables that can be used in a script. For example, the returned block number from querying a transaction can be a local variable. It exists only for that request, and it will change when fetching data for another transaction hash.

![](/images/variables1.png)

There are two types of variables:

- **Default type**: Every variable is automatically assigned this type when created.
- **Secret type**: Masks variable's value. It is used to store sensitive data.

<Callout title="Note">
Only default variables are used in the Lux Environment file. To learn more about using the secret type of variables, please checkout the [Postman documentation](https://learning.postman.com/docs/sending-requests/variables/#variable-types).
</Callout>

The [environment variables](/docs/tooling/lux-postman/index#environment-import) can be used to ease the process of making an API call. A variable contains the preset value of an API parameter, therefore it can be used in multiple places without having to add the value manually.

How to Use Variables[​](#how-to-use-variables "Direct link to heading")
-----------------------------------------------------------------------

Let's say we want to use both `eth_getTransactionByHash` and `eth_getTransctionReceipt` for a transaction with the following hash: `0x631dc45342a47d360915ea0d193fc317777f8061fe57b4a3e790e49d26960202`. We can set a variable which contains the transaction hash, and then use it on both API calls. Then, when wanting to fetch data about another transaction, the variable can be updated and the new transaction hash will be used again on both calls.

Below are examples on how to set the transaction hash as variable of each scope.

### Set a Global Variable[​](#set-a-global-variable "Direct link to heading")

Go to Environments

![](/images/variables2.png)

Select Globals

![](/images/variables3.png)

Click on the Add a new variable area

![](/images/variables4.png)

Add the variable name and value. Make sure to use quotes.

![](/images/variables5.png)

Click Save

![](/images/variables6.png)

Now it can be used on any call from any collection

### Set a Collection Variable[​](#set-a-collection-variable "Direct link to heading")

Click on the three dots next to the Lux collection and select Edit

![](/images/variables7.png)

Go to the Variables tab

![](/images/variables8.png)

Click on the Add a new variable area

![](/images/variables9.png)

Add the variable name and value. Make sure to use quotes.

![](/images/variables10.png)

Click Save

![](/images/variables11.png)

Now it can be used on any call from this collection

### Set an Environment Variable[​](#set-an-environment-variable "Direct link to heading")

Go to Environments

![](/images/variables12.png)

Select an environment. In this case, it is Example-Lux-Environment.

![](/images/variables13.png)

Scroll down until you find the Add a new variable area and click on it.

![](/images/variables14.png)

Add the variable name and value. Make sure to use quotes.

![](/images/variables15.png)

Click Save.

![](/images/variables16.png)

The variable is available now for any call collection that uses this environment.

### Set a Data Variable[​](#set-a-data-variable "Direct link to heading")

Please check out [this guide](https://www.softwaretestinghelp.com/postman-variables/#5_Data) and [this video](https://www.youtube.com/watch?v=9wl_UQtRLw4) on how to use data variables.

### Set a Local Variable[​](#set-a-local-variable "Direct link to heading")

Please check out [this guide](https://www.softwaretestinghelp.com/postman-variables/#4_Local) and [this video](https://www.youtube.com/watch?v=gOF7Oc0sXmE) on how to use local variables.

# Overview (/docs/tooling/tmpnet)

---
title: Overview
description: Create and manage temporary Lux networks for local development and testing
---

tmpnet creates temporary Lux networks on your local machine. You get a complete multi-node network with consensus, P2P communication, and pre-funded test keys—everything you need to test custom VMs, L1s, and applications before deploying to testnet or mainnet.

Networks run as native processes (no Docker needed). All configuration lives on disk at `~/.tmpnet/networks/`, making it easy to inspect state, share configs, or debug issues.

## What You Get

| Feature | Description |
|---------|-------------|
| **Multi-node networks** | Spin up 2-50 validator nodes in under a minute |
| **Pre-funded keys** | 50 keys with LUX balances on P, X, and LUExchange-Chain |
| **Custom VMs** | Deploy and test your Virtual Machines |
| **Subnets** | Create subnets with specific validator sets |
| **Monitoring** | Prometheus metrics and Promtail logs out of the box |
| **CLI + Go API** | Use `tmpnetctl` commands or Go code |

## Use Cases

| Scenario | What You Can Test |
|----------|-------------------|
| **L1 Development** | Run your L1 with multiple validators locally before deploying to Testnet |
| **Custom VMs** | Test VM behavior with real consensus across multiple nodes |
| **Staking Operations** | Add validators, test delegation, verify rewards distribution |
| **Subnet Testing** | Create subnets, manage validators, test cross-subnet messaging |
| **Integration Tests** | Write automated Go tests that spin up networks on demand |

## Basic Workflow

```bash
# Start a 5-node network
tmpnetctl start-network --luxgo-path=./bin/luxgo

# Network is running at ~/.tmpnet/networks/latest
# Get node URIs
cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq -r '.uri'

# Get pre-funded keys
cat ~/.tmpnet/networks/latest/config.json | jq -r '.preFundedKeys[0]'

# Stop when done
tmpnetctl stop-network
```

## Network Directory Structure

Each network you create gets its own directory at `~/.tmpnet/networks/[timestamp]/`:

| Path | Contents |
|------|----------|
| `config.json` | Network settings, pre-funded keys |
| `genesis.json` | Genesis configuration |
| `NodeID-*/` | Per-node directories (logs, database, config) |
| `NodeID-*/process.json` | Running node info (PID, URI, ports) |
| `metrics.txt` | Grafana dashboard link |

The `latest` symlink always points to your most recent network.

Both `tmpnetctl` and your Go code can manage the same networks because everything is file-based. No daemon, no Docker, no magic.

## Getting Started

<Cards>
  <Card title="Installation" href="/docs/tooling/tmpnet/installation">
    Build tmpnet and luxgo
  </Card>
  <Card title="Quick Start" href="/docs/tooling/tmpnet/quick-start">
    Create your first network
  </Card>
  <Card title="Testing Custom VMs" href="/docs/tooling/tmpnet/guides/testing-custom-vms">
    Deploy your VM to a local network
  </Card>
  <Card title="Staking & Delegation" href="/docs/tooling/tmpnet/guides/staking-and-delegation">
    Test validator operations
  </Card>
</Cards>

## Support & Resources

- [GitHub Repository](https://github.com/luxfi/luxgo/tree/master/tests/fixture/tmpnet)
- [Full README](https://github.com/luxfi/luxgo/blob/master/tests/fixture/tmpnet/README.md)
- [Discord Community](https://chat.avalabs.org/)
- [Documentation](https://docs.lux.network/)


# Installation (/docs/tooling/tmpnet/installation)

---
title: Installation
description: Set up tmpnet and its prerequisites for local network testing
---

This guide walks you through setting up tmpnet for testing your Lux applications and L1s.

## Prerequisites

### 1. Operating System

tmpnet runs on:
- **macOS** (Intel and Apple Silicon)
- **Linux**

Windows is not currently supported.

### 2. Go

tmpnet requires **Go 1.21 or later**. Check your version:

```bash
go version
```

If you need to install or update Go, visit [golang.org/dl](https://golang.org/dl/).

### 3. Git

Ensure you have Git installed:

```bash
git --version
```

## Installation

### Step 1: Clone LuxGo

tmpnet is part of the LuxGo repository:

```bash
# Clone the repository
git clone https://github.com/luxfi/luxgo.git
cd luxgo
```

### Step 2: Build the Binaries

Build both LuxGo and tmpnetctl:

```bash
# Build LuxGo
./scripts/build.sh

# Build tmpnetctl
./scripts/build_tmpnetctl.sh
```

You now have:
- `build/luxgo` and `build/tmpnetctl` - compiled binaries
- `bin/luxgo` and `bin/tmpnetctl` - thin wrappers that rebuild if needed

### Step 3: Verify Installation

Test that the binaries work:

```bash
# Check LuxGo
./bin/luxgo --version

# Check tmpnetctl
./bin/tmpnetctl --help
```

You should see version information and available commands.

## Understanding the Directory Structure

LuxGo has two directories for binaries:

### `build/` Directory (Actual Binaries)
Contains the compiled binaries:
- `build/luxgo` - Main node binary
- `build/tmpnetctl` - Network management CLI
- `build/plugins/` - Custom VM plugins

### `bin/` Directory (Convenience Wrappers)
Symlinks that rebuild when needed, so they're safe defaults while iterating:
- `bin/luxgo` → `scripts/run_luxgo.sh`
- `bin/tmpnetctl` → `scripts/run_tmpnetctl.sh`

For most workflows (and in the upstream README), use the `bin/` wrappers or enable the repo's `.envrc` so `tmpnetctl` is on your `PATH`.

## Optional: Simplified Setup with direnv

[direnv](https://direnv.net/) automatically loads the repo's `.envrc` so tmpnet has the paths it needs.

### Install and Configure

**macOS:**
```bash
brew install direnv
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc
```

**Linux:**
```bash
# Ubuntu/Debian
sudo apt-get install direnv

# Add to shell
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc
```

### Enable in LuxGo

```bash
cd /path/to/luxgo
direnv allow
```

The repo's `.envrc` then:
- Adds `bin/` to `PATH` so you can run `tmpnetctl` directly
- Sets `LUXGO_PATH=$PWD/bin/luxgo`
- Sets `AVAGO_PLUGIN_DIR=$PWD/build/plugins` (and creates the dir)
- Sets `TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest`

Now you can run:
```bash
tmpnetctl start-network --node-count=3
```

## Optional: Monitoring Tools

To collect metrics and logs from your networks:

**Using Nix (Recommended):**
```bash
nix develop  # Provides prometheus and promtail
```

**Manual Installation:**
- **Prometheus**: Download from [prometheus.io/download](https://prometheus.io/download/) or `brew install prometheus`
- **Promtail**: Download from [Grafana Loki releases](https://github.com/grafana/loki/releases)

See the [Monitoring guide](/docs/tooling/tmpnet/guides/monitoring) for setup details.

## Environment Variables

Key environment variables tmpnet uses:

| Variable | Purpose | Default |
|----------|---------|---------|
| `LUXGO_PATH` | Path to luxgo binary (required unless passed as `--luxgo-path`) | None |
| `AVAGO_PLUGIN_DIR` | Plugin directory for custom VMs | `~/.luxgo/plugins` (or `$PWD/build/plugins` via `.envrc`) |
| `TMPNET_ROOT_NETWORK_DIR` | Where new networks are created | `~/.tmpnet/networks` |
| `TMPNET_NETWORK_DIR` | Existing network to target for stop/restart/check commands | Unset (set automatically by `network.env` or `.envrc`) |

### Recommended Shell Setup

If you aren't using direnv, add something like this to `~/.bashrc` or `~/.zshrc`:

```bash
export LUXGO_PATH=~/luxgo/bin/luxgo
export AVAGO_PLUGIN_DIR=~/.luxgo/plugins
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest  # optional convenience
export PATH=$PATH:~/luxgo/bin
```

## Plugin Directory Setup

If you're testing custom VMs, create the plugin directory:

```bash
mkdir -p ~/.luxgo/plugins
```

Place your custom VM binaries in this directory. The plugin binary name should match your VM name.

## Troubleshooting

### Command not found: tmpnetctl

If you get "command not found":

**Option 1:** Use the full path
```bash
./bin/tmpnetctl --help
```

**Option 2:** Add to PATH
```bash
export PATH=$PATH:$(pwd)/bin
tmpnetctl --help
```

**Option 3:** Use direnv (recommended)
```bash
direnv allow
tmpnetctl --help
```

### Build Failures

If builds fail:

1. **Check Go version:**
   ```bash
   go version  # Must be 1.21 or later
   ```

2. **Check you're in the repository root:**
   ```bash
   pwd  # Should be /path/to/luxgo
   ls scripts/build.sh  # Should exist
   ```

3. **Try cleaning and rebuilding:**
   ```bash
   rm -rf build/
   ./scripts/build.sh
   ```

### Permission Denied

If you get permission errors:

```bash
chmod +x ./bin/tmpnetctl
chmod +x ./bin/luxgo
```

### Binary Not Found Error

If tmpnetctl says luxgo not found:

```bash
# Verify the binary exists
ls -lh ./bin/luxgo

# Use absolute path when starting networks
tmpnetctl start-network --luxgo-path="$(pwd)/bin/luxgo"
```

## Next Steps

Now that tmpnet is installed, create your first network!

<Cards>
  <Card title="Quick Start" href="/docs/tooling/tmpnet/quick-start">
    Start your first temporary network in minutes
  </Card>
  <Card title="Test Custom VMs" href="/docs/tooling/tmpnet/guides/testing-custom-vms">
    Learn how to test your custom VM or L1
  </Card>
</Cards>


# Quick Start (/docs/tooling/tmpnet/quick-start)

---
title: Quick Start
description: Start your first temporary Lux network in minutes
---

This guide will help you create, interact with, and manage your first temporary network using tmpnet.

## Before You Start

Make sure you've completed the [installation](/docs/tooling/tmpnet/installation) and have:
- Built `luxgo` and `tmpnetctl`
- A shell in the luxgo repo root
- Either `direnv allow`'d the repo **or** can pass `--luxgo-path`

## Start Your First Network

### Basic Start Command

Start a 2-node network (default is 5):

```bash
cd /path/to/luxgo

# If you enabled direnv (.envrc sets paths)
tmpnetctl start-network --node-count=2

# Without direnv, pass the luxgo path explicitly
./bin/tmpnetctl start-network \
  --luxgo-path="$(pwd)/bin/luxgo" \
  --node-count=2
```

**Expected Output:**
```
[12-05|15:23:26.831] INFO tmpnet/network.go:254 preparing configuration for new network
[12-05|15:23:26.839] INFO tmpnet/network.go:385 starting network {"networkDir": "/Users/you/.tmpnet/networks/20251205-152326.831812", "uuid": "0ef20abc-4d96-438f-943c-a4442254b9bb"}
[12-05|15:23:27.992] INFO tmpnet/process_runtime.go:148 started local node {"nodeID": "NodeID-Pw8tmrG..."}
[12-05|15:23:28.395] INFO tmpnet/process_runtime.go:148 started local node {"nodeID": "NodeID-KBxAJo5..."}
[12-05|15:23:28.396] INFO tmpnet/network.go:400 waiting for nodes to report healthy
[12-05|15:23:30.399] INFO tmpnet/network.go:976 node is healthy {"nodeID": "NodeID-KBxAJo5...", "uri": "http://127.0.0.1:56395"}
[12-05|15:23:33.999] INFO tmpnet/network.go:976 node is healthy {"nodeID": "NodeID-Pw8tmrG...", "uri": "http://127.0.0.1:56386"}
[12-05|15:23:33.999] INFO tmpnet/network.go:404 started network

Configure tmpnetctl to target this network by default with one of the following statements:
 - source /Users/you/.tmpnet/networks/20251205-152326.831812/network.env
 - export TMPNET_NETWORK_DIR=/Users/you/.tmpnet/networks/20251205-152326.831812
 - export TMPNET_NETWORK_DIR=/Users/you/.tmpnet/networks/latest
```

The network is now running with 2 validator nodes!

### With direnv (Simpler)

If you've set up direnv:

```bash
cd /path/to/luxgo
direnv allow

# Much simpler!
tmpnetctl start-network --node-count=2
```

## Configure Your Shell

To manage your network without specifying `--network-dir` every time, set `TMPNET_NETWORK_DIR`:

```bash
# Option 1: Use the 'latest' symlink (recommended)
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest
```

The `latest` symlink always points to the most recently created network. Now you can run commands without flags:

```bash
tmpnetctl stop-network    # Uses TMPNET_NETWORK_DIR
tmpnetctl restart-network
```

**Make it permanent** by adding to your shell config:

```bash
# For zsh (macOS)
echo 'export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest' >> ~/.zshrc
source ~/.zshrc

# For bash (Linux)
echo 'export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest' >> ~/.bashrc
source ~/.bashrc
```

**Alternative**: Source the network's env file directly:
```bash
source ~/.tmpnet/networks/latest/network.env
```

## Explore Your Network

### Network Directory Structure

```bash
ls ~/.tmpnet/networks/latest/
```

**Output:**
```
config.json                                    # Network configuration
genesis.json                                   # Genesis file
metrics.txt                                    # Grafana dashboard link
network.env                                    # Environment setup script
NodeID-74mGyq7dVVCeE4RUn4pufRMvYTFTEykcp/    # Node 1 directory
NodeID-BTtC98RhLA5mbctKczZQC2Rt6N9DziM4c/    # Node 2 directory
```

### Find Node API Endpoints

Each node exposes API endpoints on dynamically allocated ports. When tmpnet starts a node with `--http-port=0`, the OS assigns an available port. LuxGo then writes the actual allocated port to `process.json` via the `--process-context-file` flag.

<Callout type="info" title="How process.json is created">
The `process.json` file is created by **luxgo itself**, not by tmpnetctl. When tmpnet starts a node, it passes:
- `--http-port=0` and `--staking-port=0` for dynamic port allocation
- `--process-context-file=[node-dir]/process.json` to specify where luxgo should write runtime info

LuxGo then writes its PID, URI (with the actual allocated port), and staking address to this file once it starts.
</Callout>

```bash
# View all node URIs
cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq -r '.uri'
```

**Example output:**
```
http://127.0.0.1:56395
http://127.0.0.1:56386
```

### Get a Single Node URI

```bash
# Store first node URI in a variable
NODE_URI=$(cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq -r '.uri' | head -1)
echo $NODE_URI
```

### Call Node RPCs

Use the URI to call standard Lux APIs over HTTP:

```bash
# Health
curl -s "$NODE_URI/ext/health" | jq '.healthy'

# Node ID
curl -s -X POST --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "info.getNodeID"
}' -H 'content-type:application/json;' "$NODE_URI/ext/info" | jq

# LUExchange-Chain RPC (replace with your chain ID if different)
CHAIN_ID=C
curl -s -X POST --data '{
  "jsonrpc":"2.0",
  "id":1,
  "method":"eth_blockNumber",
  "params":[]
}' -H 'content-type:application/json;' "$NODE_URI/ext/bc/$CHAIN_ID/rpc" | jq
```

## Interact with Your Network

### Check Node Health

```bash
curl -s http://127.0.0.1:56395/ext/health | jq '.healthy'
```

**Response:**
```json
true
```

### Get Node Information

```bash
curl -s -X POST --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "info.getNodeID"
}' -H 'content-type:application/json;' http://127.0.0.1:56395/ext/info | jq
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-74mGyq7dVVCeE4RUn4pufRMvYTFTEykcp",
    "nodePOP": {
      "publicKey": "...",
      "proofOfPossession": "..."
    }
  },
  "id": 1
}
```

### Check Network Info

```bash
curl -s -X POST --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "info.getNetworkID"
}' -H 'content-type:application/json;' http://127.0.0.1:56395/ext/info | jq
```

## Use Pre-funded Keys

Every tmpnet network comes with **50 pre-funded test keys** ready for immediate use. These keys have large balances on all chains (Exchange-Chain, Platform-Chain, and LUExchange-Chain).

### View Pre-funded Keys

```bash
cat ~/.tmpnet/networks/latest/config.json | jq '.preFundedKeys'
```

**Example output:**
```json
[
  "PrivateKey-ewoqjP7PxY4yr3iLTpLisriqt94hdyDFNgchSxGGztUrTXtNN",
  "PrivateKey-2VbLJLjPJn4XA8UqQ4BjmF5LmkZj4EZ2dXLKmKPmXTbKHvvQh6",
  "PrivateKey-R6e8f5QSa89DjpvL9asNdhdJ4u8VqzMJStPV8VVdDmLgPd8x4",
  ...
]
```

### Get a Single Key for Testing

```bash
# Store the first pre-funded key
TEST_KEY=$(cat ~/.tmpnet/networks/latest/config.json | jq -r '.preFundedKeys[0]')
echo $TEST_KEY
# Output: PrivateKey-ewoqjP7PxY4yr3iLTpLisriqt94hdyDFNgchSxGGztUrTXtNN
```

### What Are These Keys Funded With?

Each key has balances on:
- **Platform-Chain** - For staking and subnet operations
- **Exchange-Chain** - For asset transfers
- **LUExchange-Chain** - For EVM transactions (contract deployments, etc.)

You can use these keys immediately for transactions, contract deployments, staking operations, and validator management.

## Use with Foundry/Cast

tmpnet networks work with standard EVM tools like Foundry. Here's how to connect.

### Set Up Environment Variables

```bash
# Get the first node's URI and construct the LUExchange-Chain RPC URL
NODE_URI=$(cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq -r '.uri' | head -1)
export RPC_URL="${NODE_URI}/ext/bc/C/rpc"
echo $RPC_URL
# Example: http://127.0.0.1:56395/ext/bc/C/rpc
```

### The EWOQ Test Key

Every tmpnet network includes the well-known EWOQ test key, pre-funded with LUX:

| Property | Value |
|----------|-------|
| Private Key (hex) | `56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027` |
| Address | `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` |
| LUExchange-Chain Balance | 50,000,000 LUX |

```bash
export PRIVATE_KEY="56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027"
```

<Callout type="warning" title="Test Key Only">
The EWOQ key is publicly known. Never use it on Testnet or Mainnet—only for local development.
</Callout>

### Common Cast Commands

```bash
# Check balance
cast balance 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC --rpc-url $RPC_URL

# Get chain ID
cast chain-id --rpc-url $RPC_URL

# Get latest block
cast block-number --rpc-url $RPC_URL

# Send LUX to another address
cast send 0xYourAddress --value 1ether \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY
```

### Deploy Contracts with Forge

```bash
# Deploy a contract
forge create src/MyContract.sol:MyContract \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY

# Run a deployment script
forge script script/Deploy.s.sol \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast
```

### Chain Configuration

For `foundry.toml`:

```toml
[rpc_endpoints]
local = "http://127.0.0.1:56395/ext/bc/C/rpc"

[etherscan]
# No explorer for local networks
```

<Callout type="info" title="Dynamic Ports">
Remember that tmpnet uses dynamic ports. If you restart your network, the port may change. Always re-export `RPC_URL` after restarting.
</Callout>

## View Network Configuration

### Network Configuration

```bash
cat ~/.tmpnet/networks/latest/config.json | jq '{
  uuid,
  owner,
  preFundedKeyCount: (.preFundedKeys | length)
}'
```

### Genesis Configuration

```bash
cat ~/.tmpnet/networks/latest/genesis.json | jq '.networkID'
```

### Node Configuration

```bash
# View node flags
cat ~/.tmpnet/networks/latest/NodeID-*/flags.json | head -1 | jq

# View node runtime config
cat ~/.tmpnet/networks/latest/NodeID-*/config.json | head -1 | jq
```

## Manage Your Network

### Stop the Network

```bash
tmpnetctl stop-network
```

**Output:**
```
Stopped network configured at: /Users/you/.tmpnet/networks/latest
```

### Restart the Network

```bash
tmpnetctl restart-network
```

This preserves all network data and configuration, restarting with the same genesis and keys.

### Start a New Network

```bash
# This creates a completely new network with new keys
tmpnetctl start-network \
  --luxgo-path="$(pwd)/bin/luxgo" \
  --node-count=3
```

## View Node Logs

### Watch Logs in Real-time

```bash
# Watch all node logs
tail -f ~/.tmpnet/networks/latest/NodeID-*/logs/main.log

# Watch a specific node
tail -f ~/.tmpnet/networks/latest/NodeID-74mGyq7dVVCeE4RUn4pufRMvYTFTEykcp/logs/main.log
```

### Search Logs for Errors

```bash
grep -i "error" ~/.tmpnet/networks/latest/NodeID-*/logs/main.log
```

### View Recent Log Lines

```bash
tail -50 ~/.tmpnet/networks/latest/NodeID-*/logs/main.log
```

## Common Operations

### Check Running Processes

```bash
# View all node processes
ps aux | grep luxgo

# Count running nodes
ps aux | grep luxgo | grep -v grep | wc -l
```

### Get All Node URIs at Once

```bash
# Create a simple script
for process_file in ~/.tmpnet/networks/latest/NodeID-*/process.json; do
  jq -r '.uri' "$process_file"
done
```

### Check Node Process Details

```bash
# View process information for all nodes
cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq '{
  pid,
  uri,
  stakingAddress
}'
```

## Directory Structure Reference

```
~/.tmpnet/networks/latest/
├── config.json                  # Network configuration (owner, UUID, keys)
├── genesis.json                 # Genesis file with allocations
├── metrics.txt                  # Grafana dashboard link
├── network.env                  # Shell environment variables
└── NodeID-<ID>/                 # Per-node directory
    ├── config.json              # Node runtime configuration
    ├── flags.json               # Node flags
    ├── process.json             # Process info (PID, URIs, ports)
    ├── logs/
    │   └── main.log             # Node logs
    ├── db/                      # Node database
    └── chainData/               # Chain data
```

## Troubleshooting

### Network Won't Start

**Error: `luxgo binary not found`**

Solution:
```bash
# Verify binary exists
ls -lh ./bin/luxgo

# Use absolute path
tmpnetctl start-network \
  --luxgo-path="$(pwd)/bin/luxgo"
```

**Error: `address already in use`**

Solution:
```bash
# Check for running nodes
ps aux | grep luxgo

# Stop existing network
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest
tmpnetctl stop-network
```

### Can't Connect to Nodes

**Issue:** Curl commands fail

Solution:
```bash
# 1. Verify nodes are running
ps aux | grep luxgo

# 2. Check actual URIs
cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq -r '.uri'

# 3. Test health endpoint with correct URI
curl http://127.0.0.1:<actual-port>/ext/health
```

### Missing process.json Files

**Issue:** `process.json` files don't exist in node directories, or ports in `flags.json` are all `0`

This happens when running luxgo manually without the `--process-context-file` flag.

**Understanding the issue:**
- `flags.json` showing `"http-port": "0"` is correct - this tells the OS to allocate a dynamic port
- `process.json` is created by **luxgo itself** when started with the `--process-context-file` flag
- tmpnetctl automatically passes this flag, but manual setups need to include it

**Solution for manual luxgo setups:**
```bash
# When starting luxgo manually with dynamic ports, include:
luxgo \
  --http-port=0 \
  --staking-port=0 \
  --process-context-file=/path/to/node/process.json \
  # ... other flags

# LuxGo will write the actual allocated ports to process.json
```

**If using tmpnetctl:** The `process.json` files should be created automatically. If they're missing, ensure:
1. The network started successfully (check for "started network" in output)
2. Nodes are still running (`ps aux | grep luxgo`)
3. You're looking in the correct network directory

### Command Not Found

**Error: `tmpnetctl: command not found`**

Solution:
```bash
# Use full path
./bin/tmpnetctl --help

# Or add to PATH
export PATH=$PATH:$(pwd)/bin
tmpnetctl --help

# Or use direnv
direnv allow
tmpnetctl --help
```

### Clean Up Everything

To remove all networks and start fresh:

```bash
# Stop any running networks
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest
tmpnetctl stop-network

# Remove all tmpnet data (optional)
rm -rf ~/.tmpnet/networks
```

## Next Steps

Now that you have a running network, learn how to:

<Cards>
  <Card title="Test Custom VMs" href="/docs/tooling/tmpnet/guides/testing-custom-vms">
    Deploy and test your custom Virtual Machine
  </Card>
  <Card title="Subnet Testing" href="/docs/tooling/tmpnet/guides/subnet-testing">
    Create and test custom subnets
  </Card>
  <Card title="Runtime Environments" href="/docs/tooling/tmpnet/guides/runtimes">
    Choose between local and Kubernetes runtimes
  </Card>
  <Card title="Monitoring" href="/docs/tooling/tmpnet/guides/monitoring">
    Set up metrics and log collection
  </Card>
</Cards>


# Troubleshooting Runtime Issues (/docs/tooling/tmpnet/troubleshooting-runtime)

---
title: Troubleshooting Runtime Issues
description: Diagnose and resolve common tmpnet runtime issues for local processes and Kubernetes deployments
---

This guide helps you diagnose and resolve common issues with tmpnet's different runtime environments. Issues are organized by runtime type for quick reference.

## Local Process Runtime Issues

### Port Conflicts

**Symptom:** Error messages like "address already in use" or "bind: address already in use" when starting a network.

**Cause:** A previous network is still running, or another application is using the ports.

**Solution:**

```bash
# Check for orphaned luxgo processes
ps aux | grep luxgo

# Kill any orphaned processes
pkill -f luxgo

# Verify ports are free
lsof -i :9650-9660
```

**Prevention:** Always use dynamic port allocation by setting ports to "0":

```go
network.DefaultFlags = tmpnet.FlagsMap{
    "http-port":    "0",  // Let OS assign available port
    "staking-port": "0",  // Let OS assign available port
}
```

<Callout type="warning">
Avoid hardcoding port numbers unless you have a specific reason. Dynamic ports prevent conflicts when running multiple networks or tests concurrently.
</Callout>

### Process Not Stopping

**Symptom:** After calling `network.Stop()`, luxgo processes remain running in the background.

**Cause:** Process termination may fail silently, or cleanup may not complete properly.

**Solution:**

```bash
# Find all luxgo processes
ps aux | grep luxgo

# Try graceful termination first
pkill -TERM -f luxgo
sleep 5

# If processes still running, force kill as last resort
pkill -9 -f luxgo

# Clean up temporary directories if needed
# First verify which network you want to delete
ls -lt ~/.tmpnet/networks/
# Then delete the specific network directory
rm -rf ~/.tmpnet/networks/20250312-143052.123456
```

<Callout type="warning">
Use `pkill -9` (SIGKILL) only as a last resort after graceful termination fails. SIGKILL doesn't allow cleanup and can leave the database in an inconsistent state.
</Callout>

**Prevention:** Always use context with timeout for Stop operations:

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

if err := network.Stop(ctx); err != nil {
    // Log error but continue cleanup
    log.Printf("Failed to stop network cleanly: %v", err)
}
```

### Binary Not Found

**Symptom:** Error "luxgo not found" or "executable file not found in $PATH" when starting nodes.

**Cause:** The luxgo binary path is incorrect or not specified.

**Solution:**

```bash
# Verify the binary exists
ls -lh /path/to/luxgo

# Use absolute path when configuring
export LUXGO_PATH="$(pwd)/bin/luxgo"

# Or specify in code
runtimeCfg := &tmpnet.ProcessRuntimeConfig{
    LuxGoPath: "/absolute/path/to/luxgo",
}
```

**Verification:**

```bash
# Test the binary works
/path/to/luxgo --version

# Should output version information
```

<Callout type="info">
When using relative paths, ensure they resolve correctly from your test working directory. Absolute paths are more reliable for test automation.
</Callout>

### Logs Location

**Where to find logs:** Node logs are stored in the network directory under each node's subdirectory.

```bash
# Find the latest network
ls -lt ~/.tmpnet/networks/

# Use the 'latest' symlink
tail -f ~/.tmpnet/networks/latest/NodeID-*/logs/main.log

# Or specify the timestamp directory
tail -f ~/.tmpnet/networks/20250312-143052.123456/NodeID-7Xhw2mX5xVHr1ANraYiTgjuB8Jqdbj8/logs/main.log
```

**Useful log commands:**

```bash
# View all node logs simultaneously
tail -f ~/.tmpnet/networks/latest/NodeID-*/logs/main.log

# Search for errors across all nodes
grep -r "ERROR" ~/.tmpnet/networks/latest/*/logs/

# Monitor a specific node
export NODE_ID="NodeID-7Xhw2mX5xVHr1ANraYiTgjuB8Jqdbj8"
tail -f ~/.tmpnet/networks/latest/$NODE_ID/logs/main.log
```

## Kubernetes Runtime Issues

### Pod Stuck in Pending

**Symptom:** Node pods remain in "Pending" state and never start.

**Common causes:**
- Insufficient cluster resources (CPU/memory)
- Node selector constraints not met
- Storage class unavailable
- Image pull errors (see below)

**Diagnosis:**

```bash
# Check pod status details
kubectl describe pod luxgo-node-0 -n tmpnet

# Look for events section
kubectl get events -n tmpnet --sort-by='.lastTimestamp'

# Check node resources
kubectl top nodes
```

**Solutions:**

```bash
# If resource limits are too high, adjust them
kubectl edit statefulset luxgo -n tmpnet

# Verify your cluster has available nodes
kubectl get nodes

# Check for node taints
kubectl describe nodes | grep -i taint
```

### Image Pull Errors

**Symptom:** Pod status shows "ImagePullBackOff" or "ErrImagePull".

**Cause:** Cannot pull the Docker image from the registry.

**Diagnosis:**

```bash
# Check image pull status
kubectl describe pod luxgo-node-0 -n tmpnet | grep -A 5 "Events:"

# Verify image name
kubectl get pod luxgo-node-0 -n tmpnet -o jsonpath='{.spec.containers[0].image}'
```

**Solutions:**

```bash
# Verify image exists in registry
docker pull avaplatform/luxgo:latest

# If using private registry, check image pull secrets
kubectl get secrets -n tmpnet

# Create image pull secret if needed
kubectl create secret docker-registry regcred \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password> \
  -n tmpnet
```

**Alternative:** Use a local image with kind:

```bash
# Load image into kind cluster
kind load docker-image avaplatform/luxgo:latest --name tmpnet-cluster
```

### Ingress Not Working

**Symptom:** Cannot reach node APIs through ingress endpoints, connection refused or timeouts.

**Cause:** Ingress controller not installed, misconfigured, or ingress rules not applied.

**Diagnosis:**

```bash
# Check if ingress controller is running
kubectl get pods -n ingress-nginx

# Verify ingress resource exists
kubectl get ingress -n tmpnet

# Check ingress details
kubectl describe ingress luxgo-ingress -n tmpnet

# Test service directly (bypassing ingress)
kubectl port-forward svc/luxgo-node-0 9650:9650 -n tmpnet
curl http://localhost:9650/ext/health
```

**Solutions:**

```bash
# Install ingress controller if missing
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml

# Verify ingress host configuration
kubectl get ingress -n tmpnet -o yaml | grep host:

# Check service endpoints
kubectl get endpoints -n tmpnet
```

<Callout type="warning">
For kind clusters, ensure you created the cluster with `extraPortMappings` to expose ports 80/443. See the [kind ingress documentation](https://kind.sigs.k8s.io/docs/user/ingress/).
</Callout>

### StatefulSet Not Updating

**Symptom:** After updating the StatefulSet (e.g., changing image version), pods still run the old image.

**Cause:** StatefulSet update strategy is set to `OnDelete` by default, requiring manual pod deletion.

**Solution:**

```bash
# Check update strategy
kubectl get statefulset luxgo -n tmpnet -o jsonpath='{.spec.updateStrategy}'

# Manually delete pods to trigger update
kubectl delete pod luxgo-node-0 -n tmpnet
# StatefulSet will recreate with new image

# Or delete all pods
kubectl delete pods -l app=luxgo -n tmpnet
```

**Change to rolling updates:**

```bash
kubectl patch statefulset luxgo -n tmpnet -p '{"spec":{"updateStrategy":{"type":"RollingUpdate"}}}'
```

### Persistent Volume Issues

**Symptom:** Pod cannot start with error "FailedMount" or "PVC not bound".

**Cause:** Persistent Volume Claims (PVCs) cannot be provisioned or bound.

**Diagnosis:**

```bash
# Check PVC status
kubectl get pvc -n tmpnet

# Should show "Bound" status
# If "Pending", check details
kubectl describe pvc data-luxgo-node-0 -n tmpnet

# Verify storage class exists
kubectl get storageclass
```

**Solutions:**

```bash
# If using kind or minikube, ensure default storage class exists
kubectl get storageclass

# For kind, standard storage class should be available by default
# For custom clusters, install a storage provisioner

# Delete stuck PVCs if needed (will delete data!)
kubectl delete pvc data-luxgo-node-0 -n tmpnet
```

## General Runtime Issues

### Health Check Failures

**Symptom:** Node reports as unhealthy or `IsHealthy()` returns false in tests.

**Cause:** Node may still be bootstrapping, or there's a configuration issue.

**Health check endpoint:** `GET /ext/health/liveness` on the HTTP port.

**Diagnosis:**

```bash
# Check health endpoint directly
curl http://localhost:9650/ext/health/liveness

# Expected healthy response:
# {"checks":{"network":{"message":{"..."},"timestamp":"...","duration":123,"contiguousFailures":0,"timeOfFirstFailure":null}},"healthy":true}

# Check if node is still bootstrapping
curl http://localhost:9650/ext/info | jq '.result.isBootstrapped'
```

**Solutions:**

Wait longer - bootstrapping can take time:

```go
// Use generous timeout for health checks
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

err := node.WaitForHealthy(ctx)
if err != nil {
    return fmt.Errorf("node failed to become healthy: %w", err)
}
```

Check logs for errors:

```bash
# Look for bootstrap progress
tail -f ~/.tmpnet/networks/latest/NodeID-*/logs/main.log | grep -i "bootstrap"

# Check for errors
tail -f ~/.tmpnet/networks/latest/NodeID-*/logs/main.log | grep -i "error"
```

<Callout type="info">
The first node in a network typically takes longer to start because it must wait for staking to be enabled. Subsequent nodes bootstrap from the first node.
</Callout>

### Monitoring Not Working

**Symptom:** No metrics or logs appear in Prometheus/Grafana/Loki dashboards.

**Diagnosis:**

```bash
# Check if collectors are running
ps aux | grep prometheus
ps aux | grep promtail

# Verify environment variables
echo $PROMETHEUS_URL
echo $LOKI_URL

# Check service discovery configs exist
ls -la ~/.tmpnet/prometheus/file_sd_configs/
ls -la ~/.tmpnet/promtail/file_sd_configs/
```

**Solutions:**

```bash
# Start collectors if not running
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector

# Verify binaries are in PATH
which prometheus
which promtail

# If using nix, ensure development shell is active
nix develop

# Check collector logs
tail -f ~/.tmpnet/prometheus/*.log
tail -f ~/.tmpnet/promtail/*.log
```

**Verify metrics are being collected:**

```bash
# Query Prometheus directly
curl -s "${PROMETHEUS_URL}/api/v1/query?query=up" \
  -u "${PROMETHEUS_USERNAME}:${PROMETHEUS_PASSWORD}" \
  | jq
```

## Performance Troubleshooting

### Slow Network Bootstrap

**Symptom:** Network takes longer than 5 minutes to bootstrap.

**Common causes:**
- Network too large (many nodes/subnets)
- Insufficient system resources
- Debug logging enabled

**Solutions:**

Reduce network size for testing:

```go
// Use fewer nodes for faster tests
network.Nodes = tmpnet.NewNodesOrPanic(3) // Instead of 5+
```

Reduce logging verbosity:

```go
network.DefaultFlags = tmpnet.FlagsMap{
    "log-level": "info", // Instead of "debug" or "trace"
}
```

Increase system resources:

```bash
# Check current resource usage
top
df -h ~/.tmpnet/

# Clean up old networks
rm -rf ~/.tmpnet/networks/202*
```

### High Memory Usage

**Symptom:** luxgo processes consume excessive memory, system becomes slow.

**Diagnosis:**

```bash
# Check memory usage per process
ps aux | grep luxgo | awk '{print $2, $4, $11}'

# Monitor over time
watch -n 5 'ps aux | grep luxgo'
```

**Solutions:**

Limit database size:

```go
network.DefaultFlags = tmpnet.FlagsMap{
    "db-type":                    "memdb",  // Use in-memory DB for tests
    "pruning-enabled":            "true",
    "state-sync-enabled":         "false",  // Disable if not needed
}
```

Stop old networks:

```bash
# Stop all running networks
for dir in ~/.tmpnet/networks/*/; do
    export TMPNET_NETWORK_DIR="$dir"
    tmpnetctl stop-network
done
```

## Debugging Techniques

### Enable Verbose Logging

Increase log verbosity to diagnose issues:

```go
node.Flags = tmpnet.FlagsMap{
    "log-level":         "trace",  // Most verbose
    "log-display-level": "trace",
}
```

### Capture Process Output

Redirect process output to see initialization errors:

```bash
# Run luxgo manually with same config
/path/to/luxgo \
  --config-file=~/.tmpnet/networks/latest/NodeID-*/flags.json \
  2>&1 | tee luxgo-debug.log
```

### Network State Inspection

Inspect the network state directory:

```bash
# View network configuration
cat ~/.tmpnet/networks/latest/config.json | jq

# View node flags
cat ~/.tmpnet/networks/latest/NodeID-*/flags.json | jq

# Check process status
cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq
```

### Test Individual Components

Test components in isolation:

```go
// Test just node health
func TestNodeHealth(t *testing.T) {
    node := network.Nodes[0]

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    err := node.WaitForHealthy(ctx)
    require.NoError(t, err)
}
```

## Getting Help

If you're still experiencing issues:

1. **Check logs** - Always check node logs first for error messages
2. **Search GitHub issues** - Check [luxgo issues](https://github.com/luxfi/luxgo/issues) for similar problems
3. **Ask the community** - Post in [Lux Discord](https://chat.lux.network) #developers channel
4. **Include details** - Share error messages, logs, and your configuration

**Information to include when asking for help:**

- tmpnet version: `go list -m github.com/luxfi/luxgo`
- Runtime type: Local process or Kubernetes
- Operating system and version
- Error messages and relevant log excerpts
- Network configuration (redact sensitive data)
- Steps to reproduce the issue

## Next Steps

<Cards>
  <Card title="Configuration Reference" href="/docs/tooling/tmpnet/reference/configuration">
    Complete configuration options
  </Card>
  <Card title="Monitoring Guide" href="/docs/tooling/tmpnet/guides/monitoring">
    Set up metrics and logging
  </Card>
  <Card title="Getting Started" href="/docs/tooling/tmpnet/guides/getting-started">
    Start with the basics
  </Card>
</Cards>


# Track ERC-20 Transfers (/docs/api-reference/webhook-api/tutorials/erc20transfer)

---
title: Track ERC-20 Transfers
description: How to track ERC-20 transfers with the Webhooks API
icon: Coins
---

In a smart contract, events serve as notifications of specific occurrences, like transactions, or changes in ownership. Each event is uniquely identified by its event signature, which is calculated using the keccak 256 hash of the event name and its input argument types.

For example, for an ERC-20 transfer event, the event signature is determined by taking the hash of `Transfer(address,address,uint256)`. To compute this hash yourself, you can use an online `keccak-256` converter and you’ll see that the hexadecimal representation of Transfer(address,address,uint256) is 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef. For a full list of signatures check [https://www.4byte.directory/event-signatures/](https://www.4byte.directory/event-signatures/).

Take into consideration that the Transfer event for ERC-20 and ERC-721 tokens is similar. Here is the Transfer event prototype on each standard:

* **ERC20**:\
  `event Transfer(address indexed _from, address indexed _to, uint256 _value);`
* **ERC721**:\
  `event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);`

These two signatures are indeed the same when you hash them to identify `Transfer` events. The example below illustrates how to set up filtering to receive transfer events.

In this example, we will monitor all the USDT transfers on the C-chain. If we go to any block explorer, select a USDT transaction, and look at `Topic 0` from the transfer event, we can get the signature.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=86336e01db1fbfa22e5c313f371defdb" data-og-width="2746" width="2746" data-og-height="694" height="694" data-path="images/function-signature.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=86be3ca19e0ca7931285fb669af8cdb5 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bf86f3f2cebace8a07ffa511a824abb5 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=36762aaa05508745908e07fb8c166715 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=21f6a095afce08def0633554fdff81c9 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=874fdd1d396c9ca39cae06db51efd042 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=464f87dad439c35894a5f9dff10bef3d 2500w" />

With the event signature, we can create the webhook as follows:

```bash
curl --location '<https://glacier-api.lux.network/v1/webhooks'>
--header 'x-glacier-api-key: <YOUR_API_KEY'
--header 'Content-Type: application/json'
--data '{
   "url": "https://webhook.site/30eb3703-04f0-4a01-8903-fe3f5afb78bc",
   "chainId": "43114",
   "eventType": "address_activity",
   "metadata": {
       "addresses": ["0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7"],
       "eventSignatures": [
           "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
        ]
   },
   "name": "USDT",
   "description": "USDT"
}'
```

Once the the webhook is created we start receiving the events:

```json
{
  "webhookId": "401da7d9-d6d7-46c8-b431-72ff1e1543f4",
  "eventType": "address_activity",
  "messageId": "bc9732db-2430-4296-afc3-c51267beb14a",
  "event": {
    "transaction": {
      "blockHash": "0x2a47bebed93db4a21cc8339980f004cc67f17d0dff4a368001e450e7be2edaa0",
      "blockNumber": "45396106",
      "from": "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
      "gas": "80000",
      "gasPrice": "52000000000",
      "maxFeePerGas": "52000000000",
      "maxPriorityFeePerGas": "2000000000",
      "txHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
      "txStatus": "1",
      "input": "0xa9059cbb00000000000000000000000040e832c3df9562dfae5a86a4849f27f687a9b46b00000000000000000000000000000000000000000000000000000000c68b2a69",
      "nonce": "2",
      "to": "0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7",
      "transactionIndex": 2,
      "value": "0",
      "type": 2,
      "chainId": "43114",
      "receiptCumulativeGasUsed": "668508",
      "receiptGasUsed": "44038",
      "receiptEffectiveGasPrice": "27000000000",
      "receiptRoot": "0xe5b018c29a77c8a92c4ea2f2d7e58820283041a52e14a0620d90d13b881e1ee3",
      "erc20Transfers": [
        {
          "transactionHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
          "type": "ERC20",
          "from": "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
          "to": "0x40E832C3Df9562DfaE5A86A4849F27F687A9B46B",
          "value": "3331009129",
          "blockTimestamp": 1715621840,
          "logIndex": 0,
          "erc20Token": {
            "address": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            "name": "TetherToken",
            "symbol": "USDt",
            "decimals": 6,
            "valueWithDecimals": "3331.009129"
          }
        }
      ],
      "erc721Transfers": [],
      "erc1155Transfers": [],
      "internalTransactions": [
        {
          "from": "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
          "to": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "44038",
          "gasLimit": "80000",
          "transactionHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8"
        },
        {
          "from": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
          "to": "0xBA2a995Bd4ab9e605454cCEf88169352cd5F75A6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "15096",
          "gasLimit": "50301",
          "transactionHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8"
        }
      ],
      "blockTimestamp": 1715621840
    },
    "logs": [
      {
        "address": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x000000000000000000000000737f6b0b8a04e8462d0fc7076451298f0da9a972",
        "topic2": "0x00000000000000000000000040e832c3df9562dfae5a86a4849f27f687a9b46b",
        "topic3": null,
        "data": "0x00000000000000000000000000000000000000000000000000000000c68b2a69",
        "transactionIndex": 2,
        "logIndex": 19,
        "removed": false
      }
    ]
  }
}
```

# Track ERC-721 Transfers (/docs/api-reference/webhook-api/tutorials/erc721transfer)

---
title: Track ERC-721 Transfers
description: How to track ERC-721 transfers with the Webhooks API
icon: Wallpaper
---

In this tutorial, we build upon the previous in which we tracked ERC20 transfers. To monitor NFT transfers, we will utilize the event signature. If you wish to receive a notification every time a Dokyo NFT is transferred, you can use an expression similar to the following:

```bash
curl --location 'https://glacier-api.lux.network/v1/webhooks' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://webhook.site/961a0d1b-a7ed-42fd-9eab-d7e4c7eb1227",
    "chainId": "43114",
    "eventType": "address_activity",
    "metadata": {
        "addresses": ["0x54C800d2331E10467143911aabCa092d68bF4166"],
        "includeInternalTxs": false,
        "includeLogs": true,
        "eventSignatures": [
           "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
        ]

    },
    "name": "Dokyo NFT",
    "description": "Dokyo NFT"
}'
```

Whenever an NFT is transferred you’ll receive a payload like this:

```json
{
  "webhookId": "6d1bd383-aa8d-47b5-b793-da6d8a115fde",
  "eventType": "address_activity",
  "messageId": "6a364b45-47a2-45af-97c3-0ddc2e87ad36",
  "event": {
    "transaction": {
      "blockHash": "0x30da6a8887bf2c26b7921a1501abd6e697529427e4a4f52a9d4fc163a2344b46",
      "blockNumber": "42649820",
      "from": "0x0000333883f313AD709f583D0A3d2E18a44EF29b",
      "gas": "245004",
      "gasPrice": "30000000000",
      "maxFeePerGas": "30000000000",
      "maxPriorityFeePerGas": "30000000000",
      "txHash": "0x2f1a9e2b8719536997596d878f21b70f2ce0901287aa3480d923e7ffc68ac3bc",
      "txStatus": "1",
      "input": "0xafde1b3c0000000000000000000000000…0000000000000000000000000000000000",
      "nonce": "898",
      "to": "0x398baa6ffc99126671ab6be565856105a6118a40",
      "transactionIndex": 0,
      "value": "0",
      "type": 0,
      "chainId": "43114",
      "receiptCumulativeGasUsed": "163336",
      "receiptGasUsed": "163336",
      "receiptEffectiveGasPrice": "30000000000",
      "receiptRoot": "0xdf05c214cee5ff908744e13a3b2879fdba01c9c7f95073670cb23ed735126178",
      "contractAddress": "0x0000000000000000000000000000000000000000",
      "blockTimestamp": 1709930290
    },
    "logs": [
      {
        "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic2": "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
        "topic3": null,
        "data": "0x000000000000000000000000000000000000000000000001a6c5c6f4f4f6d060",
        "transactionIndex": 0,
        "logIndex": 0,
        "removed": false
      },
      {
        "address": "0x54C800d2331E10467143911aabCa092d68bF4166",
        "topic0": "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
        "topic1": "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
        "topic2": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "topic3": "0x0000000000000000000000000000000000000000000000000000000000001350",
        "data": "0x",
        "transactionIndex": 0,
        "logIndex": 1,
        "removed": false
      },
      {
        "address": "0x54C800d2331E10467143911aabCa092d68bF4166",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
        "topic2": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic3": "0x0000000000000000000000000000000000000000000000000000000000001350",
        "data": "0x",
        "transactionIndex": 0,
        "logIndex": 2,
        "removed": false
      },
      {
        "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic2": "0x00000000000000000000000087f45335268512cc5593d435e61df4d75b07d2a2",
        "topic3": null,
        "data": "0x000000000000000000000000000000000000000000000000087498758a04efb0",
        "transactionIndex": 0,
        "logIndex": 3,
        "removed": false
      },
      {
        "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic2": "0x000000000000000000000000610512654af4fa883bb727afdff2dd78b65342b7",
        "topic3": null,
        "data": "0x000000000000000000000000000000000000000000000000021d261d62813bec",
        "transactionIndex": 0,
        "logIndex": 4,
        "removed": false
      },
      {
        "address": "0x398BAa6FFc99126671Ab6be565856105a6118A40",
        "topic0": "0x50273fa02273cceea9cf085b42de5c8af60624140168bd71357db833535877af",
        "topic1": null,
        "topic2": null,
        "topic3": null,
        "data": "0x0000000000009911a89f400000000000000000000…0000010",
        "transactionIndex": 0,
        "logIndex": 5,
        "removed": false
      }
    ]
  }
}
```

# Monitoring multiple addresses (/docs/api-reference/webhook-api/tutorials/monitor-multiple-addresses)

---
title: Monitoring multiple addresses
description: How to monitor multiple addresses with the Webhooks API
icon: BookUser
---

A single webhook can monitor multiple addresses, you don't need to create one webhook per address.

<Callout>In the free plan, you add up to 5 addresses per webhook. If you need more than that you can upgrade your plan.</Callout>

### Creating the webhook

Let's start by creating a new webhook to monitor all USDC and USDT activity:

```bash
curl --location 'https://glacier-api.lux.network/v1/webhooks' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://webhook.site/4eb31e6c-a088-4dcb-9a5d-e9341624b584",
    "chainId": "43114",
    "eventType": "address_activity",
    "includeInternalTxs": true,
    "includeLogs": true,
    "metadata": {
        "addresses": [
            "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
            ]
    },
    "name": "Tokens",
    "description": "Track tokens"
}
```

It returns the following:

```json
{
    "id": "401da7d9-d6d7-46c8-b431-72ff1e1543f4",
    "eventType": "address_activity",
    "chainId": "43114",
    "metadata": {
        "addresses": [
            "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
        ]
    },
    "includeInternalTxs": true,
    "includeLogs": true,
    "url": "https://webhook.site/4eb31e6c-a088-4dcb-9a5d-e9341624b584",
    "status": "active",
    "createdAt": 1715621587726,
    "name": "Tokens",
    "description": "Track tokens"
}
```

### Adding addresses to monitor

With the webhook `id` we can add more addresses. In this case, let's add the contract addresses for JOE and PNG:

```bash
curl --location --request PATCH 'https://glacier-api.lux.network/v1/webhooks/401da7d9-d6d7-46c8-b431-72ff1e1543f4/addresses' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "addresses": [
            "0x6e84a6216eA6dACC71eE8E6b0a5B7322EEbC0fDd",
            "0x60781C2586D68229fde47564546784ab3fACA982"
  ]
}
```

Following that, we will begin to receive events from the four smart contracts integrated into the webhook: USDC, USDT, JOE, and PNG.

### Deleting addresses

To remove addresses, simply send an array:

```bash
curl --location --request DELETE 'https://glacier-api.lux.network/v1/webhooks/401da7d9-d6d7-46c8-b431-72ff1e1543f4/addresses' \
--header 'x-glacier-api-key: <YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "addresses": [
    "0x735D8f3B6A5d2c96D0405230c50Eaf96794FbB88"
  ]
}
```

# Send Push Notifications (/docs/api-reference/webhook-api/tutorials/push)

---
title: Send Push Notifications
description: How to send push notifications with the Webhooks API
icon: Bell
---
In this tutorial, we'll explore how to send push notifications to a user's wallet whenever they receive a transaction containing tokens. It's a handy way to keep users informed about their account activity.

We'll be using [OneSignal](https://onesignal.com) for sending push notifications, but you can also achieve similar functionality with other services like [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [AWS Pinpoint](https://aws.amazon.com/pinpoint/).

### Step 1 - OneSignal Setup

The first step is to create a free account in [OneSignal](https://onesignal.com). For this example, we are going to use Web push but it works similarly for mobile.

To get started, the first step is to create a free account on OneSignal. Once you've signed up and logged in, we'll proceed to create a new OneSignal App.

For this example, we'll focus on using Web push notifications, but keep in mind that the process is quite similar for mobile apps.

Create a new OneSignal App and select Web. Once your app is created, you'll be provided with an App ID and API Key. Keep these credentials handy as we'll need them later to integrate OneSignal with our code.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/new-onesignal-app.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=a1655c7c6c7612674e58cc51c47667fd" data-og-width="1884" width="1884" data-og-height="1624" height="1624" data-path="images/new-onesignal-app.png" data-optimize="true" data-opv="3" />

Next, click on Configure Your Platform and select Web, select Code Custom, and set the site URL `http://localhost:3000` and enable both toggles for local development.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d0f8b0e5a0bb760a6d6da6326cf7588d" data-og-width="2572" width="2572" data-og-height="2432" height="2432" data-path="images/onesignal-web-configuration.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=75dbc845a08b371e8a780c03239e9bb6 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=31d057925a5ee7840ac49688d81513a5 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5b3ce1c389d8ca65e0ee1c0027140f11 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=942e156dc7ddbf45ff8e3129a90dc936 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c094e4046674e6e8db902ffa76b8b330 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bd1f699c0bb61fa6baf0f34b36ae4f13 2500w" />

This will generate a code snippet to add to your code. Download the OneSignal SDK files and copy them to the top-level root of your directory.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1de37f66dbd19b46f75a938a4a37323a" data-og-width="2572" width="2572" data-og-height="2784" height="2784" data-path="images/onsignal-snippet.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=fcc0aa943efd60ff4ad161dfe6efdc7b 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8752058899bfd0b54f48fce57448826d 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c3d93c31a409cfff91f736ef7faf2680 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=2dbb1217d71dfcf635133884ce531a3f 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=01375f360ded2e7c815de9d64aaa2ce9 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=34330c9282acb58554756d97ffae3500 2500w" />

### Step 2 - Frontend Setup

In a real-world scenario, your architecture typically involves customers signing up for subscriptions within your Web or Mobile App. To ensure these notifications are sent out, your app needs to register with a push notification provider such as OneSignal.

To maintain privacy and security, we'll be using a hash of the wallet address as the `externalID` instead of directly sharing the addresses with OneSignal. This `externalID` will then be mapped to an address in our database. So, when our backend receives a webhook for a specific address, it can retrieve the corresponding `externalID` and send a push notification accordingly.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5e450fcdbb76408198d570d06198256f" alt="OneSignal Architecture" data-og-width="1396" width="1396" data-og-height="1072" height="1072" data-path="images/onesignal-architecture.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=3056807946d72d2eee495f4f969668eb 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f3388e86a7f2f107c97dec83dc6c2948 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=19b7ea6c2660a372ef1ca682f4dac6d4 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=44e4c4514a393398e94a16ac41931906 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1ca2f7c9374450eb657853998ce8caa1 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d03d911305eb93c6ec6e6553e787e3de 2500w" />

For the sake of simplicity in our demonstration, we'll present a basic scenario where our frontend app retrieves the wallet address and registers it with OneSignal. Additionally, we'll simulate a database using an array within the code. Download the [sample code](https://github.com/javiertc/webhookdemo) and you'll see `client/index.html` with this content.

```html
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "a63e0a25-186c-40a7-8fce-9c0fde324400",
        safari_web_id: "web.onesignal.auto.67fef31a-7360-4fd8-9645-1463ac233cef",
        notifyButton: {
          enable: false,
        },
        allowLocalhostAsSecureOrigin: true,
      });
    });

    window.connect = async function() {
      try {
        if (!window.ethereum) {
          throw new Error("Lux wallet not detected");
        }
        const accounts = await window.ethereum.request({ method: "eth_requestAccounts" });
        window.web3 = new Web3(window.ethereum);

        //Create externalID based on the address
        const externalID = web3.utils.sha3(accounts[0].toLowerCase()).slice(2);
        console.log("externalID:", externalID);

        OneSignal.login(externalID);
        OneSignal.Notifications.requestPermission();
      } catch (error) {
        console.error("Error connecting to Lux wallet:", error.message);
      }
    };
  </script>
</head>
<body>
  <h1>Lux push notifications</h1>
  <button onclick="window.connect()">Connect</button>
</body>
</html>
```

Run the project using Nodejs.

```bash
npm install express axios path body-parser dotenv
node app.js
```

Open a Chrome tab and type `http://localhost:3000`, you should see something like this. Then click on Connect and accept receiving push notifications. If you are using MacOS, check in **System Settings** > **Notifications** that you have enabled notifications for the browser.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=ae7af57911b5c970833a39974df1d50b" data-og-width="2216" width="2216" data-og-height="1144" height="1144" data-path="images/onesignal-connect.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b5d75487527b3671f395986c2125407d 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=23b8447cb83d9d9eb4a8be31fe9d89ee 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b5fb06deb480000404eb86e4826b9e40 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c2a18635bca4f3f4d4822654ab1bc863 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c0c81768ee7b3962210d98c130dc4405 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=10a4a54aa32fdfb14e1c420af48d106a 2500w" />

If everything runs correctly your browser should be registered in OneSignal. To check go to **Audience** > **Subscriptions** and verify that your browser is registered.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-subscription.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=27e8e9430e32f1761a976686c8d28bcb" data-og-width="2075" width="2075" data-og-height="1312" height="1312" data-path="images/onesignal-subscription.png" data-optimize="true" data-opv="3" />

### Step 3 - Backend Setup

Now, let's configure the backend to manage webhook events and dispatch notifications based on the incoming data. Here's the step-by-step process:

1. **Transaction Initiation:** When someone starts a transaction with your wallet as the destination, the webhooks detect the transaction and generate an event.
2. **Event Triggering:** The backend receives the event triggered by the transaction, containing the destination address.
3. **ExternalID Retrieval:** Using the received address, the backend retrieves the corresponding `externalID` associated with that wallet.
4. **Notification Dispatch:** The final step involves sending a notification through OneSignal, utilizing the retrieved `externalID`.
   <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f9f4ba254762a15eb3adb32c02a8dca5" alt="OneSignal Backend" data-og-width="2305" width="2305" data-og-height="1072" height="1072" data-path="images/onesignal-backend.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=aa990f7f2274c7a8d354ba9673d5b805 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0547ba77ae5a9d2c1c8b74f7e2dd0703 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=fb40164003e26bfdb5662fe4aaf5aee5 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4e4a87b57e62617efdb3fc8d834b50ee 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=48537241c64e0dc7f3a33de9bbff0587 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=380a39b72d033ec6dc00f783bea413cc 2500w" />

#### 3.1 - Use Ngrok to tunnel the traffic to localhost

If we want to test the webhook in our computer and we are behind a proxy/NAT device or a firewall we need a tool like Ngrok. Glacier will trigger the webhook and make a POST to the Ngrok cloud, then the request is forwarded to your local Ngrok client who in turn forwards it to the Node.js app listening on port 3000.
Go to [https://ngrok.com/](https://ngrok.com/) create a free account, download the binary, and connect to your account. Create a Node.js app with Express and paste the following code to receive the webhook:

To start an HTTP tunnel forwarding to your local port 3000 with Ngrok, run this next:

```bash
./ngrok http 3000
```

You should see something like this:

```
ngrok                                                                                                                                                                           (Ctrl+C to quit)

Take our ngrok in production survey! https://forms.gle/aXiBFWzEA36DudFn6

Session Status                online
Account                       javier.toledo@luxfi.org (Plan: Free)
Version                       3.8.0
Region                        United States (us)
Latency                       48ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://c902-2600-1700-5220-11a0-813c-d5ac-d72c-f7fd.ngrok-free.app -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              33      0       0.00    0.00    5.02    5.05

HTTP Requests
-------------
```

#### 3.2 - Create the webhook

The webhook can be created using the [Avacloud Dashboard](https://app.avacloud.io/) or Glacier API. For convenience, we are going to use cURL. For that copy the forwarding URL generated by Ngrok and append the `/callbackpath` and our address.

```bash
curl --location 'https://glacier-api-dev.lux.network/v1/webhooks' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "url": " https://c902-2600-1700-5220-11a0-813c-d5ac-d72c-f7fd.ngrok-free.app/callback",
    "chainId": "43113",
    "eventType": "address_activity",
    "includeInternalTxs": true,
    "includeLogs": true,
    "metadata": {
        "addresses": ["0x8ae323046633A07FB162043f28Cea39FFc23B50A"]
    },
    "name": "My wallet",
    "description": "My wallet"
}'
```

<Callout> Don't forget to add your API Key. If you don't have one go to the [Avacloud Dashboard](https://app.avacloud.io/) and create a new one. </Callout>

#### 3.3 - The backend

To run the backend we need to add the environment variables in the root of your project. For that create an `.env` file with the following values:

```
PORT=3000
ONESIGNAL_API_KEY=<YOUR_ONESIGNAL_API_KEY>
APP_ID=<YOUR_ONESIGNAL_APP_ID>
```

<Callout> To get the APP ID from OneSignal go to **Settings** > **Keys and IDs** </Callout>

Since we are simulating the connection to a database to retrieve the externalID, we need to add the wallet address and the OneSignal externalID to the myDB array.

```javascript
//simulating a DB
const myDB = [
    { name: 'wallet1', address: '0x8ae323046633A07FB162043f28Cea39FFc23B50A', externalID: '9c96e91d40c7a44c763fb55960e12293afbcfaf6228860550b0c1cc09cd40ac3' },
    { name: 'wallet2', address: '0x1f83eC80D755A87B31553f670070bFD897c40CE0', externalID: '0xd39d39c99305c6df2446d5cc3d584dc1eb041d95ac8fb35d4246f1d2176bf330' }
];
```

The code handles a webhook event triggered when a wallet receives a transaction, performs a lookup in the simulated "database" using the receiving address to retrieve the corresponding OneSignal `externalID`, and then sends an instruction to OneSignal to dispatch a notification to the browser, with OneSignal ultimately delivering the web push notification to the browser.

```javascript
require('dotenv').config();
const axios = require('axios');
const express = require('express');
const bodyParser = require('body-parser');
const path = require('path');

const app = express();
const port = process.env.PORT || 3000;

//  Serve static website
app.use(bodyParser.json());
app.use(express.static(path.join(__dirname, './client')));

//simulating a DB
const myDB = [
    { name: 'wallet1', address: '0x8ae323046633A07FB162043f28Cea39FFc23B50A', externalID: '9c96e91d40c7a44c763fb55960e12293afbcfaf6228860550b0c1cc09cd40ac3' },
    { name: 'wallet2', address: '0x1f83eC80D755A87B31553f670070bFD897c40CE0', externalID: '0xd39d39c99305c6df2446d5cc3d584dc1eb041d95ac8fb35d4246f1d2176bf330' }
];

app.post('/callback', async (req, res) => {
    const { body } = req;
    try {
        res.sendStatus(200);
        handleTransaction(body.event.transaction).catch(error => {
            console.error('Error processing transaction:', error);
        });
    } catch (error) {
        console.error('Error processing transaction:', error);
        res.status(500).json({ error: 'Internal server error' });
    }
});

// Handle transaction
async function handleTransaction(transaction) {
    console.log('*****Transaction:', transaction);
    const notifications = [];

    const erc20Transfers = transaction?.erc20Transfers || [];
    for (const transfer of erc20Transfers) {
        const externalID = await getExternalID(transfer.to);
        const { symbol, valueWithDecimals } = transfer.erc20Token;
        notifications.push({
            type: transfer.type,
            sender: transfer.from,
            receiver: transfer.to,
            amount: valueWithDecimals,
            token: symbol,
            externalID
        });
    }

    if (transaction?.networkToken) {
        const { tokenSymbol, valueWithDecimals } = transaction.networkToken;
        const externalID = await getExternalID(transaction.to);
        notifications.push({
            sender: transaction.from,
            receiver: transaction.to,
            amount: valueWithDecimals,
            token: tokenSymbol,
            externalID
        });
    }

    if (notifications.length > 0) {
        sendNotifications(notifications);
    }
}

//connect to DB and return externalID
async function getExternalID(address) {
    const entry = myDB.find(entry => entry.address.toLowerCase() === address.toLowerCase());
    return entry ? entry.externalID : null;
}

// Send notifications
async function sendNotifications(notifications) {
    for (const notification of notifications) {
        try {
            const data = {
                include_aliases: { external_id: [notification.externalID.toLowerCase()] },
                target_channel: 'push',
                isAnyWeb: true,
                contents: { en: `You've received ${notification.amount} ${notification.token}` },
                headings: { en: 'Core wallet' },
                name: 'Notification',
                app_id: process.env.APP_ID
            };
            console.log('data:', data);
            const response = await axios.post('https://onesignal.com/api/v1/notifications', data, {
                headers: {
                    Authorization: `Bearer ${process.env.ONESIGNAL_API_KEY}`,
                    'Content-Type': 'application/json'
                }
            });
            console.log('Notification sent:', response.data);
        } catch (error) {
            console.error('Error sending notification:', error);
            // Optionally, implement retry logic here
        }
    }
}

// Start the server
app.listen(port, () => {
    console.log(`App listening at http://localhost:${port}`);
});
```

You can now start your backend server by running:

```shell
node app.js
```

Send LUX from another wallet to the wallet being monitored by the webhook and you should receive a notification with the amount of Lux received. You can try it with any other ERC20 token as well.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-notification.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f261c49d1063073f38ddea236294c085" data-og-width="1892" width="1892" data-og-height="1195" height="1195" data-path="images/onesignal-notification.png" data-optimize="true" data-opv="3" />

### Conclusion

In this tutorial, we've set up a frontend to connect to the Core wallet and enable push notifications using OneSignal. We've also implemented a backend to handle webhook events and send notifications based on the received data. By integrating the frontend with the backend, users can receive real-time notifications for blockchain events.

# Lux L1 Configs (/docs/nodes/chain-configs/avalanche-l1s/avalanche-l1-configs)

---
title: "Lux L1 Configs"
description: "This page describes the configuration options available for Lux L1s."
edit_url: https://github.com/luxfi/luxgo/edit/master/subnets/config.md
---

# Subnet Configs

It is possible to provide parameters for a Subnet. Parameters here apply to all
chains in the specified Subnet.

LuxGo looks for files specified with `{subnetID}.json` under
`--subnet-config-dir` as documented
[here](https://build.lux.network/docs/nodes/configure/configs-flags#subnet-configs).

Here is an example of Subnet config file:

```json
{
  "validatorOnly": false,
  "consensusParameters": {
    "k": 25,
    "alpha": 18
  }
}
```

## Parameters

### Private Subnet

#### `validatorOnly` (bool)

If `true` this node does not expose Subnet blockchain contents to non-validators
via P2P messages. Defaults to `false`.

Lux Subnets are public by default. It means that every node can sync and
listen ongoing transactions/blocks in Subnets, even they're not validating the
listened Subnet.

Subnet validators can choose not to publish contents of blockchains via this
configuration. If a node sets `validatorOnly` to true, the node exchanges
messages only with this Subnet's validators. Other peers will not be able to
learn contents of this Subnet from this node.

:::tip
This is a node-specific configuration. Every validator of this Subnet has to use
this configuration in order to create a full private Subnet.

:::

#### `allowedNodes` (string list)

If `validatorOnly=true` this allows explicitly specified NodeIDs to be allowed
to sync the Subnet regardless of validator status. Defaults to be empty.

:::tip
This is a node-specific configuration. Every validator of this Subnet has to use
this configuration in order to properly allow a node in the private Subnet.

:::

### Consensus Parameters

Subnet configs supports loading new consensus parameters. JSON keys are
different from their matching `CLI` keys. These parameters must be grouped under
`consensusParameters` key. The consensus parameters of a Subnet default to the
same values used for the Primary Network, which are given [CLI Snow Parameters](https://build.lux.network/docs/nodes/configure/configs-flags#snow-parameters).

| CLI Key                          | JSON Key              |
| :------------------------------- | :-------------------- |
| --snow-sample-size               | k                     |
| --snow-quorum-size               | alpha                 |
| --snow-commit-threshold          | `beta`                |
| --snow-concurrent-repolls        | concurrentRepolls     |
| --snow-optimal-processing        | `optimalProcessing`   |
| --snow-max-processing            | maxOutstandingItems   |
| --snow-max-time-processing       | maxItemProcessingTime |
| --snow-lux-batch-size      | `batchSize`           |
| --snow-lux-num-parents     | `parentSize`          |

#### `proposerMinBlockDelay` (duration)

The minimum delay performed when building snowman++ blocks. Default is set to 1 second.

As one of the ways to control network congestion, Snowman++ will only build a
block `proposerMinBlockDelay` after the parent block's timestamp. Some
high-performance custom VMs may find this too strict. This flag allows tuning the
frequency at which blocks are built.

### Gossip Configs

It's possible to define different Gossip configurations for each Subnet without
changing values for Primary Network. JSON keys of these
parameters are different from their matching `CLI` keys. These parameters
default to the same values used for the Primary Network. For more information
see [CLI Gossip Configs](https://build.lux.network/docs/nodes/configure/configs-flags#gossiping).

| CLI Key                                                 | JSON Key                               |
| :------------------------------------------------------ | :------------------------------------- |
| --consensus-accepted-frontier-gossip-validator-size     | gossipAcceptedFrontierValidatorSize    |
| --consensus-accepted-frontier-gossip-non-validator-size | gossipAcceptedFrontierNonValidatorSize |
| --consensus-accepted-frontier-gossip-peer-size          | gossipAcceptedFrontierPeerSize         |
| --consensus-on-accept-gossip-validator-size             | gossipOnAcceptValidatorSize            |
| --consensus-on-accept-gossip-non-validator-size         | gossipOnAcceptNonValidatorSize         |
| --consensus-on-accept-gossip-peer-size                  | gossipOnAcceptPeerSize                 |

# Subnet-EVM Configs (/docs/nodes/chain-configs/avalanche-l1s/subnet-evm)

---
title: "Subnet-EVM Configs"
description: "This page describes the configuration options available for the Subnet-EVM."
edit_url: https://github.com/luxfi/subnet-evm/edit/master/plugin/evm/config/config.md
---

# Subnet-EVM Configuration

> **Note**: These are the configuration options available in the Subnet-EVM codebase. To set these values, you need to create a configuration file at `~/.luxgo/configs/chains/<blockchainID>/config.json`.
>
> For the LuxGo node configuration options, see the LuxGo Configuration page.

This document describes all configuration options available for Subnet-EVM.

## Example Configuration

```json
{
  "eth-apis": ["eth", "eth-filter", "net", "web3"],
  "pruning-enabled": true,
  "commit-interval": 4096,
  "trie-clean-cache": 512,
  "trie-dirty-cache": 512,
  "snapshot-cache": 256,
  "rpc-gas-cap": 50000000,
  "log-level": "info",
  "metrics-expensive-enabled": true,
  "continuous-profiler-dir": "./profiles",
  "state-sync-enabled": false,
  "accepted-cache-size": 32
}
```

## Configuration Format

Configuration is provided as a JSON object. All fields are optional unless otherwise specified.

## API Configuration

### Ethereum APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `eth-apis` | array of strings | List of Ethereum services that should be enabled | `["eth", "eth-filter", "net", "web3", "internal-eth", "internal-blockchain", "internal-transaction"]` |

### Subnet-EVM Specific APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `validators-api-enabled` | bool | Enable the validators API | `true` |
| `admin-api-enabled` | bool | Enable the admin API for administrative operations | `false` |
| `admin-api-dir` | string | Directory for admin API operations | - |
| `warp-api-enabled` | bool | Enable the Warp API for cross-chain messaging | `false` |

### API Limits and Security

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `rpc-gas-cap` | uint64 | Maximum gas limit for RPC calls | `50,000,000` |
| `rpc-tx-fee-cap` | float64 | Maximum transaction fee cap in LUX | `100` |
| `api-max-duration` | duration | Maximum duration for API calls (0 = no limit) | `0` |
| `api-max-blocks-per-request` | int64 | Maximum number of blocks per getLogs request (0 = no limit) | `0` |
| `http-body-limit` | uint64 | Maximum size of HTTP request bodies | - |
| `batch-request-limit` | uint64 | Maximum number of requests that can be batched in an RPC call. For no limit, set either this or `batch-response-max-size` to 0 | `1000` | 
| `batch-response-max-size` | uint64 | Maximum size (in bytes) of response that can be returned from a batched RPC call. For no limit, set either this or `batch-request-limit` to 0. Defaults to `25 MB`| `1000` |

### WebSocket Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `ws-cpu-refill-rate` | duration | Rate at which WebSocket CPU usage quota is refilled (0 = no limit) | `0` |
| `ws-cpu-max-stored` | duration | Maximum stored WebSocket CPU usage quota (0 = no limit) | `0` |

## Cache Configuration

### Trie Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `trie-clean-cache` | int | Size of the trie clean cache in MB | `512` |
| `trie-dirty-cache` | int | Size of the trie dirty cache in MB | `512` |
| `trie-dirty-commit-target` | int | Memory limit to target in the dirty cache before performing a commit in MB | `20` |
| `trie-prefetcher-parallelism` | int | Maximum concurrent disk reads trie prefetcher should perform | `16` |

### Other Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-cache` | int | Size of the snapshot disk layer clean cache in MB | `256` |
| `accepted-cache-size` | int | Depth to keep in the accepted headers and logs cache (blocks) | `32` |
| `state-sync-server-trie-cache` | int | Trie cache size for state sync server in MB | `64` |

## Ethereum Settings

### Transaction Processing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `preimages-enabled` | bool | Enable preimage recording | `false` |
| `allow-unfinalized-queries` | bool | Allow queries for unfinalized blocks | `false` |
| `allow-unprotected-txs` | bool | Allow unprotected transactions (without EIP-155) | `false` |
| `allow-unprotected-tx-hashes` | array | List of specific transaction hashes allowed to be unprotected | EIP-1820 registry tx |
| `local-txs-enabled` | bool | Enable treatment of transactions from local accounts as local | `false` |

### Snapshots

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-wait` | bool | Wait for snapshot generation on startup | `false` |
| `snapshot-verification-enabled` | bool | Enable snapshot verification | `false` |

## Pruning and State Management

### Basic Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `pruning-enabled` | bool | Enable state pruning to save disk space | `true` |
| `commit-interval` | uint64 | Interval at which to persist EVM and atomic tries (blocks) | `4096` |
| `accepted-queue-limit` | int | Maximum blocks to queue before blocking during acceptance | `64` |

### State Reconstruction

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `allow-missing-tries` | bool | Suppress warnings about incomplete trie index | `false` |
| `populate-missing-tries` | uint64 | Starting block for re-populating missing tries (null = disabled) | `null` |
| `populate-missing-tries-parallelism` | int | Concurrent readers for re-populating missing tries | `1024` |

### Offline Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `offline-pruning-enabled` | bool | Enable offline pruning | `false` |
| `offline-pruning-bloom-filter-size` | uint64 | Bloom filter size for offline pruning in MB | `512` |
| `offline-pruning-data-directory` | string | Directory for offline pruning data | - |

### Historical Data

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `historical-proof-query-window` | uint64 | Number of blocks before last accepted for proof queries (archive mode only, ~24 hours) | `43200` |
| `state-history` | uint64 | Number of most recent states that are accesible on disk (pruning mode only) | `32` |

## Transaction Pool Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `tx-pool-price-limit` | uint64 | Minimum gas price for transaction acceptance | - |
| `tx-pool-price-bump` | uint64 | Minimum price bump percentage for transaction replacement | - |
| `tx-pool-account-slots` | uint64 | Maximum number of executable transaction slots per account | - |
| `tx-pool-global-slots` | uint64 | Maximum number of executable transaction slots for all accounts | - |
| `tx-pool-account-queue` | uint64 | Maximum number of non-executable transaction slots per account | - |
| `tx-pool-global-queue` | uint64 | Maximum number of non-executable transaction slots for all accounts | - |
| `tx-pool-lifetime` | duration | Maximum time transactions can stay in the pool | - |

## Gossip Configuration

### Push Gossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-percent-stake` | float64 | Percentage of total stake to push gossip to (range: [0, 1]) | `0.9` |
| `push-gossip-num-validators` | int | Number of validators to push gossip to | `100` |
| `push-gossip-num-peers` | int | Number of non-validator peers to push gossip to | `0` |

### Regossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-regossip-num-validators` | int | Number of validators to regossip to | `10` |
| `push-regossip-num-peers` | int | Number of non-validator peers to regossip to | `0` |
| `priority-regossip-addresses` | array | Addresses to prioritize for regossip | - |

### Timing Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-frequency` | duration | Frequency of push gossip | `100ms` |
| `pull-gossip-frequency` | duration | Frequency of pull gossip | `1s` |
| `regossip-frequency` | duration | Frequency of regossip | `30s` |

## Logging and Monitoring

### Logging

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `log-level` | string | Logging level (trace, debug, info, warn, error, crit) | `"info"` |
| `log-json-format` | bool | Use JSON format for logs | `false` |

### Profiling

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `continuous-profiler-dir` | string | Directory for continuous profiler output (empty = disabled) | - |
| `continuous-profiler-frequency` | duration | Frequency to run continuous profiler | `15m` |
| `continuous-profiler-max-files` | int | Maximum number of profiler files to maintain | `5` |

### Metrics

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `metrics-expensive-enabled` | bool | Enable expensive debug-level metrics; this includes Firewood metrics | `true` |

## Security and Access

### Keystore

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `keystore-directory` | string | Directory for keystore files (absolute or relative path) | - |
| `keystore-external-signer` | string | External signer configuration | - |
| `keystore-insecure-unlock-allowed` | bool | Allow insecure account unlocking | `false` |

### Fee Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `feeRecipient` | string | Address to send transaction fees to (leave empty if not supported) | - |

## Network and Sync

### Network

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `max-outbound-active-requests` | int64 | Maximum number of outbound active requests for VM2VM network | `16` |

### State Sync

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `state-sync-enabled` | bool | Enable state sync | `false` |
| `state-sync-skip-resume` | bool | Force state sync to use highest available summary block | `false` |
| `state-sync-ids` | string | Comma-separated list of state sync IDs | - |
| `state-sync-commit-interval` | uint64 | Commit interval for state sync (blocks) | `16384` |
| `state-sync-min-blocks` | uint64 | Minimum blocks ahead required for state sync | `300000` |
| `state-sync-request-size` | uint16 | Number of key/values to request per state sync request | `1024` |

## Database Configuration

> **WARNING**: `firewood` and `path` schemes are untested in production. Using `path` is strongly discouraged. To use `firewood`, you must also set the following config options:
>
> - `pruning-enabled: true` (enabled by default)
> - `state-sync-enabled: false`
> - `snapshot-cache: 0`

Failing to set these options will result in errors on VM initialization. Additionally, not all APIs are available - see these portions of the config documentation for more details.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `database-type` | string | Type of database to use | `"pebbledb"` |
| `database-path` | string | Path to database directory | - |
| `database-read-only` | bool | Open database in read-only mode | `false` |
| `database-config` | string | Inline database configuration | - |
| `database-config-file` | string | Path to database configuration file | - |
| `use-standalone-database` | bool | Use standalone database instead of shared one | - |
| `inspect-database` | bool | Inspect database on startup | `false` |
| `state-scheme` | string |  EXPERIMENTAL: specifies the database scheme to store state data; can be one of `hash` or `firewood` | `hash` | 

## Transaction Indexing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `transaction-history` | uint64 | Maximum number of blocks from head whose transaction indices are reserved (0 = no limit) | - |
| `tx-lookup-limit` | uint64 | **Deprecated** - use `transaction-history` instead | - |
| `skip-tx-indexing` | bool | Skip indexing transactions entirely | `false` |

## Warp Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `warp-off-chain-messages` | array | Off-chain messages the node should be willing to sign | - |
| `prune-warp-db-enabled` | bool | Clear warp database on startup | `false` |

## Miscellaneous

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `airdrop` | string | Path to airdrop file | - |
| `skip-upgrade-check` | bool | Skip checking that upgrades occur before last accepted block ⚠️ **Warning**: Only use when you understand the implications | `false` |
| `min-delay-target` | integer | The minimum delay between blocks (in milliseconds) that this node will attempt to use when creating blocks | Parent block's target |

## Gossip Constants

The following constants are defined for transaction gossip behavior and cannot be configured without a custom build of Subnet-EVM:

| Constant | Type | Description | Value |
|----------|------|-------------|-------|
| Bloom Filter Min Target Elements | int | Minimum target elements for bloom filter | `8,192` |
| Bloom Filter Target False Positive Rate | float | Target false positive rate | `1%` |
| Bloom Filter Reset False Positive Rate | float | Reset false positive rate | `5%` |
| Bloom Filter Churn Multiplier | int | Churn multiplier | `3` |
| Push Gossip Discarded Elements | int | Number of discarded elements | `16,384` |
| Tx Gossip Target Message Size | size | Target message size for transaction gossip | `20 KiB` |
| Tx Gossip Throttling Period | duration | Throttling period | `10s` |
| Tx Gossip Throttling Limit | int | Throttling limit | `2` |
| Tx Gossip Poll Size | int | Poll size | `1` |

## Validation Notes

- Cannot enable `populate-missing-tries` while pruning or offline pruning is enabled
- Cannot run offline pruning while pruning is disabled  
- Commit interval must be non-zero when pruning is enabled
- `push-gossip-percent-stake` must be in range `[0, 1]`
- Some settings may require node restart to take effect

# Amazon Web Services (/docs/nodes/run-a-node/on-third-party-services/amazon-web-services)

---
title: Amazon Web Services
description: Learn how to run a node on Amazon Web Services.
---

Introduction[​](#introduction "Direct link to heading")
-------------------------------------------------------

This tutorial will guide you through setting up an Lux node on [Amazon Web Services (AWS)](https://aws.amazon.com/). Cloud services like AWS are a good way to ensure that your node is highly secure, available, and accessible.

To get started, you'll need:

- An AWS account
- A terminal with which to SSH into your AWS machine
- A place to securely store and back up files

This tutorial assumes your local machine has a Unix style terminal. If you're on Windows, you'll have to adapt some of the commands used here.

Log Into AWS[​](#log-into-aws "Direct link to heading")
-------------------------------------------------------

Signing up for AWS is outside the scope of this article, but Amazon has instructions [here](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account).

It is _highly_ recommended that you set up Multi-Factor Authentication on your AWS root user account to protect it. Amazon has documentation for this [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-root).

Once your account is set up, you should create a new EC2 instance. An EC2 is a virtual machine instance in AWS's cloud. Go to the [AWS Management Console](https://console.aws.amazon.com/) and enter the EC2 dashboard.

![AWS Management Console.png](/images/amazon1.png)

To log into the EC2 instance, you will need a key on your local machine that grants access to the instance. First, create that key so that it can be assigned to the EC2 instance later on. On the bar on the left side, under **Network & Security**, select **Key Pairs.**

![Select &quot;Key Pairs&quot; under the &quot;Network &amp; Security&quot; drop-down.](/images/amazon2.png)

Select **Create key pair** to launch the key pair creation wizard.

![Select "Create key pair."](/images/amazon3.png)

Name your key `lux`. If your local machine has MacOS or Linux, select the `pem` file format. If it's Windows, use the `ppk` file format. Optionally, you can add tags for the key pair to assist with tracking.

![Create a key pair that will later be assigned to your EC2 instance.](/images/amazon4.png)

Click `Create key pair`. You should see a success message, and the key file should be downloaded to your local machine. Without this file, you will not be able to access your EC2 instance. **Make a copy of this file and put it on a separate storage medium such as an external hard drive. Keep this file secret; do not share it with others.**

![Success message after creating a key pair.](/images/amazon5.png)

Create a Security Group[​](#create-a-security-group "Direct link to heading")
-----------------------------------------------------------------------------

An AWS Security Group defines what internet traffic can enter and leave your EC2 instance. Think of it like a firewall. Create a new Security Group by selecting **Security Groups** under the **Network & Security** drop-down.

![Select "Security Groups" underneath "Network & Security."](/images/amazon6.png)

This opens the Security Groups panel. Click **Create security group** in the top right of the Security Groups panel.

![Select "Create security group."](/images/amazon7.png)

You'll need to specify what inbound traffic is allowed. Allow SSH traffic from your IP address so that you can log into your EC2 instance (each time your ISP changes your IP address, you will need to modify this rule). Allow TCP traffic on port 9651 so your node can communicate with other nodes on the network. Allow TCP traffic on port 9650 from your IP so you can make API calls to your node. **It's important that you only allow traffic on the SSH and API port from your IP.** If you allow incoming traffic from anywhere, this could be used to brute force entry to your node (SSH port) or used as a denial of service attack vector (API port). Finally, allow all outbound traffic.

![Your inbound and outbound rules should look like this.](/images/amazon8.png)

Add a tag to the new security group with key `Name` and value`Lux Security Group`. This will enable us to know what this security group is when we see it in the list of security groups.

![Tag the security group so you can identify it later.](/images/amazon9.png)

Click `Create security group`. You should see the new security group in the list of security groups.

Launch an EC2 Instance[​](#launch-an-ec2-instance "Direct link to heading")
---------------------------------------------------------------------------

Now you're ready to launch an EC2 instance. Go to the EC2 Dashboard and select **Launch instance**.

![Select "Launch Instance."](/images/amazon10.png)

Select **Ubuntu 20.04 LTS (HVM), SSD Volume Type** for the operating system.

![Select Ubuntu 20.04 LTS.](/images/amazon11.png)

Next, choose your instance type. This defines the hardware specifications of the cloud instance. In this tutorial we set up a **c5.2xlarge**. This should be more than powerful enough since Lux is a lightweight consensus protocol. To create a c5.2xlarge instance, select the **Compute-optimized** option from the filter drop-down menu.

![Filter by compute optimized.](/images/amazon12.png)

Select the checkbox next to the c5.2xlarge instance in the table.

![Select c5.2xlarge.](/images/amazon13.png)

Click the **Next: Configure Instance Details** button in the bottom right-hand corner.

![Configure instance details](/images/amazon14.png)

The instance details can stay as their defaults.

<Callout title="Note">
When setting up a node as a validator, it is crucial to select the appropriate AWS instance type to ensure the node can efficiently process transactions and manage the network load. The recommended instance types are as follows:

- For a minimal stake, start with a compute-optimized instance such as c6, c6i, c6a, c7 and similar.
- Use a 2xlarge instance size for the minimal stake configuration.
- As the staked amount increases, choose larger instance sizes to accommodate the additional workload. For every order of magnitude increase in stake, move up one instance size. For example, for a 20k LUX stake, a 4xlarge instance is suitable.
</Callout>

### Optional: Using Reserved Instances[​](#optional-using-reserved-instances "Direct link to heading")

By default, you will be charged hourly for running your EC2 instance. For a long term usage that is not optimal.

You could save money by using a **Reserved Instance**. With a reserved instance, you pay upfront for an entire year of EC2 usage, and receive a lower per-hour rate in exchange for locking in. If you intend to run a node for a long time and don't want to risk service interruptions, this is a good option to save money. Again, do your own research before selecting this option.

### Add Storage, Tags, Security Group[​](#add-storage-tags-security-group "Direct link to heading")

Click the **Next: Add Storage** button in the bottom right corner of the screen.

You need to add space to your instance's disk. You should start with at least 700GB of disk space. Although upgrades to reduce disk usage are always in development, on average the database will continually grow, so you need to constantly monitor disk usage on the node and increase disk space if needed.

Note that the image below shows 100GB as disk size, which was appropriate at the time the screenshot was taken. You should check the current [recommended disk space size](https://github.com/luxfi/luxgo#installation) before entering the actual value here.

![Select disk size.](/images/amazon15.png)

Click **Next: Add Tags** in the bottom right corner of the screen to add tags to the instance. Tags enable us to associate metadata with our instance. Add a tag with key `Name` and value `My Lux Node`. This will make it clear what this instance is on your list of EC2 instances.

![Add a tag with key "Name" and value "My Lux Node."](/images/amazon16.png)

Now assign the security group created earlier to the instance. Choose **Select an existing security group** and choose the security group created earlier.

![Choose the security group created earlier.](/images/amazon17.png)

Finally, click **Review and Launch** in the bottom right. A review page will show the details of the instance you're about to launch. Review those, and if all looks good, click the blue **Launch** button in the bottom right corner of the screen.

You'll be asked to select a key pair for this instance. Select **Choose an existing key pair** and then select the `lux` key pair you made earlier in the tutorial. Check the box acknowledging that you have access to the `.pem` or `.ppk` file created earlier (make sure you've backed it up!) and then click **Launch Instances**.

![Use the key pair created earlier.](/images/amazon18.png)

You should see a new pop up that confirms the instance is launching!

![Your instance is launching!](/images/amazon19.png)

### Assign an Elastic IP[​](#assign-an-elastic-ip "Direct link to heading")

By default, your instance will not have a fixed IP. Let's give it a fixed IP through AWS's Elastic IP service. Go back to the EC2 dashboard. Under **Network & Security,** select **Elastic IPs**.

![Select "Elastic IPs" under "Network & Security."](/images/amazon20.png)

Select **Allocate Elastic IP address**.

![Select "Allocate Elastic IP address."](/images/amazon21.png)

Select the region your instance is running in, and choose to use Amazon's pool of IPv4 addresses. Click **Allocate**.

![Settings for the Elastic IP.](/images/amazon22.png)

Select the Elastic IP you just created from the Elastic IP manager. From the **Actions** drop-down, choose **Associate Elastic IP address**.

![Under "Actions" select "Associate Elastic IP address."](/images/amazon23.png)

Select the instance you just created. This will associate the new Elastic IP with the instance and give it a public IP address that won't change.

![Assign the Elastic IP to your EC2 instance.](/images/amazon24.png)

Set Up LuxGo[​](#set-up-luxgo "Direct link to heading")
-------------------------------------------------------------------

Go back to the EC2 Dashboard and select `Running Instances`.

![Go to your running instances.](/images/amazon25.png)

Select the newly created EC2 instance. This opens a details panel with information about the instance.

![Details about your new instance.](/images/amazon26.png)

Copy the `IPv4 Public IP` field to use later. From now on we call this value `PUBLICIP`.

**Remember: the terminal commands below assume you're running Linux. Commands may differ for MacOS or other operating systems. When copy-pasting a command from a code block, copy and paste the entirety of the text in the block.**

Log into the AWS instance from your local machine. Open a terminal (try shortcut `CTRL + ALT + T`) and navigate to the directory containing the `.pem` file you downloaded earlier.

Move the `.pem` file to `$HOME/.ssh` (where `.pem` files generally live) with:

Add it to the SSH agent so that we can use it to SSH into your EC2 instance, and mark it as read-only.

```bash
ssh-add ~/.ssh/lux.pem; chmod 400 ~/.ssh/lux.pem
```

SSH into the instance. (Remember to replace `PUBLICIP` with the public IP field from earlier.)

If the permissions are **not** set correctly, you will see the following error.

![Make sure you set the permissions correctly.](/images/amazon27.png)

You are now logged into the EC2 instance.

![You're on the EC2 instance.](/images/amazon28.png)

If you have not already done so, update the instance to make sure it has the latest operating system and security updates:

```bash
sudo apt update; sudo apt upgrade -y; sudo reboot
```

This also reboots the instance. Wait 5 minutes, then log in again by running this command on your local machine:

You're logged into the EC2 instance again. Now we'll need to set up our Lux node. To do this, follow the [Set Up Lux Node With Installer](/docs/nodes/run-a-node/using-install-script/installing-lux-go) tutorial which automates the installation process. You will need the `PUBLICIP` we set up earlier.

Your LuxGo node should now be running and in the process of bootstrapping, which can take a few hours. To check if it's done, you can issue an API call using `curl`. If you're making the request from the EC2 instance, the request is:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

Once the node is finished bootstrapping, the response will be:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "isBootstrapped": true
    },
    "id": 1
}
```

You can continue on, even if LuxGo isn't done bootstrapping.

In order to make your node a validator, you'll need its node ID. To get it, run:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The response contains the node ID.

```json
{"jsonrpc":"2.0","result":{"nodeID":"NodeID-DznHmm3o7RkmpLkWMn9NqafH66mqunXbM"},"id":1}
```

In the above example the node ID is`NodeID-DznHmm3o7RkmpLkWMn9NqafH66mqunXbM`. Copy your node ID for later. Your node ID is not a secret, so you can just paste it into a text editor.

LuxGo has other APIs, such as the [Health API](/docs/rpcs/other/health-rpc), that may be used to interact with the node. Some APIs are disabled by default. To enable such APIs, modify the ExecStart section of `/etc/systemd/system/luxgo.service` (created during the installation process) to include flags that enable these endpoints. Don't manually enable any APIs unless you have a reason to.

![Some APIs are disabled by default.](/images/amazon29.png)

Back up the node's staking key and certificate in case the EC2 instance is corrupted or otherwise unavailable. The node's ID is derived from its staking key and certificate. If you lose your staking key or certificate then your node will get a new node ID, which could cause you to become ineligible for a staking reward if your node is a validator. **It is very strongly advised that you copy your node's staking key and certificate**. The first time you run a node, it will generate a new staking key/certificate pair and store them in directory `/home/ubuntu/.luxgo/staking`.

Exit out of the SSH instance by running:

Now you're no longer connected to the EC2 instance; you're back on your local machine.

To copy the staking key and certificate to your machine, run the following command. As always, replace `PUBLICIP`.

```bash
scp -r ubuntu@PUBLICIP:/home/ubuntu/.luxgo/staking ~/aws_lux_backup
```

Now your staking key and certificate are in directory `~/aws_lux_backup` . **The contents of this directory are secret.** You should hold this directory on storage not connected to the internet (like an external hard drive.)

### Upgrading Your Node[​](#upgrading-your-node "Direct link to heading")

LuxGo is an ongoing project and there are regular version upgrades. Most upgrades are recommended but not required. Advance notice will be given for upgrades that are not backwards compatible. To update your node to the latest version, SSH into your AWS instance as before and run the installer script again.

```bash
./luxgo-installer.sh
```

Your machine is now running the newest LuxGo version. To see the status of the LuxGo service, run `sudo systemctl status luxgo.`

Increase Volume Size[​](#increase-volume-size "Direct link to heading")
-----------------------------------------------------------------------

If you need to increase the volume size, follow these instructions from AWS:

- [Request modifications to your EBS volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/requesting-ebs-volume-modifications.html)
- [Extend a Linux file system after resizing a volume](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/recognize-expanded-volume-linux.html)

Wrap Up[​](#wrap-up "Direct link to heading")
---------------------------------------------

That's it! You now have an LuxGo node running on an AWS EC2 instance. We recommend setting up [node monitoring](/docs/nodes/maintain/monitoring)for your LuxGo node. We also recommend setting up AWS billing alerts so you're not surprised when the bill arrives. If you have feedback on this tutorial, or anything else, send us a message on [Discord](https://chat.avalabs.org/).

# AWS Marketplace (/docs/nodes/run-a-node/on-third-party-services/aws-marketplace)

---
title: AWS Marketplace
description: Learn how to run a node on AWS Marketplace.
---

## How to Launch an Lux Validator using AWS

<iframe
  width="560"
  height="315"
  src="https://youtu.be/4RPmgpbC_Cc"
  title="YouTube video player"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

With the intention of enabling developers and entrepreneurs to on-ramp into the Lux ecosystem with as little friction as possible, Lux Network recently launched an offering to deploy an Lux Validator node via the AWS Marketplace. This tutorial will show the main steps required to get this node running and validating on the Lux Testnet testnet.

Product Overview[​](#product-overview "Direct link to heading")
---------------------------------------------------------------

The Lux Validator node is available via [the AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-nd6wgi2bhhslg). There you'll find a high level product overview. This includes a product description, pricing information, usage instructions, support information and customer reviews. After reviewing this information you want to click the "Continue to Subscribe" button.

Subscribe to This Software[​](#subscribe-to-this-software "Direct link to heading")
-----------------------------------------------------------------------------------

Once on the "Subscribe to this Software" page you will see a button which enables you to subscribe to this AWS Marketplace offering. In addition you'll see Terms of service including the seller's End User License Agreement and the [AWS Privacy Notice](https://aws.amazon.com/privacy/). After reviewing these you want to click on the "Continue to Configuration" button.

Configure This Software[​](#configure-this-software "Direct link to heading")
-----------------------------------------------------------------------------

This page lets you choose a fulfillment option and software version to launch this software. No changes are needed as the default settings are sufficient. Leave the `Fulfillment Option` as `64-bit (x86) Amazon Machine Image (AMI)`. The software version is the latest build of [the LuxGo full node](https://github.com/luxfi/luxgo/releases), `v1.9.5 (Dec 22, 2022)`, AKA `Banff.5`. This will always show the latest version. Also, the Region to deploy in can be left as `US East (N. Virginia)`. On the right you'll see the software and infrastructure pricing. Lastly, click the "Continue to Launch" button.

Launch This Software[​](#launch-this-software "Direct link to heading")
-----------------------------------------------------------------------

Here you can review the launch configuration details and follow the instructions to launch the Lux Validator Node. The changes are very minor. Leave the action as "Launch from Website." The EC2 Instance Type should remain `c5.2xlarge`. The primary change you'll need to make is to choose a keypair which will enable you to `ssh` into the newly created EC2 instance to run `curl` commands on the Validator node. You can search for existing Keypairs or you can create a new keypair and download it to your local machine. If you create a new keypair you'll need to move the keypair to the appropriate location, change the permissions and add it to the OpenSSH authentication agent. For example, on MacOS it would look similar to the following:

```bash
# In this example we have a keypair called lux.pem which was downloaded from AWS to ~/Downloads/lux.pem
# Confirm the file exists with the following command
test -f ~/Downloads/lux.pem && echo "Lux.pem exists."

# Running the above command will output the following:
# Lux.pem exists.

# Move the lux.pem keypair from the ~/Downloads directory to the hidden ~/.ssh directory
mv ~/Downloads/lux.pem ~/.ssh

# Next add the private key identity to the OpenSSH authentication agent
ssh-add ~/.ssh/lux.pem;

# Change file modes or Access Control Lists
sudo chmod 600 ~/.ssh/lux.pem
```

Once these steps are complete you are ready to launch the Validator node on EC2. To make that happen click the "Launch" button

![launch successful](/images/aws1.png)

You now have an Lux node deployed on an AWS EC2 instance! Copy the `AMI ID` and click on the `EC2 Console` link for the next step.

EC2 Console[​](#ec2-console "Direct link to heading")
-----------------------------------------------------

Now take the `AMI ID` from the previous step and input it into the search bar on the EC2 Console. This will bring you to the dashboard where you can find the EC2 instances public IP address.

![AMI instance](/images/aws2.png)

Copy that public IP address and open a Terminal or command line prompt. Once you have the new Terminal open `ssh` into the EC2 instance with the following command.

Node Configuration[​](#node-configuration "Direct link to heading")
-------------------------------------------------------------------

### Switch to Testnet Testnet[​](#switch-to-testnet-testnet "Direct link to heading")

By default the Lux Node available through the AWS Marketplace syncs the Mainnet. If this is what you are looking for, you can skip this step.

For this tutorial you want to sync and validate the Testnet Testnet. Now that you're `ssh`ed into the EC2 instance you can make the required changes to sync Testnet instead of Mainnet.

First, confirm that the node is syncing the Mainnet by running the `info.getNetworkID` command.

#### `info.getNetworkID` Request[​](#infogetnetworkid-request "Direct link to heading")

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNetworkID",
    "params": {
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

#### `info.getNetworkID` Response[​](#infogetnetworkid-response "Direct link to heading")

The returned `networkID` will be 1 which is the network ID for Mainnet.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "networkID": "1"
  },
  "id": 1
}
```

Now you want to edit `/etc/luxgo/conf.json` and change the `"network-id"` property from `"mainnet"` to `"testnet"`. To see the contents of `/etc/luxgo/conf.json` you can `cat` the file.

```bash
cat /etc/luxgo/conf.json
{
  "api-keystore-enabled": false,
  "http-host": "0.0.0.0",
  "log-dir": "/var/log/luxgo",
  "db-dir": "/data/luxgo",
  "api-admin-enabled": false,
  "public-ip-resolution-service": "opendns",
  "network-id": "mainnet"
}
```

Edit that `/etc/luxgo/conf.json` with your favorite text editor and change the value of the `"network-id"` property from `"mainnet"` to `"testnet"`. Once that's complete, save the file and restart the Lux node via `sudo systemctl restart luxgo`. You can then call the `info.getNetworkID` endpoint to confirm the change was successful.

#### `info.getNetworkID` Request[​](#infogetnetworkid-request-1 "Direct link to heading")

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNetworkID",
    "params": {
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

#### `info.getNetworkID` Response[​](#infogetnetworkid-response-1 "Direct link to heading")

The returned `networkID` will be 5 which is the network ID for Testnet.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "networkID": "5"
  },
  "id": 1
}
```

Next you run the `info.isBoostrapped` command to confirm if the Lux Validator node has finished bootstrapping.

### `info.isBootstrapped` Request[​](#infoisbootstrapped-request "Direct link to heading")

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"P"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

Once the node is finished bootstrapping, the response will be:

### `info.isBootstrapped` Response[​](#infoisbootstrapped-response "Direct link to heading")

```json
{
    "jsonrpc": "2.0",
    "result": {
        "isBootstrapped": true
    },
    "id": 1
}
```

**Note** that initially the response is `false` because the network is still syncing.  
When you're adding your node as a Validator on the Lux Mainnet you'll want to wait for this response to return `true` so that you don't suffer from any downtime while validating. For this tutorial you're not going to wait for it to finish syncing as it's not strictly necessary.

### `info.getNodeID` Request[​](#infogetnodeid-request "Direct link to heading")

Next, you want to get the NodeID which will be used to add the node as a Validator. To get the node's ID you call the `info.getNodeID` jsonrpc endpoint.

```bash
curl --location --request POST 'http://127.0.0.1:9650/ext/info' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID",
    "params" :{
    }
}'
```

### `info.getNodeID` Response[​](#infogetnodeid-response "Direct link to heading")

Take a note of the `nodeID` value which is returned as you'll need to use it in the next step when adding a validator via the Lux Web Wallet. In this case the `nodeID` is `NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5`

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
    "nodePOP": {
      "publicKey": "0x85675db18b326a9585bfd43892b25b71bf01b18587dc5fac136dc5343a9e8892cd6c49b0615ce928d53ff5dc7fd8945d",
      "proofOfPossession": "0x98a56f092830161243c1f1a613ad68a7f1fb25d2462ecf85065f22eaebb4e93a60e9e29649a32252392365d8f628b2571174f520331ee0063a94473f8db6888fc3a722be330d5c51e67d0d1075549cb55376e1f21d1b48f859ef807b978f65d9"
    }
  },
  "id": 1
}
```

Add Node as Validator on Testnet via Core web[​](#add-node-as-validator-on-testnet-via-core-web "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------

For adding the new node as a Validator on the Testnet testnet's Primary Network you can use the [Core web](https://core.app/) [connected](https://support.lux.network/en/articles/6639869-core-web-how-do-i-connect-to-core-web) to [Core extension](https://core.app). If you don't have a Core extension already, check out this [guide](https://support.lux.network/en/articles/6100129-core-extension-how-do-i-create-a-new-wallet). If you'd like to import an existing wallet to Core extension, follow [these steps](https://support.lux.network/en/articles/6078933-core-extension-how-do-i-access-my-existing-account).

![Core web](/images/aws3.png)

Core web is a free, all-in-one command center that gives users a more intuitive and comprehensive way to view assets, and use dApps across the Lux network, its various Lux L1s, and Ethereum. Core web is optimized for use with the Core browser extension and Core mobile (available on both iOS & Android). Together, they are key components of the Core product suite that brings dApps, NFTs, Lux Bridge, Lux L1s, L2s, and more, directly to users.

### Switching to Testnet Mode[​](#switching-to-testnet-mode "Direct link to heading")

By default, Core web and Core extension are connected to Mainnet. For the sake of this demo, you want to connect to the Testnet Testnet.

#### On Core Extension[​](#on-core-extension "Direct link to heading")

From the hamburger menu on the top-left corner, choose Advanced, and then toggle the Testnet Mode on.

![](/images/aws4.gif)

You can follow the same steps for switching back to Mainnet.

#### On Core web[​](#on-core-web "Direct link to heading")

Click on the Settings button top-right corner of the page, then toggle Testnet Mode on.

![](/images/aws5.gif)

You can follow the same steps for switching back to Mainnet.

### Adding the Validator[​](#adding-the-validator "Direct link to heading")

<Callout title="Note">
- Node ID: A unique ID derived from each individual node's staker certificate. Use the `NodeID` which was returned in the `info.getNodeID` response. In this example it's `NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5`  
- Staking End Date: Your LUX tokens will be locked until this date.
- Stake Amount: The amount of LUX to lock for staking. On Mainnet, the minimum required amount is 2,000 LUX. On Testnet the minimum required amount is 1 AVAAX.  
- Delegation Fee: You will claim this % of the rewards from the delegators on your node.  
- Reward Address: A reward address is the destination address of the accumulated staking rewards.
</Callout>

To add a node as a Validator, first select the Stake tab on Core web, in the left hand nav menu. Next click the Validate button, and select Get Started.

![](/images/aws6.gif)

This page will open up.

![](/images/aws7.png)

Choose the desired Staking Amount, then click Next.

![](/images/aws8.png)

Enter you Node ID, then click Next.

![](/images/aws9.png)

Here, you'll need to choose the staking duration. There are predefined values, like 1 day, 1 month and so on. You can also choose a custom period of time. For this example, 22 days were chosen.

![](/images/aws10.png)

Choose the address that the network will send rewards to. Make sure it's the correct address because once the transaction is submitted this cannot be changed later or undone. You can choose the wallet's Platform-Chain address, or a custom Platform-Chain address. After entering the address, click Next.

![](/images/aws11.png)

Other individuals can stake to your validator and receive rewards too, known as "delegating." You will claim this percent of the rewards from the delegators on your node. Click Next.

![](/images/aws12.png)

After entering all these details, a summary of your validation will show up. If everything is correct, you can proceed and click on Submit Validation. A new page will open up, prompting you to accept the transaction. Here, please approve the transaction.

![](/images/aws13.png)

After the transaction is approved, you will see a message saying that your validation transaction was submitted.

![](/images/aws14.png)

If you click on View on explorer, a new browser tab will open with the details of the `AddValidatorTx`. It will show details such as the total value of LUX transferred, any LUX which were burned, the blockchainID, the blockID, the NodeID of the validator, and the total time which has elapsed from the entire Validation period.

![](/images/aws15.png)

Confirm That the Node is a Pending Validator on Testnet[​](#confirm-that-the-node-is-a-pending-validator-on-testnet "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------------------

As a last step you can call the `platform.getPendingvalidators` endpoint to confirm that the Lux node which was recently spun up on AWS is no in the pending validators queue where it will stay for 5 minutes.

### `platform.getPendingValidators` Request[​](#platformgetpendingvalidators-request "Direct link to heading")

```bash
curl --location --request POST 'https://api.lux-test.network/ext/bc/P' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "platform.getPendingValidators",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY",
        "nodeIDs": []
    },
    "id": 1
}'
```

### `platform.getPendingValidators` Response[​](#platformgetpendingvalidators-response "Direct link to heading")

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "4d7ZboCrND4FjnyNaF3qyosuGQsNeJ2R4KPJhHJ55VCU1Myjd",
        "startTime": "1673411918",
        "endTime": "1675313170",
        "stakeAmount": "1000000000",
        "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
        "delegationFee": "2.0000",
        "connected": false,
        "delegators": null
      }
    ],
    "delegators": []
  },
  "id": 1
}
```

You can also pass in the `NodeID` as a string to the `nodeIDs` array in the request body.

```bash
curl --location --request POST 'https://api.lux-test.network/ext/bc/P' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "platform.getPendingValidators",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY",
        "nodeIDs": ["NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5"]
    },
    "id": 1
}'
```

This will filter the response by the `nodeIDs` array which will save you time by no longer requiring you to search through the entire response body for the NodeIDs.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "4d7ZboCrND4FjnyNaF3qyosuGQsNeJ2R4KPJhHJ55VCU1Myjd",
        "startTime": "1673411918",
        "endTime": "1675313170",
        "stakeAmount": "1000000000",
        "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
        "delegationFee": "2.0000",
        "connected": false,
        "delegators": null
      }
    ],
    "delegators": []
  },
  "id": 1
}
```

After 5 minutes the node will officially start validating the Lux Testnet testnet and you will no longer see it in the response body for the `platform.getPendingValidators` endpoint. Now you will access it via the `platform.getCurrentValidators` endpoint.

### `platform.getCurrentValidators` Request[​](#platformgetcurrentvalidators-request "Direct link to heading")

```bash
curl --location --request POST 'https://api.lux-test.network/ext/bc/P' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "platform.getCurrentValidators",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY",
        "nodeIDs": ["NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5"]
    },
    "id": 1
}'
```

### `platform.getCurrentValidators` Response[​](#platformgetcurrentvalidators-response "Direct link to heading")

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "2hy57Z7KiZ8L3w2KonJJE1fs5j4JDzVHLjEALAHaXPr6VMeDhk",
        "startTime": "1673411918",
        "endTime": "1675313170",
        "stakeAmount": "1000000000",
        "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
        "rewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-testnet1tgj2c3k56enytw5d78rt0tsq3lzg8wnftffwk7"
          ]
        },
        "validationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-testnet1tgj2c3k56enytw5d78rt0tsq3lzg8wnftffwk7"
          ]
        },
        "delegationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-testnet1tgj2c3k56enytw5d78rt0tsq3lzg8wnftffwk7"
          ]
        },
        "potentialReward": "5400963",
        "delegationFee": "2.0000",
        "uptime": "0.0000",
        "connected": false,
        "delegators": null
      }
    ]
  },
  "id": 1
}
```

Mainnet[​](#mainnet "Direct link to heading")
---------------------------------------------

All of these steps can be applied to Mainnet. However, the minimum required Lux token amounts to become a validator is 2,000 on the Mainnet. For more information, please read [this doc](/docs/primary-network/validate/how-to-stake#validators).

Maintenance[​](#maintenance "Direct link to heading")
-----------------------------------------------------

AWS one click is meant to be used in automated environments, not as an end-user solution. You can still manage it manually, but it is not as easy as an Ubuntu instance or using the script:

- LuxGo binary is at `/usr/local/bin/luxgo`
- Main node config is at `/etc/luxgo/conf.json`
- Working directory is at `/home/lux/.luxgo/ (and belongs to luxgo user)`
- Database is at `/data/luxgo`
- Logs are at `/var/log/luxgo`

For a simple upgrade you would need to place the new binary at `/usr/local/bin/`. If you run an Lux L1, you would also need to place the VM binary into `/home/lux/.luxgo/plugins`.

You can also look at using [this guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-tutorial-update-ami.html), but that won't address updating the Lux L1, if you have one.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Lux is the first decentralized smart contracts platform built for the scale of global finance, with near-instant transaction finality. Now with an Lux Validator node available as a one-click install from the AWS Marketplace developers and entrepreneurs can on-ramp into the Lux ecosystem in a matter of minutes. If you have any questions or want to follow up in any way please join our Discord server at [https://discord.gg/lux](https://discord.gg/lux/). For more developer resources please check out our [Developer Documentation](/docs).

# Google Cloud (/docs/nodes/run-a-node/on-third-party-services/google-cloud)

---
title: Google Cloud
description: Learn how to run an Lux node on Google Cloud.
---

<Callout type="warn">
This document was written by a community member, some information may be outdated.
</Callout>

Introduction[​](#introduction "Direct link to heading")
-------------------------------------------------------

Google's Cloud Platform (GCP) is a scalable, trusted and reliable hosting platform. Google operates a significant amount of it's own global networking infrastructure. It's [fiber network](https://cloud.google.com/blog/products/networking/google-cloud-networking-in-depth-cloud-cdn) can provide highly stable and consistent global connectivity. In this article, we will leverage GCP to deploy a node on which Lux can installed via [terraform](https://www.terraform.io/). Leveraging `terraform` may seem like overkill, it should set you apart as an operator and administrator as it will enable you greater flexibility and provide the basis on which you can easily build further automation.

Conventions[​](#conventions "Direct link to heading")
-----------------------------------------------------

- `Items` highlighted in this manor are GCP parlance and can be searched for further reference in the Google documentation for their cloud products.

Important Notes[​](#important-notes "Direct link to heading")
-------------------------------------------------------------

- The machine type used in this documentation is for reference only and the actual sizing you use will depend entirely upon the amount that is staked and delegated to the node.

Architectural Description[​](#architectural-description "Direct link to heading")
---------------------------------------------------------------------------------

This section aims to describe the architecture of the system that the steps in the [Setup Instructions](#-setup-instructions) section deploy when enacted. This is done so that the executor can not only deploy the reference architecture, but also understand and potentially optimize it for their needs.

### Project[​](#project "Direct link to heading")

We will create and utilize a single GCP `Project` for deployment of all resources.

#### Service Enablement[​](#service-enablement "Direct link to heading")

Within our GCP project we will need to enable the following Cloud Services:

- `Compute Engine`
- `IAP`

### Networking[​](#networking "Direct link to heading")

#### Compute Network[​](#compute-network "Direct link to heading")

We will deploy a single `Compute Network` object. This unit is where we will deploy all subsequent networking objects. It provides a logical boundary and securitization context should you wish to deploy other chain stacks or other infrastructure in GCP.

#### Public IP[​](#public-ip "Direct link to heading")

Lux requires that a validator communicate outbound on the same public IP address that it advertises for other peers to connect to it on. Within GCP this precludes the possibility of us using a Cloud NAT Router for the outbound communications and requires us to bind the public IP that we provision to the interface of the machine. We will provision a single `EXTERNAL` static IPv4 `Compute Address`.

#### Lux L1s[​](#lux-l1s "Direct link to heading")

For the purposes of this documentation we will deploy a single `Compute Subnetwork` in the US-EAST1 `Region` with a /24 address range giving us 254 IP addresses (not all usable but for the sake of generalized documentation).

### Compute[​](#compute "Direct link to heading")

#### Disk[​](#disk "Direct link to heading")

We will provision a single 400GB `PD-SSD` disk that will be attached to our VM.

#### Instance[​](#instance "Direct link to heading")

We will deploy a single `Compute Instance` of size `e2-standard-8`. Observations of operations using this machine specification suggest it is memory over provisioned and could be brought down to 16GB using custom machine specification; but please review and adjust as needed (the beauty of compute virtualization!!).

#### Zone[​](#zone "Direct link to heading")

We will deploy our instance into the `US-EAST1-B` `Zone`

#### Firewall[​](#firewall "Direct link to heading")

We will provision the following `Compute Firewall` rules:

- IAP INGRESS for SSH (TCP 22) - this only allows GCP IAP sources inbound on SSH.
- P2P INGRESS for LUX Peers (TCP 9651)

These are obviously just default ports and can be tailored to your needs as you desire.

Setup Instructions[​](#-setup-instructions "Direct link to heading")
--------------------------------------------------------------------

### GCP Account[​](#gcp-account "Direct link to heading")

1.  If you don't already have a GCP account go create one [here](https://console.cloud.google.com/freetrial)

You will get some free bucks to run a trial, the trial is feature complete but your usage will start to deplete your free bucks so turn off anything you don't need and/or add a credit card to your account if you intend to run things long term to avoid service shutdowns.

### Project[​](#project-1 "Direct link to heading")

Login to the GCP `Cloud Console` and create a new `Project` in your organization. Let's use the name `my-lux-nodes` for the sake of this setup.

1.  ![Select Project Dropdown](/images/cloud1.png)

2.  ![Click New Project Button](/images/cloud2.png)

3.  ![Create New Project](/images/cloud3.png)

### Terraform State[​](#terraform-state "Direct link to heading")

Terraform uses a state files to compose a differential between current infrastructure configuration and the proposed plan. You can store this state in a variety of different places, but using GCP storage is a reasonable approach given where we are deploying so we will stick with that.

1.  ![Select Cloud Storage Browser](/images/cloud4.png)

2.  ![Create New Bucket](/images/cloud5.png)

Authentication to GCP from terraform has a few different options which are laid out [here](https://www.terraform.io/language/settings/backends/gcs). Please chose the option that aligns with your context and ensure those steps are completed before continuing.

<Callout title="Note">
Depending upon how you intend to execute your terraform operations you may or may not need to enable public access to the bucket. Obviously, not exposing the bucket for `public` access (even if authenticated) is preferable. If you intend to simply run terraform commands from your local machine then you will need to open the access up. I recommend to employ a full CI/CD pipeline using GCP Cloud Build which if utilized will mean the bucket can be marked as `private`. A full walk through of Cloud Build setup in this context can be found [here](https://cloud.google.com/architecture/managing-infrastructure-as-code)
</Callout>


### Clone GitHub Repository[​](#clone-github-repository "Direct link to heading")

I have provided a rudimentary terraform construct to provision a node on which to run Lux which can be found [here](https://github.com/meaghanfitzgerald/deprecated-lux-docs/tree/master/static/scripts). Documentation below assumes you are using this repository but if you have another terraform skeleton similar steps will apply.

### Terraform Configuration[​](#terraform-configuration "Direct link to heading")

1.  If running terraform locally, please [install](https://learn.hashicorp.com/tutorials/terraform/install-cli) it.
2.  In this repository, navigate to the `terraform` directory.
3.  Under the `projects` directory, rename the `my-lux-project` directory to match your GCP project name that you created (not required, but nice to be consistent)
4.  Under the folder you just renamed locate the `terraform.tfvars` file.
5.  Edit this file and populate it with the values which make sense for your context and save it.
6.  Locate the `backend.tf` file in the same directory.
7.  Edit this file ensuring to replace the `bucket` property with the GCS bucket name that you created earlier.

If you do not with to use cloud storage to persist terraform state then simply switch the `backend` to some other desirable provider.

### Terraform Execution[​](#terraform-execution "Direct link to heading")

Terraform enables us to see what it would do if we were to run it without actually applying any changes... this is called a `plan` operation. This plan is then enacted (optionally) by an `apply`.

#### Plan[​](#plan "Direct link to heading")

1.  In a terminal which is able to execute the `tf` binary, `cd` to the ~`my-lux-project` directory that you renamed in step 3 of `Terraform Configuration`.
2.  Execute the command `tf plan`
3.  You should see a JSON output to the stdout of the terminal which lays out the operations that terraform will execute to apply the intended state.

#### Apply[​](#apply "Direct link to heading")

1.  In a terminal which is able to execute the `tf` binary, `cd` to the ~`my-lux-project` directory that you renamed in step 3 of `Terraform Configuration`.
2.  Execute the command `tf apply`

If you want to ensure that terraform does **exactly** what you saw in the `apply` output, you can optionally request for the `plan` output to be saved to a file to feed to `apply`. This is generally considered best practice in highly fluid environments where rapid change is occurring from multiple sources.

Conclusion[​](#conclusion "Direct link to heading")
---------------------------------------------------

Establishing CI/CD practices using tools such as GitHub and Terraform to manage your infrastructure assets is a great way to ensure base disaster recovery capabilities and to ensure you have a place to embed any ~tweaks you have to make operationally removing the potential to miss them when you have to scale from 1 node to 10. Having an automated pipeline also gives you a place to build a bigger house... what starts as your interest in building and managing a single LUX node today can quickly change into you building an infrastructure operation for many different chains working with multiple different team members. I hope this may have inspired you to take a leap into automation in this context!

# Latitude (/docs/nodes/run-a-node/on-third-party-services/latitude)

---
title: Latitude
description: Learn how to run an Lux node on Latitude.sh.
---

Introduction[​](#introduction "Direct link to heading")
-------------------------------------------------------

This tutorial will guide you through setting up an Lux node on [Latitude.sh](https://latitude.sh/). Latitude.sh provides high-performance lighting-fast bare metal servers to ensure that your node is highly secure, available, and accessible.

To get started, you'll need:

- A Latitude.sh account
- A terminal with which to SSH into your Latitude.sh machine

For the instructions on creating an account and server with Latitude.sh, please reference their [GitHub tutorial](https://github.com/NottherealIllest/Latitude.sh-post/blob/main/avalanhe/lux-copy.md) , or visit [this page](https://www.latitude.sh/dashboard/signup) to sign up and create your first project.

This tutorial assumes your local machine has a Unix-style terminal. If you're on Windows, you'll have to adapt some of the commands used here.

Configuring Your Server[​](#configuring-your-server "Direct link to heading")
-----------------------------------------------------------------------------

### Create a Latitude.sh Account[​](#create-a-latitudesh-account "Direct link to heading")

At this point your account has been verified, and you have created a new project and deployed the server according to the instructions linked above.

### Access Your Server & Further Steps[​](#access-your-server--further-steps "Direct link to heading")

All your Latitude.sh credentials are available by clicking the `server` under your project, and can be used to access your Latitude.sh machine from your local machine using a terminal.

<Callout title="Note">
You will need to install the `lux node installer script` directly in the server's terminal.
</Callout>

After gaining access, we'll need to set up our Lux node. To do this, follow the instructions here to install and run your node [Set Up Lux Node With Installer](/docs/nodes/run-a-node/using-install-script/installing-lux-go).

Your LuxGo node should now be running and in the process of bootstrapping, which can take a few hours. To check if it's done, you can issue an API call using `curl`. The request is:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

Once the node is finished bootstrapping, the response will be:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isBootstrapped": true
  },
  "id": 1
}
```

You can continue on, even if LuxGo isn't done bootstrapping. In order to make your node a validator, you'll need its node ID. To get it, run:

```bash
curl -X POST --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The response contains the node ID.

```json
{
  "jsonrpc": "2.0",
  "result": { "nodeID": "KhDnAoZDW8iRJ3F26iQgK5xXVFMPcaYeu" },
  "id": 1
}
```

In the above example the node ID is `NodeID-KhDnAoZDW8iRJ3F26iQgK5xXVFMPcaYeu`.

LuxGo has other APIs, such as the [Health API](/docs/rpcs/other/health-rpc), that may be used to interact with the node. Some APIs are disabled by default. To enable such APIs, modify the ExecStart section of `/etc/systemd/system/luxgo.service` (created during the installation process) to include flags that enable these endpoints. Don't manually enable any APIs unless you have a reason to.

Exit out of the SSH server by running:

### Upgrading Your Node[​](#upgrading-your-node "Direct link to heading")

LuxGo is an ongoing project and there are regular version upgrades. Most upgrades are recommended but not required. Advance notice will be given for upgrades that are not backwards compatible. To update your node to the latest version, SSH into your server using a terminal and run the installer script again.

```bash
./luxgo-installer.sh
```

Your machine is now running the newest LuxGo version. To see the status of the LuxGo service, run `sudo systemctl status luxgo.`

Wrap Up[​](#wrap-up "Direct link to heading")
---------------------------------------------

That's it! You now have an LuxGo node running on a Latitude.sh machine. We recommend setting up [node monitoring](/docs/nodes/maintain/monitoring) for your LuxGo node.

# Microsoft Azure (/docs/nodes/run-a-node/on-third-party-services/microsoft-azure)

---
title: Microsoft Azure
description: How to run an Lux node on Microsoft Azure.
---

<Callout type="warn">
This document was written by a community member, some information may be out of date.
</Callout>

Running a validator and staking with Lux provides extremely competitive rewards of between 9.69% and 11.54% depending on the length you stake for. The maximum rate is earned by staking for a year, whilst the lowest rate for 14 days. There is also no slashing, so you don't need to worry about a hardware failure or bug in the client which causes you to lose part or all of your stake. Instead with Lux you only need to currently maintain at least 80% uptime to receive rewards. If you fail to meet this requirement you don't get slashed, but you don't receive the rewards. **You also do not need to put your private keys onto a node to begin validating on that node.** Even if someone breaks into your cloud environment and gains access to the node, the worst they can do is turn off the node.

Not only does running a validator node enable you to receive rewards in LUX, but later you will also be able to validate other Lux L1s in the ecosystem as well and receive rewards in the token native to their Lux L1s.

Hardware requirements to run a validator are relatively modest: 8 CPU cores, 16 GB of RAM and 1 TB SSD. It also doesn't use enormous amounts of energy. Lux's [revolutionary consensus mechanism](/docs/primary-network/lux-consensus) is able to scale to millions of validators participating in consensus at once, offering unparalleled decentralisation.

Currently the minimum amount required to stake to become a validator is 2,000 LUX. Alternatively, validators can also charge a small fee to enable users to delegate their stake with them to help towards running costs.
In this article we will step through the process of configuring a node on Microsoft Azure. This tutorial assumes no prior experience with Microsoft Azure and will go through each step with as few assumptions possible.

At the time of this article, spot pricing for a virtual machine with 2 Cores and 8 GB memory costs as little as 0.01060perhourwhichworksoutatabout0.01060 per hour which works out at about 113.44 a year, **a saving of 83.76%! compared to normal pay as you go prices.** In comparison a virtual machine in AWS with 2 Cores and 4 GB Memory with spot pricing is around $462 a year.

Initial Subscription Configuration[​](#initial-subscription-configuration "Direct link to heading")
---------------------------------------------------------------------------------------------------

### Set up 2 Factor[​](#set-up-2-factor "Direct link to heading")

First you will need a Microsoft Account, if you don't have one already you will see an option to create one at the following link. If you already have one, make sure to set up 2 Factor authentication to secure your node by going to the following link and then selecting "Two-step verification" and following the steps provided.

[https://account.microsoft.com/security](https://account.microsoft.com/security)

![Image for post](/images/azure1.png)

Once two factor has been configured log into the Azure portal by going to [https://portal.azure.com](https://portal.azure.com/) and signing in with your Microsoft account. When you login you won't have a subscription, so we need to create one first. Select "Subscriptions" as highlighted below:

![Image for post](/images/azure2.png)

Then select "+ Add" to add a new subscription

![Image for post](/images/azure3.png)

If you want to use Spot Instance VM Pricing (which will be considerably cheaper) you can't use a Free Trial account (and you will receive an error upon validation), so **make sure to select Pay-As-You-Go.**

![Image for post](/images/azure4.png)

Enter your billing details and confirm identity as part of the sign-up process, when you get to Add technical support select the without support option (unless you want to pay extra for support) and press Next.

![Image for post](/images/azure5.png)

Create a Virtual Machine[​](#create-a-virtual-machine "Direct link to heading")
-------------------------------------------------------------------------------

Now that we have a subscription, we can create the Ubuntu Virtual Machine for our Lux Node. Select the Icon in the top left for the Menu and choose "+ Create a resource"

![Image for post](/images/azure6.png)

Select Ubuntu Server 18.04 LTS (this will normally be under the popular section or alternatively search for it in the marketplace)

![Image for post](/images/azure7.png)

This will take you to the Create a virtual machine page as shown below:

![Image for post](/images/azure8.png)

First, enter a virtual machine a name, this can be anything but in my example, I have called it Lux (This will also automatically change the resource group name to match)

Then select a region from the drop-down list. Select one of the recommended ones in a region that you prefer as these tend to be the larger ones with most features enabled and cheaper prices. In this example I have selected North Europe.

![Image for post](/images/azure9.png)

You have the option of using spot pricing to save significant amounts on running costs. Spot instances use a supply and demand market price structure. As demand for instances goes up, the price for the spot instance goes up. If there is insufficient capacity, then your VM will be turned off. The chances of this happening are incredibly low though, especially if you select the Capacity only option. Even in the unlikely event it does get turned off temporarily you only need to maintain at least 80% up time to receive the staking rewards and there is no slashing implemented in Lux.

Select Yes for Azure Spot instance, select Eviction type to Capacity Only and **make sure to set the eviction policy to Stop / Deallocate. This is very important otherwise the VM will be deleted**

![Image for post](/images/azure10.png)

Choose "Select size" to change the Virtual Machine size, and from the menu select D2s\_v4 under the D-Series v4 selection (This size has 2 Cores, 8 GB Memory and enables Premium SSDs). You can use F2s\_v2 instances instead, with are 2 Cores, 4 GB Memory and enables Premium SSDs) but the spot price actually works out cheaper for the larger VM currently with spot instance prices. You can use [this link](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/) to view the prices across the different regions.

![Image for post](/images/azure11.png)

Once you have selected the size of the Virtual Machine, select "View pricing history and compare prices in nearby regions" to see how the spot price has changed over the last 3 months, and whether it's cheaper to use a nearby region which may have more spare capacity.

![Image for post](/images/azure12.png)

At the time of this article, spot pricing for D2s\_v4 in North Europe costs 0.07975perhour,oraround0.07975 per hour, or around 698.61 a year. With spot pricing, the price falls to 0.01295perhour,whichworksoutatabout0.01295 per hour, which works out at about 113.44 a year, **a saving of 83.76%!**

There are some regions which are even cheaper, East US for example is 0.01060perhouroraround0.01060 per hour or around 92.86 a year!

![Image for post](/images/azure13.png)

Below you can see the price history of the VM over the last 3 months for North Europe and regions nearby.

![Image for post](/images/azure14.png)

### Cheaper Than Amazon AWS[​](#cheaper-than-amazon-aws "Direct link to heading")

As a comparison a c5.large instance costs 0.085USDperhouronAWS.Thistotals 0.085 USD per hour on AWS. This totals ~745 USD per year. Spot instances can save 62%, bringing that total down to $462.

The next step is to change the username for the VM, to align with other Lux tutorials change the username to Ubuntu. Otherwise you will need to change several commands later in this article and swap out Ubuntu with your new username.

![Image for post](/images/azure15.png)

### Disks[​](#disks "Direct link to heading")

Select Next: Disks to then configure the disks for the instance. There are 2 choices for disks, either Premium SSD which offer greater performance with a 64 GB disk costs around 10amonth,orthereisthestandardSSDwhichofferslowerperformanceandisaround10 a month, or there is the standard SSD which offers lower performance and is around 5 a month. You also have to pay $0.002 per 10,000 transaction units (reads / writes and deletes) with the Standard SSD, whereas with Premium SSDs everything is included. Personally, I chose the Premium SSD for greater performance, but also because the disks are likely to be heavily used and so may even work out cheaper in the long run.

Select Next: Networking to move onto the network configuration

![Image for post](/images/azure16.png)

### Network Config[​](#network-config "Direct link to heading")

You want to use a Static IP so that the public IP assigned to the node doesn't change in the event it stops. Under Public IP select "Create new"

![Image for post](/images/azure17.png)

Then select "Static" as the Assignment type

![Image for post](/images/azure19.png)

Then we need to configure the network security group to control access inbound to the Lux node. Select "Advanced" as the NIC network security group type and select "Create new"

![Image for post](/images/azure20.png)

For security purposes you want to restrict who is able to remotely connect to your node. To do this you will first want to find out what your existing public IP is. This can be done by going to google and searching for "what's my IP"

![Image for post](/images/azure21.png)

It's likely that you have been assigned a dynamic public IP for your home, unless you have specifically requested it, and so your assigned public IP may change in the future. It's still recommended to restrict access to your current IP though, and then in the event your home IP changes and you are no longer able to remotely connect to the VM, you can just update the network security rules with your new public IP so you are able to connect again.

NOTE: If you need to change the network security group rules after deployment if your home IP has changed, search for "lux-nsg" and you can modify the rule for SSH and Port 9650 with the new IP. **Port 9651 needs to remain open to everyone** though as that's how it communicates with other Lux nodes.

![Image for post](/images/azure22.png)

Now that you have your public IP select the default allow ssh rule on the left under inbound rules to modify it. Change Source from "Any" to "IP Addresses" and then enter in your Public IP address that you found from google in the Source IP address field. Change the Priority towards the bottom to 100 and then press Save.

![Image for post](/images/azure23.png)

Then select "+ Add an inbound rule" to add another rule for RPC access, this should also be restricted to only your IP. Change Source to "IP Addresses" and enter in your public IP returned from google into the Source IP field. This time change the "Destination port ranges" field to 9650 and select "TCP" as the protocol. Change the priority to 110 and give it a name of "Lux\_RPC" and press Add.

![Image for post](/images/azure24.png)

Select "+ Add an inbound rule" to add a final rule for the Lux Protocol so that other nodes can communicate with your node. This rule needs to be open to everyone so keep "Source" set to "Any." Change the Destination port range to "9651" and change the protocol to "TCP." Enter a priority of 120 and a name of Lux\_Protocol and press Add.

![Image for post](/images/azure25.png)

The network security group should look like the below (albeit your public IP address will be different) and press OK.

![Image for post](/images/azure26.png)

Leave the other settings as default and then press "Review + create" to create the Virtual machine.

![Image for post](/images/azure27.png)

First it will perform a validation test. If you receive an error here, make sure you selected Pay-As-You-Go subscription model and you are not using the Free Trial subscription as Spot instances are not available. Verify everything looks correct and press "Create"

![Image for post](/images/azure28.png)

You should then receive a prompt asking you to generate a new key pair to connect your virtual machine. Select "Download private key and create resource" to download the private key to your PC.

![Image for post](/images/azure29.png)

Once your deployment has finished, select "Go to resource"

![Image for post](/images/azure30.png)

Change the Provisioned Disk Size[​](#change-the-provisioned-disk-size "Direct link to heading")
-----------------------------------------------------------------------------------------------

By default, the Ubuntu VM will be provisioned with a 30 GB Premium SSD. You should increase this to 250 GB, to allow for database growth.

![Image for post](/images/azure31.png)

To change the Disk size, the VM needs to be stopped and deallocated. Select "Stop" and wait for the status to show deallocated. Then select "Disks" on the left.

![Image for post](/images/azure32.png)

Select the Disk name that's current provisioned to modify it

![Image for post](/images/azure33.png)

Select "Size + performance" on the left under settings and change the size to 250 GB and press "Resize"

![Image for post](/images/azure34.png)

Doing this now will also extend the partition automatically within Ubuntu. To go back to the virtual machine overview page, select Lux in the navigation setting.

![Image for post](/images/azure35.png)

Then start the VM

![Image for post](/images/azure36.png)

Connect to the Lux Node[​](#connect-to-the-lux-node "Direct link to heading")
-----------------------------------------------------------------------------------------

The following instructions show how to connect to the Virtual Machine from a Windows 10 machine. For instructions on how to connect from a Ubuntu machine see the [AWS tutorial](/docs/nodes/run-a-node/on-third-party-services/amazon-web-services).

On your local PC, create a folder on the root of the C: drive called Lux and then move the Lux\_key.pem file you downloaded before into the folder. Then right click the file and select Properties. Go to the security tab and select "Advanced" at the bottom

![Image for post](/images/azure37.png)

Select "Disable inheritance" and then "Remove all inherited permissions from this object" to remove all existing permissions on that file.

![Image for post](/images/azure38.png)

Then select "Add" to add a new permission and choose "Select a principal" at the top. From the pop-up box enter in your user account that you use to log into your machine. In this example I log on with a local user called Seq, you may have a Microsoft account that you use to log in, so use whatever account you login to your PC with and press "Check Names" and it should underline it to verify and press OK.

![Image for post](/images/azure39.png)

Then from the permissions section make sure only "Read & Execute" and "Read" are selected and press OK.

![Image for post](/images/azure40.png)

It should look something like the below, except with a different PC name / user account. This just means the key file can't be modified or accessed by any other accounts on this machine for security purposes so they can't access your Lux Node.

![Image for post](/images/azure41.png)

### Find your Lux Node Public IP[​](#find-your-lux-node-public-ip "Direct link to heading")

From the Azure Portal make a note of your static public IP address that has been assigned to your node.

![Image for post](/images/azure42.png)

To log onto the Lux node, open command prompt by searching for `cmd` and selecting "Command Prompt" on your Windows 10 machine.

![Image for post](/images/azure43.png)

Then use the following command and replace the EnterYourAzureIPHere with the static IP address shown on the Azure portal.

ssh -i C:\\Lux\\Lux\_key.pem ubuntu@EnterYourAzureIPHere

for my example its:

ssh -i C:\\Lux\\Lux\_key.pem

The first time you connect you will receive a prompt asking to continue, enter yes.

![Image for post](/images/azure44.png)

You should now be connected to your Node.

![Image for post](/images/azure45.png)

The following section is taken from Colin's excellent tutorial for [configuring an Lux Node on Amazon's AWS](/docs/nodes/run-a-node/on-third-party-services/amazon-web-services).

### Update Linux with Security Patches[​](#update-linux-with-security-patches "Direct link to heading")

Now that we are on our node, it's a good idea to update it to the latest packages. To do this, run the following commands, one-at-a-time, in order:

```
sudo apt update
sudo apt upgrade -y
sudo reboot
```

![Image for post](/images/azure46.png)

This will make our instance up to date with the latest security patches for our operating system. This will also reboot the node. We'll give the node a minute or two to boot back up, then log in again, same as before.

### Set up the Lux Node[​](#set-up-the-lux-node "Direct link to heading")

Now we'll need to set up our Lux node. To do this, follow the [Set Up Lux Node With Installer](/docs/nodes/run-a-node/using-install-script/installing-lux-go) tutorial which automates the installation process. You will need the "IPv4 Public IP" copied from the Azure Portal we set up earlier.

Once the installation is complete, our node should now be bootstrapping! We can run the following command to take a peek at the latest status of the LuxGo node:

```
sudo systemctl status luxgo
```

To check the status of the bootstrap, we'll need to make a request to the local RPC using `curl`. This request is as follows:

```
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The node can take some time (upward of an hour at this moment writing) to bootstrap. Bootstrapping means that the node downloads and verifies the history of the chains. Give this some time. Once the node is finished bootstrapping, the response will be:

```
{
    "jsonrpc": "2.0",
    "result": {
        "isBootstrapped": true
    },
    "id": 1
}
```

We can always use `sudo systemctl status luxgo` to peek at the latest status of our service as before, as well.

### Get Your NodeID[​](#get-your-nodeid "Direct link to heading")

We absolutely must get our NodeID if we plan to do any validating on this node. This is retrieved from the RPC as well. We call the following curl command to get our NodeID.

```
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If all is well, the response should look something like:

```
{"jsonrpc":"2.0","result":{"nodeID":"NodeID-Lve2PzuCvXZrqn8Stqwy9vWZux6VyGUCR"},"id":1}
```

That portion that says, "NodeID-Lve2PzuCvXZrqn8Stqwy9vWZux6VyGUCR" is our NodeID, the entire thing. Copy that and keep that in our notes. There's nothing confidential or secure about this value, but it's an absolute must for when we submit this node to be a validator.

### Backup Your Staking Keys[​](#backup-your-staking-keys "Direct link to heading")

The last thing that should be done is backing up our staking keys in the untimely event that our instance is corrupted or terminated. It's just good practice for us to keep these keys. To back them up, we use the following command:

```
scp -i C:\Lux\lux_key.pem -r ubuntu@EnterYourAzureIPHere:/home/ubuntu/.luxgo/staking C:\Lux
```

As before, we'll need to replace "EnterYourAzureIPHere" with the appropriate value that we retrieved. This backs up our staking key and staking certificate into the C:\\Lux folder we created before.

![Image for post](/images/azure47.png)

# Installing LuxGo (/docs/nodes/run-a-node/using-install-script/installing-avalanche-go)

---
title: Installing LuxGo
description: Learn how to install LuxGo on your system.
---

## Running the Script

So, now that you prepared your system and have the info ready, let's get to it.

To download and run the script, enter the following in the terminal:

```bash
wget -nd -m https://raw.githubusercontent.com/luxfi/lux-docs/master/scripts/luxgo-installer.sh;\
chmod 755 luxgo-installer.sh;\
./luxgo-installer.sh
```

And we're off! The output should look something like this:

<Accordions>
<Accordion title="Click to see the Terminal output">
```bash
LuxGo installer
---------------------
Preparing environment...
Found arm64 architecture...
Looking for the latest arm64 build...
Will attempt to download:
 https://github.com/luxfi/luxgo/releases/download/v1.1.1/luxgo-linux-arm64-v1.1.1.tar.gz
luxgo-linux-arm64-v1.1.1.tar.gz 100%[=========================================================================>]  29.83M  75.8MB/s    in 0.4s
2020-12-28 14:57:47 URL:https://github-production-release-asset-2e65be.s3.amazonaws.com/246387644/f4d27b00-4161-11eb-8fb2-156a992fd2c8?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20201228%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20201228T145747Z&X-Amz-Expires=300&X-Amz-Signature=ea838877f39ae940a37a076137c4c2689494c7e683cb95a5a4714c062e6ba018&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=246387644&response-content-disposition=attachment%3B%20filename%3Dluxgo-linux-arm64-v1.1.1.tar.gz&response-content-type=application%2Foctet-stream [31283052/31283052] -> "luxgo-linux-arm64-v1.1.1.tar.gz" [1]
Unpacking node files...
luxgo-v1.1.1/plugins/
luxgo-v1.1.1/plugins/evm
luxgo-v1.1.1/luxgo
Node files unpacked into /home/ubuntu/lux-node
```
</Accordion>
</Accordions>

And then the script will prompt you for information about the network environment:

```bash
To complete the setup some networking information is needed.
Where is the node installed:
1) residential network (dynamic IP)
2) cloud provider (static IP)
Enter your connection type [1,2]:
```

Enter `1` if you have dynamic IP, and `2` if you have a static IP. If you are on a static IP, it will try to auto-detect the IP and ask for confirmation.

```bash
Detected '3.15.152.14' as your public IP. Is this correct? [y,n]:
```

Confirm with `y`, or `n` if the detected IP is wrong (or empty), and then enter the correct IP at the next prompt.

Next, you have to set up RPC port access for your node. Those are used to query the node for its internal state, to send commands to the node, or to interact with the platform and its chains (sending transactions, for example). You will be prompted:

```bash
RPC port should be public (this is a public API node) or private (this is a validator)? [public, private]:
```

- `private`: this setting only allows RPC requests from the node machine itself.
- `public`: this setting exposes the RPC port to all network interfaces.

As this is a sensitive setting you will be asked to confirm if choosing `public`. Please read the following note carefully:

<Callout title="Note">
If you choose to allow RPC requests on any network interface you will need to set up a firewall to only let through RPC requests from known IP addresses, otherwise your node will be accessible to anyone and might be overwhelmed by RPC calls from malicious actors! If you do not plan to use your node to send RPC calls remotely, enter `private`.
</Callout>

The script will then prompt you to choose whether to enable state sync setting or not:

```bash
Do you want state sync bootstrapping to be turned on or off? [on, off]:
```

Turning state sync on will greatly increase the speed of bootstrapping, but will sync only the current network state. If you intend to use your node for accessing historical data (archival node) you should select `off`. Otherwise, select `on`. Validators can be bootstrapped with state sync turned on.

The script will then continue with system service creation and finish with starting the service.

<Accordions>
<Accordion title="Click to see the final output">
```bash
Created symlink /etc/systemd/system/multi-user.target.wants/luxgo.service → /etc/systemd/system/luxgo.service.

Done!

Your node should now be bootstrapping.
Node configuration file is /home/ubuntu/.luxgo/configs/node.json
LUExchange-Chain configuration file is /home/ubuntu/.luxgo/configs/chains/C/config.json
Plugin directory, for storing subnet VM binaries, is /home/ubuntu/.luxgo/plugins
To check that the service is running use the following command (q to exit):
sudo systemctl status luxgo
To follow the log use (ctrl-c to stop):
sudo journalctl -u luxgo -f

Reach us over on https://discord.gg/lux if you're having problems.
```
</Accordion>
</Accordions>

The script is finished, and you should see the system prompt again.

## Post Installation

LuxGo should be running in the background as a service. You can check that it's running with:

```bash
sudo systemctl status luxgo
```

Below is an example of what the node's latest logs should look like:

<Accordions>
<Accordion title="Click to expand and see the Logs">
```bash
● luxgo.service - LuxGo systemd service
Loaded: loaded (/etc/systemd/system/luxgo.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2021-01-05 10:38:21 UTC; 51s ago
Main PID: 2142 (luxgo)
Tasks: 8 (limit: 4495)
Memory: 223.0M
CGroup: /system.slice/luxgo.service
└─2142 /home/ubuntu/lux-node/luxgo --public-ip-resolution-service=opendns --http-host=

Jan 05 10:38:45 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:38:45] <P Chain> luxgo/vms/platformvm/vm.go#322: initializing last accepted block as 2FUFPVPxbTpKNn39moGSzsmGroYES4NZRdw3mJgNvMkMiMHJ9e
Jan 05 10:38:45 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:38:45] <P Chain> luxgo/snow/engine/snowman/transitive.go#58: initializing consensus engine
Jan 05 10:38:45 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:38:45] luxgo/api/server.go#143: adding route /ext/bc/11111111111111111111111111111111LpoYY
Jan 05 10:38:45 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:38:45] luxgo/api/server.go#88: HTTP API server listening on ":9650"
Jan 05 10:38:58 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:38:58] <P Chain> luxgo/snow/engine/common/bootstrapper.go#185: Bootstrapping started syncing with 1 vertices in the accepted frontier
Jan 05 10:39:02 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:39:02] <P Chain> luxgo/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 2500 blocks
Jan 05 10:39:04 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:39:04] <P Chain> luxgo/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 5000 blocks
Jan 05 10:39:06 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:39:06] <P Chain> luxgo/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 7500 blocks
Jan 05 10:39:09 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:39:09] <P Chain> luxgo/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 10000 blocks
Jan 05 10:39:11 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:39:11] <P Chain> luxgo/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 12500 blocks
```
</Accordion>
</Accordions>

Note the `active (running)` which indicates the service is running OK. You may need to press `q` to return to the command prompt.

To find out your NodeID, which is used to identify your node to the network, run the following command:

```bash
sudo journalctl -u luxgo | grep "NodeID"
```

It will produce output like:

```bash
Jan 05 10:38:38 ip-172-31-30-64 luxgo[2142]: INFO [01-05|10:38:38] luxgo/node/node.go#428: Set node's ID to 6seStrauyCnVV7NEVwRbfaT9B6EnXEzfY
```

Prepend `NodeID-` to the value to get, for example, `NodeID-6seStrauyCnVV7NEVwRbfaT9B6EnXEzfY`. Store that; it will be needed for staking or looking up your node.

Your node should be in the process of bootstrapping now. You can monitor the progress by issuing the following command:

```bash
sudo journalctl -u luxgo -f
```

Press `ctrl+C` when you wish to stop reading node output.

# Managing LuxGo (/docs/nodes/run-a-node/using-install-script/managing-avalanche-go)

---
title: Managing LuxGo
description: Learn how to start, stop and upgrade your LuxGo node
---

## Stop Your Node

To stop LuxGo, run:

```bash
sudo systemctl stop luxgo
```

## Start Your Node

To start your node again, run:

```bash
sudo systemctl start luxgo
```

## Upgrade Your Node

LuxGo is an ongoing project and there are regular version upgrades. Most upgrades are recommended but not required. Advance notice will be given for upgrades that are not backwards compatible. When a new version of the node is released, you will notice log lines like:

```bash
Jan 08 10:26:45 ip-172-31-16-229 luxgo[6335]: INFO [01-08|10:26:45] luxgo/network/peer.go#526: beacon 9CkG9MBNavnw7EVSRsuFr7ws9gascDQy3 attempting to connect with newer version lux/1.1.1. You may want to update your client
```

It is recommended to always upgrade to the latest version, because new versions bring bug fixes, new features and upgrades.

To upgrade your node, just run the installer script again:

```bash
./luxgo-installer.sh
```

It will detect that you already have LuxGo installed:

```bash
LuxGo installer
---------------------
Preparing environment...
Found 64bit Intel/AMD architecture...
Found LuxGo systemd service already installed, switching to upgrade mode.
Stopping service...
```

It will then upgrade your node to the latest version, and after it's done, start the node back up, and print out the information about the latest version:

```bash
Node upgraded, starting service...
New node version:
lux/1.1.1 [network=mainnet, database=v1.0.0, commit=f76f1fd5f99736cf468413bbac158d6626f712d2]
Done!
```


# Node Config and Maintenance (/docs/nodes/run-a-node/using-install-script/node-config-maintenance)

---
title: Node Config and Maintenance
description: Advanced options for configuring and maintaining your LuxGo node.
---

## Advanced Node Configuration

Without any additional arguments, the script installs the node in a most common configuration. But the script also enables various advanced options to be configured, via the command line prompts. Following is a list of advanced options and their usage:

- `admin` - [Admin API](/docs/rpcs/other/admin-rpc) will be enabled
- `archival` - disables database pruning and preserves the complete transaction history
- `state-sync` - if `on` state-sync for the LUExchange-Chain is used, if `off` it will use regular transaction replay to bootstrap; state-sync is much faster, but has no historical data
- `db-dir` - use to provide the full path to the location where the database will be stored
- `testnet` - node will connect to Testnet testnet instead of the Mainnet
- `index` - [Index API](/docs/rpcs/other/index-rpc) will be enabled
- `ip` - use `dynamic`, `static` arguments, of enter a desired IP directly to be used as the public IP node will advertise to the network
- `rpc` - use `any` or `local` argument to select any or local network interface to be used to listen for RPC calls
- `version` - install a specific node version, instead of the latest. See [here](#using-a-previous-version) for usage.

<Callout title="Note">
Configuring the `index` and `archival` options on an existing node will require a fresh bootstrap to recreate the database.
</Callout>

Complete script usage can be displayed by entering:

```bash
./luxgo-installer.sh --help
```

### Unattended Installation[​](#unattended-installation "Direct link to heading")

If you want to use the script in an automated environment where you cannot enter the data at the prompts you must provide at least the `rpc` and `ip` options. For example:

```bash
./luxgo-installer.sh --ip 1.2.3.4 --rpc local
```

### Usage Examples[​](#usage-examples "Direct link to heading")

- To run a Testnet node with indexing enabled and autodetected static IP:        
    ```bash
    ./luxgo-installer.sh --testnet --ip static --index
    ```   
- To run an archival Mainnet node with dynamic IP and database located at `/home/node/db`:      
    ```bash
    ./luxgo-installer.sh --archival --ip dynamic --db-dir /home/node/db
    ```  
- To use LUExchange-Chain state-sync to quickly bootstrap a Mainnet node, with dynamic IP and local RPC only:       
    ```bash
    ./luxgo-installer.sh --state-sync on --ip dynamic --rpc local
    ```   
- To reinstall the node using node version 1.7.10 and use specific IP and local RPC only:     
    ```bash
    ./luxgo-installer.sh --reinstall --ip 1.2.3.4 --version v1.7.10 --rpc local
    ```

Node Configuration[​](#node-configuration "Direct link to heading")
-------------------------------------------------------------------

The file that configures node operation is `~/.luxgo/configs/node.json`. You can edit it to add or change configuration options. The documentation of configuration options can be found [here](/docs/nodes/configure/configs-flags). Configuration may look like this:

```json
{
  "public-ip-resolution-service": "opendns",
  "http-host": ""
}
```

Note that the configuration file needs to be a properly formatted `JSON` file, so switches should formatted differently than they would be for the command line. Therefore, don't enter options like `--public-ip-resolution-service=opendns` as shown in the example above.

The script also creates an empty LUExchange-Chain config file, located at `~/.luxgo/configs/chains/C/config.json`. By editing that file, you can configure the LUExchange-Chain, as described in detail [here](/docs/nodes/configure/configs-flags).

Using a Previous Version[​](#using-a-previous-version "Direct link to heading")
-------------------------------------------------------------------------------

The installer script can also be used to install a version of LuxGo other than the latest version.

To see a list of available versions for installation, run:

```bash
./luxgo-installer.sh --list
```

It will print out a list, something like:

```bash
LuxGo installer
---------------------
Available versions:
v1.3.2
v1.3.1
v1.3.0
v1.2.4-arm-fix
v1.2.4
v1.2.3-signed
v1.2.3
v1.2.2
v1.2.1
v1.2.0
```

To install a specific version, run the script with `--version` followed by the tag of the version. For example:

```bash
./luxgo-installer.sh --version v1.3.1
```

<Callout type="warn">
Note that not all LuxGo versions are compatible. You should generally run the latest version. Running a version other than latest may lead to your node not working properly and, for validators, not receiving a staking reward.
</Callout>

Thanks to community member [Jean Zundel](https://github.com/jzu) for the inspiration and help implementing support for installing non-latest node versions.

Reinstall and Script Update[​](#reinstall-and-script-update "Direct link to heading")
-------------------------------------------------------------------------------------

The installer script gets updated from time to time, with new features and capabilities added. To take advantage of new features or to recover from modifications that made the node fail, you may want to reinstall the node. To do that, fetch the latest version of the script from the web with:

```bash
wget -nd -m https://raw.githubusercontent.com/luxfi/lux-build/master/scripts/luxgo-installer.sh
```

After the script has updated, run it again with the `--reinstall` config flag:

```bash
./luxgo-installer.sh --reinstall
```

This will delete the existing service file, and run the installer from scratch, like it was started for the first time. Note that the database and NodeID will be left intact.

Removing the Node Installation[​](#removing-the-node-installation "Direct link to heading")
-------------------------------------------------------------------------------------------

If you want to remove the node installation from the machine, you can run the script with the `--remove` option, like this:

```bash
./luxgo-installer.sh --remove
```

This will remove the service, service definition file and node binaries. It will not remove the working directory, node ID definition or the node database. To remove those as well, you can type:


<Callout type="warn">
Please note that this is irreversible and the database and node ID will be deleted!
</Callout>

What Next?[​](#what-next "Direct link to heading")
--------------------------------------------------

That's it, you're running an LuxGo node! Congratulations! Let us know you did it on our [X](https://x.com/lux), [Telegram](https://t.me/luxlux) or [Reddit](https://www.reddit.com/r/Lux/)!

If you're on a residential network (dynamic IP), don't forget to set up port forwarding. If you're on a cloud service provider, you're good to go.

Now you can [interact with your node](/docs/rpcs/other/guides/issuing-api-calls), [stake your tokens](/docs/primary-network/validate/what-is-staking), or level up your installation by setting up [node monitoring](/docs/nodes/maintain/monitoring) to get a better insight into what your node is doing. Also, you might want to use our [Postman Collection](/docs/tooling/lux-postman) to more easily issue commands to your node.

Finally, if you haven't already, it is a good idea to [back up](/docs/nodes/maintain/backup-restore) important files in case you ever need to restore your node to a different machine.

If you have any questions, or need help, feel free to contact us on our [Discord](https://chat.avalabs.org/) server.

# Preparing Your Environment (/docs/nodes/run-a-node/using-install-script/preparing-environment)

---
title: Preparing Your Environment
description: Learn how to prepare your environment before using install script.
---

We have a shell (bash) script that installs LuxGo on your computer. This script sets up full, running node in a matter of minutes with minimal user input required. Script can also be used for unattended, automated installs.

This install script assumes:

- LuxGo is not running and not already installed as a service
- User running the script has superuser privileges (can run `sudo`)

Environment Considerations[​](#environment-considerations "Direct link to heading")
-----------------------------------------------------------------------------------

If you run a different flavor of Linux, the script might not work as intended. It assumes `systemd` is used to run system services. Other Linux flavors might use something else, or might have files in different places than is assumed by the script. It will probably work on any distribution that uses `systemd` but it has been developed for and tested on Ubuntu.

If you have a node already running on the computer, stop it before running the script. Script won't touch the node working directory so you won't need to bootstrap the node again.

### Node Running from Terminal[​](#node-running-from-terminal "Direct link to heading")

If your node is running in a terminal stop it by pressing `ctrl+C`.

### Node Running as a Service[​](#node-running-as-a-service "Direct link to heading")

If your node is already running as a service, then you probably don't need this script. You're good to go.

### Node Running in the Background[​](#node-running-in-the-background "Direct link to heading")

If your node is running in the background (by running with `nohup`, for example) then find the process running the node by running `ps aux | grep lux`. This will produce output like:

```bash
ubuntu  6834  0.0  0.0   2828   676 pts/1    S+   19:54   0:00 grep lux
ubuntu  2630 26.1  9.4 2459236 753316 ?      Sl   Dec02 1220:52 /home/ubuntu/build/luxgo
```

Look for line that doesn't have `grep` on it. In this example, that is the second line. It shows information about your node. Note the process id, in this case, `2630`. Stop the node by running `kill -2 2630`.

### Node Working Files[​](#node-working-files "Direct link to heading")

If you previously ran an LuxGo node on this computer, you will have local node files stored in `$HOME/.luxgo` directory. Those files will not be disturbed, and node set up by the script will continue operation with the same identity and state it had before. That being said, for your node's security, back up `staker.crt` and `staker.key` files, found in `$HOME/.luxgo/staking` and store them somewhere secure. You can use those files to recreate your node on a different computer if you ever need to. Check out this [tutorial](/docs/nodes/maintain/backup-restore) for backup and restore procedure.

Networking Considerations[​](#networking-considerations "Direct link to heading")
---------------------------------------------------------------------------------

To run successfully, LuxGo needs to accept connections from the Internet on the network port `9651`. Before you proceed with the installation, you need to determine the networking environment your node will run in.

### Running on a Cloud Provider[​](#running-on-a-cloud-provider "Direct link to heading")

If your node is running on a cloud provider computer instance, it will have a static IP. Find out what that static IP is, or set it up if you didn't already. The script will try to find out the IP by itself, but that might not work in all environments, so you will need to check the IP or enter it yourself.

### Running on a Home Connection[​](#running-on-a-home-connection "Direct link to heading")

If you're running a node on a computer that is on a residential internet connection, you have a dynamic IP; that is, your IP will change periodically. The install script will configure the node appropriately for that situation. But, for a home connection, you will need to set up inbound port forwarding of port `9651` from the internet to the computer the node is installed on.

As there are too many models and router configurations, we cannot provide instructions on what exactly to do, but there are online guides to be found (like [this](https://www.noip.com/support/knowledgebase/general-port-forwarding-guide/), or [this](https://www.howtogeek.com/66214/how-to-forward-ports-on-your-router/) ), and your service provider support might help too.

<Callout type="warn">
Please note that a fully connected Lux node maintains and communicates over a couple of thousand of live TCP connections. For some low-powered and older home routers that might be too much to handle. If that is the case you may experience lagging on other computers connected to the same router, node getting benched, failing to sync and similar issues.
</Callout>

# Banff Changes (/docs/rpcs/other/guides/banff-changes)

---
title: Banff Changes
description: This document specifies the changes in Lux “Banff”, which was released in LuxGo v1.9.x.
---
Block Changes[​](#block-changes "Direct link to heading")
---------------------------------------------------------

### Apricot[​](#apricot "Direct link to heading")

Apricot allows the following block types with the following content:

- _Standard Blocks_ may contain multiple transactions of the following types:
    - CreateChainTx
    - CreateSubnetTx
    - ImportTx
    - ExportTx
- _Proposal Blocks_ may contain a single transaction of the following types:
    - AddValidatorTx
    - AddDelegatorTx
    - AddSubnetValidatorTx
    - RewardValidatorTx
    - AdvanceTimeTx
- _Options Blocks_, that is _Commit Block_ and _Abort Block_ do not contain any transactions.

Each block has a header containing:

- ParentID
- Height

### Banff[​](#banff "Direct link to heading")

Banff allows the following block types with the following content:

- _Standard Blocks_ may contain multiple transactions of the following types:
    
    - CreateChainTx
    - CreateSubnetTx
    - ImportTx
    - ExportTx
    - AddValidatorTx
    - AddDelegatorTx
    - AddSubnetValidatorTx
    - _RemoveSubnetValidatorTx_
    - _TransformSubnetTx_
    - _AddPermissionlessValidatorTx_
    - _AddPermissionlessDelegatorTx_
- _Proposal Blocks_ may contain a single transaction of the following types:
    
    - RewardValidatorTx
- _Options blocks_, that is _Commit Block_ and _Abort Block_ do not contain any transactions.
    

Note that each block has an header containing:

- ParentID
- Height
- _Time_

So the two main differences with respect to Apricot are:

- _AddValidatorTx_, _AddDelegatorTx_, _AddSubnetValidatorTx_ are included into Standard Blocks rather than Proposal Blocks so that they don't need to be voted on (that is followed by a Commit/Abort Block).
- New Transaction types: _RemoveSubnetValidatorTx_, _TransformSubnetTx_, _AddPermissionlessValidatorTx_, and _AddPermissionlessDelegatorTx_ have been added into Standard Blocks.
- Block timestamp is explicitly serialized into block header, to allow chain time update.

### New Transactions[​](#new-transactions "Direct link to heading")

#### RemoveSubnetValidatorTx[​](#removesubnetvalidatortx "Direct link to heading")

```
type RemoveSubnetValidatorTx struct {
	BaseTx `serialize:"true"`
	// The node to remove from the Lux L1.
	NodeID ids.NodeID `serialize:"true" json:"nodeID"`
	// The Lux L1 to remove the node from.
	Subnet ids.ID `serialize:"true" json:"subnet"`
	// Proves that the issuer has the right to remove the node from the Lux L1.
SubnetAuth verify.Verifiable `serialize:"true" json:"subnetAuthorization"`
}
```

#### TransformSubnetTx[​](#transformsubnettx "Direct link to heading")

```
type TransformSubnetTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// ID of the Subnet to transform
	// Restrictions:
	// - Must not be the Primary Network ID
	Subnet ids.ID `serialize:"true" json:"subnetID"`
	// Asset to use when staking on the Lux L1
	// Restrictions:
	// - Must not be the Empty ID
	// - Must not be the LUX ID
	AssetID ids.ID `serialize:"true" json:"assetID"`
	// Amount to initially specify as the current supply
	// Restrictions:
	// - Must be > 0
	InitialSupply uint64 `serialize:"true" json:"initialSupply"`
	// Amount to specify as the maximum token supply
	// Restrictions:
	// - Must be >= [InitialSupply]
	MaximumSupply uint64 `serialize:"true" json:"maximumSupply"`
	// MinConsumptionRate is the rate to allocate funds if the validator's stake
	// duration is 0
	MinConsumptionRate uint64 `serialize:"true" json:"minConsumptionRate"`
	// MaxConsumptionRate is the rate to allocate funds if the validator's stake
	// duration is equal to the minting period
	// Restrictions:
	// - Must be >= [MinConsumptionRate]
	// - Must be <= [reward.PercentDenominator]
	MaxConsumptionRate uint64 `serialize:"true" json:"maxConsumptionRate"`
	// MinValidatorStake is the minimum amount of funds required to become a
	// validator.
	// Restrictions:
	// - Must be > 0
	// - Must be <= [InitialSupply]
	MinValidatorStake uint64 `serialize:"true" json:"minValidatorStake"`
	// MaxValidatorStake is the maximum amount of funds a single validator can
	// be allocated, including delegated funds.
	// Restrictions:
	// - Must be >= [MinValidatorStake]
	// - Must be <= [MaximumSupply]
	MaxValidatorStake uint64 `serialize:"true" json:"maxValidatorStake"`
	// MinStakeDuration is the minimum number of seconds a staker can stake for.
	// Restrictions:
	// - Must be > 0
	MinStakeDuration uint32 `serialize:"true" json:"minStakeDuration"`
	// MaxStakeDuration is the maximum number of seconds a staker can stake for.
	// Restrictions:
	// - Must be >= [MinStakeDuration]
	// - Must be <= [GlobalMaxStakeDuration]
	MaxStakeDuration uint32 `serialize:"true" json:"maxStakeDuration"`
	// MinDelegationFee is the minimum percentage a validator must charge a
	// delegator for delegating.
	// Restrictions:
	// - Must be <= [reward.PercentDenominator]
	MinDelegationFee uint32 `serialize:"true" json:"minDelegationFee"`
	// MinDelegatorStake is the minimum amount of funds required to become a
	// delegator.
	// Restrictions:
	// - Must be > 0
	MinDelegatorStake uint64 `serialize:"true" json:"minDelegatorStake"`
	// MaxValidatorWeightFactor is the factor which calculates the maximum
	// amount of delegation a validator can receive.
	// Note: a value of 1 effectively disables delegation.
	// Restrictions:
	// - Must be > 0
	MaxValidatorWeightFactor byte `serialize:"true" json:"maxValidatorWeightFactor"`
	// UptimeRequirement is the minimum percentage a validator must be online
	// and responsive to receive a reward.
	// Restrictions:
	// - Must be <= [reward.PercentDenominator]
	UptimeRequirement uint32 `serialize:"true" json:"uptimeRequirement"`
	// Authorizes this transformation
SubnetAuth verify.Verifiable `serialize:"true" json:"subnetAuthorization"`
}
```

#### AddPermissionlessValidatorTx[​](#addpermissionlessvalidatortx "Direct link to heading")

```
type AddPermissionlessValidatorTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// Describes the validator
	Validator validator.Validator `serialize:"true" json:"validator"`
	// ID of the Lux L1 this validator is validating
	Subnet ids.ID `serialize:"true" json:"subnet"`
	// Where to send staked tokens when done validating
	StakeOuts []*lux.TransferableOutput `serialize:"true" json:"stake"`
	// Where to send validation rewards when done validating
	ValidatorRewardsOwner fx.Owner `serialize:"true" json:"validationRewardsOwner"`
	// Where to send delegation rewards when done validating
	DelegatorRewardsOwner fx.Owner `serialize:"true" json:"delegationRewardsOwner"`
	// Fee this validator charges delegators as a percentage, times 10,000
	// For example, if this validator has DelegationShares=300,000 then they
	// take 30% of rewards from delegators
	DelegationShares uint32 `serialize:"true" json:"shares"`
}
```

#### AddPermissionlessDelegatorTx[​](#addpermissionlessdelegatortx "Direct link to heading")

```
type AddPermissionlessDelegatorTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// Describes the validator
	Validator validator.Validator `serialize:"true" json:"validator"`
	// ID of the Lux L1 this validator is validating
	Subnet ids.ID `serialize:"true" json:"subnet"`
	// Where to send staked tokens when done validating
	Stake []*lux.TransferableOutput `serialize:"true" json:"stake"`
	// Where to send staking rewards when done validating
	RewardsOwner fx.Owner `serialize:"true" json:"rewardsOwner"`
}
```

#### New TypeIDs[​](#new-typeids "Direct link to heading")

```
ApricotProposalBlock = 0
ApricotAbortBlock = 1
ApricotCommitBlock = 2
ApricotStandardBlock = 3
ApricotAtomicBlock = 4

secp256k1fx.TransferInput = 5
secp256k1fx.MintOutput = 6
secp256k1fx.TransferOutput = 7
secp256k1fx.MintOperation = 8
secp256k1fx.Credential = 9
secp256k1fx.Input = 10
secp256k1fx.OutputOwners = 11

AddValidatorTx = 12
AddSubnetValidatorTx = 13
AddDelegatorTx = 14
CreateChainTx = 15
CreateSubnetTx = 16
ImportTx = 17
ExportTx = 18
AdvanceTimeTx = 19
RewardValidatorTx = 20

stakeable.LockIn = 21
stakeable.LockOut = 22

RemoveSubnetValidatorTx = 23
TransformSubnetTx = 24
AddPermissionlessValidatorTx = 25
AddPermissionlessDelegatorTx = 26

EmptyProofOfPossession = 27
BLSProofOfPossession   = 28

BanffProposalBlock = 29
BanffAbortBlock = 30
BanffCommitBlock = 31
BanffStandardBlock = 32

```



# Flow of a Single Blockchain (/docs/rpcs/other/guides/blockchain-flow)

---
title: Flow of a Single Blockchain
---
![](/images/flow1.png)

Intro[​](#intro "Direct link to heading")
-----------------------------------------

The Lux network consists of 3 built-in blockchains: Exchange-Chain, LUExchange-Chain, and Platform-Chain. The Exchange-Chain is used to manage assets and uses the Lux consensus protocol. The LUExchange-Chain is used to create and interact with smart contracts and uses the Snowman consensus protocol. The Platform-Chain is used to coordinate validators and stake and also uses the Snowman consensus protocol. At the time of writing, the Lux network has ~1200 validators. A set of validators makes up an Lux L1. Lux L1s can validate 1 or more chains. It is a common misconception that 1 Lux L1 = 1 chain and this is shown by the primary Lux L1 of Lux which is made up of the Exchange-Chain, LUExchange-Chain, and Platform-Chain.

A node in the Lux network can either be a validator or a non-validator. A validator stakes LUX tokens and participates in consensus to earn rewards. A non-validator does not participate in consensus or have any LUX staked but can be used as an API server. Both validators and non-validators need to have their own copy of the chain and need to know the current state of the network. At the time of writing, there are ~1200 validators and ~1800 non-validators.

Each blockchain on Lux has several components: the virtual machine, database, consensus engine, sender, and handler. These components help the chain run smoothly. Blockchains also interact with the P2P layer and the chain router to send and receive messages.

Peer-to-Peer (P2P)[​](#peer-to-peer-p2p "Direct link to heading")
-----------------------------------------------------------------

### Outbound Messages[​](#outbound-messages "Direct link to heading")

[The `OutboundMsgBuilder` interface](https://github.com/luxfi/luxgo/blob/master/message/outbound_msg_builder.go) specifies methods that build messages of type `OutboundMessage`. Nodes communicate to other nodes by sending `OutboundMessage` messages.

All messaging functions in `OutboundMsgBuilder` can be categorized as follows:

- **Handshake**
    - Nodes need to be on a certain version before they can be accepted into the network.
- **State Sync**
    - A new node can ask other nodes for the current state of the network. It only syncs the required state for a specific block.
- **Bootstrapping**
    - Nodes can ask other nodes for blocks to build their own copy of the chain. A node can fetch all blocks from the locally last accepted block to the current last accepted block in the network.
- **Consensus**
    - Once a node is up to tip they can participate in consensus! During consensus, a node conducts a poll to several different small random samples of the validator set. They can communicate decisions on whether or not they have accepted/rejected a block.
- **App**
    - VMs communicate application-specific messages to other nodes through app messages. A common example is mempool gossiping.

Currently, LuxGo implements its own message serialization to communicate. In the future, LuxGo will use protocol buffers to communicate.

### Network[​](#network "Direct link to heading")

[The networking interface](https://github.com/luxfi/luxgo/blob/master/network/network.go) is shared across all chains. It implements functions from the `ExternalSender` interface. The two functions it implements are `Send` and `Gossip`. `Send` sends a message of type `OutboundMessage` to a specific set of nodes (specified by an array of `NodeIDs`). `Gossip` sends a message of type `OutboundMessage` to a random group of nodes in an Lux L1 (can be a validator or a non-validator). Gossiping is used to push transactions across the network. The networking protocol uses TLS to pass messages between peers.

Along with sending and gossiping, the networking library is also responsible for making connections and maintaining connections. Any node, either a validator or non-validator, will attempt to connect to the primary network.

Router[​](#router "Direct link to heading")
-------------------------------------------

[The `ChainRouter`](https://github.com/luxfi/luxgo/blob/master/snow/networking/router/chain_router.go) routes all incoming messages to its respective blockchain using `ChainID`. It does this by pushing all the messages onto the respective Chain handler's queue. The `ChainRouter` references all existing chains on the network such as the X-chain, C-chain, P-chain and possibly any other chain. The `ChainRouter` handles timeouts as well. When sending messages on the P2P layer, timeouts are registered on the sender and cleared on the `ChainRouter` side when a response is received. If no response is received, then it triggers a timeout. Because timeouts are handled on the `ChainRouter` side, the handler is reliable. Timeouts are triggered when peers do not respond and the `ChainRouter` will still notify the handler of failure cases. The timeout manager within `ChainRouter` is also adaptive. If the network is experiencing long latencies, timeouts will then be adjusted as well.

Handler[​](#handler "Direct link to heading")
---------------------------------------------

The main function of [the `Handler`](https://github.com/luxfi/luxgo/blob/master/snow/networking/handler/handler.go) is to pass messages from the network to the consensus engine. It receives these messages from the `ChainRouter`. It passes messages by pushing them onto a sync or Async queue (depends on message type). Messages are then popped from the queue, parsed, and routed to the correct function in consensus engine. This can be one of the following.

- **State sync message (sync queue)**
- **Bootstrapping message (sync queue)**
- **Consensus message (sync queue)**
- **App message (Async queue)**

Sender[​](#sender "Direct link to heading")
-------------------------------------------

The main role of [the `sender`](https://github.com/luxfi/luxgo/blob/master/snow/networking/sender/sender.go) is to build and send outbound messages. It is actually a very thin wrapper around the normal networking code. The main difference here is that sender registers timeouts and tells the router to expect a response message. The timer starts on the sender side. If there is no response, sender will send a failed response to the router. If a node is repeatedly unresponsive, that node will get benched and the sender will immediately start marking those messages as failed. If a sufficient amount of network deems the node benched, it might not get rewards (as a validator).

Consensus Engine[​](#consensus-engine "Direct link to heading")
---------------------------------------------------------------

Consensus is defined as getting a group of distributed systems to agree on an outcome. In the case of the Lux network, consensus is achieved when validators are in agreement with the state of the blockchain. The novel consensus algorithm is documented in the [white paper](https://assets.website-files.com/5d80307810123f5ffbb34d6e/6009805681b416f34dcae012_Lux%20Consensus%20Whitepaper.pdf). There are two main consensus algorithms: Lux and [Snowman](https://github.com/luxfi/luxgo/blob/master/snow/consensus/snowman/consensus.go). The engine is responsible for adding proposing a new block to consensus, repeatedly polling the network for decisions (accept/reject), and communicating that decision to the `Sender`.

Blockchain Creation[​](#blockchain-creation "Direct link to heading")
---------------------------------------------------------------------

[The `Manager`](https://github.com/luxfi/luxgo/blob/master/chains/manager.go) is what kick-starts everything in regards to blockchain creation, starting with the Platform-Chain. Once the Platform-Chain finishes bootstrapping, it will kickstart LUExchange-Chain and Exchange-Chain and any other chains. The `Manager`'s job is not done yet, if a create-chain transaction is seen by a validator, a whole new process to create a chain will be started by the `Manager`. This can happen dynamically, long after the 3 chains in the Primary Network have been created and bootstrapped.


# Issuing API Calls (/docs/rpcs/other/guides/issuing-api-calls)

---
title: Issuing API Calls
description: This guide explains how to make calls to APIs exposed by Lux nodes.
---

Endpoints[​](#endpoints "Direct link to heading")
-------------------------------------------------

An API call is made to an endpoint, which is a URL, made up of the base URI which is the address and the port of the node, and the path the particular endpoint the API call is on.

### Base URL[​](#base-url "Direct link to heading")

The base of the URL is always:

`[node-ip]:[http-port]`

where

- `node-ip` is the IP address of the node the call is to.
- `http-port` is the port the node listens on for HTTP calls. This is specified by [command-line argument](/docs/nodes/configure/configs-flags#http-server) `http-port` (default value `9650`).

For example, if you're making RPC calls on the local node, the base URL might look like this: `127.0.0.1:9650`.

If you're making RPC calls to remote nodes, then the instead of `127.0.0.1` you should use the public IP of the server where the node is. Note that by default the node will only accept API calls on the local interface, so you will need to set up the [`http-host`](/docs/nodes/configure/configs-flags#--http-host-string) config flag on the node. Also, you will need to make sure the firewall and/or security policy allows access to the `http-port` from the internet.


<Callout type="warn">
When setting up RPC access to a node, make sure you don't leave the `http-port` accessible to everyone! There are malicious actors that scan for nodes that have unrestricted access to their RPC port and then use those nodes for spamming them with resource-intensive queries which can knock the node offline. Only allow access to your node's RPC port from known IP addresses!
</Callout>
### Endpoint Path[​](#endpoint-path "Direct link to heading")

Each API's documentation specifies what endpoint path a user should make calls to in order to access the API's methods.

In general, they are formatted like:

So for the Admin API, the endpoint path is `/ext/admin`, for the Info API it is `/ext/info` and so on. Note that some APIs have additional path components, most notably the chain RPC endpoints which includes the Lux L1 chain RPCs. We'll go over those in detail in the next section.

So, in combining the base URL and the endpoint path we get the complete URL for making RPC calls. For example, to make a local RPC call on the Info API, the full URL would be:

```
http://127.0.0.1:9650/ext/info
```

Primary Network and Lux L1 RPC calls[​](#primary-network-and-lux-l1-rpc-calls "Direct link to heading")
-------------------------------------------------------------------------------------------------------

Besides the APIs that are local to the node, like Admin or Metrics APIs, nodes also expose endpoints for talking to particular chains that are either part of the Primary Network (the X, P and C chains), or part of any Lux L1s the node might be syncing or validating.

In general, chain endpoints are formatted as:

### Primary Network Endpoints[​](#primary-network-endpoints "Direct link to heading")

The Primary Network consists of three chains: X, P and C chain. As those chains are present on every node, there are also convenient aliases defined that can be used instead of the full blockchainIDs. So, the endpoints look like:

### LUExchange-Chain and Subnet-EVM Endpoints[​](#c-chain-and-subnet-evm-endpoints "Direct link to heading")

LUExchange-Chain and many Lux L1s run a version of the EthereumVM (EVM). EVM exposes its own endpoints, which are also accessible on the node: JSON-RPC, and Websocket.

#### JSON-RPC EVM Endpoints[​](#json-rpc-evm-endpoints "Direct link to heading")

To interact with LUExchange-Chain EVM via the JSON-RPC use the endpoint:

To interact with Lux L1 instances of the EVM via the JSON-RPC endpoint:

```
/ext/bc/[blockchainID]/rpc
```

where `blockchainID` is the ID of the blockchain running the EVM. So for example, the RPC URL for the DFK Network (an Lux L1 that runs the DeFi Kingdoms:Crystalvale game) running on a local node would be:

```
http://127.0.0.1/ext/bc/q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi/rpc
```

Or for the WAGMI Lux L1 on the Testnet testnet:

```
http://127.0.0.1/ext/bc/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/rpc
```

#### Websocket EVM Endpoints[​](#websocket-evm-endpoints "Direct link to heading")

To interact with LUExchange-Chain via the websocket endpoint, use:

To interact with other instances of the EVM via the websocket endpoint:

where `blockchainID` is the ID of the blockchain running the EVM. For example, to interact with the LUExchange-Chain's Ethereum APIs via websocket on localhost you can use:

```
ws://127.0.0.1:9650/ext/bc/C/ws
```


<Callout title="Note">
When using the [Public API](/docs/rpcs) or another host that supports HTTPS, use `https://` or `wss://` instead of `http://` or `ws://`.

Also, note that the [public API](/docs/rpcs#using-the-public-api-nodes) only supports LUExchange-Chain websocket API calls for API methods that don't exist on the LUExchange-Chain's HTTP API.
</Callout>


Making a JSON RPC Request[​](#making-a-json-rpc-request "Direct link to heading")
---------------------------------------------------------------------------------

Most of the built-in APIs use the [JSON RPC 2.0](https://www.jsonrpc.org/specification) format to describe their requests and responses. Such APIs include the Platform API and the Exchange-Chain API.

Suppose we want to call the `getTxStatus` method of the [Exchange-Chain API](/docs/rpcs/x-chain). The Exchange-Chain API documentation tells us that the endpoint for this API is `/ext/bc/X`.

That means that the endpoint we send our API call to is:

`[node-ip]:[http-port]/ext/bc/X`

The Exchange-Chain API documentation tells us that the signature of `getTxStatus` is:

[`xvm.getTxStatus`](/docs/rpcs/x-chain#avmgettxstatus)`(txID:bytes) -> (status:string)`

where:

- Argument `txID` is the ID of the transaction we're getting the status of.
- Returned value `status` is the status of the transaction in question.

To call this method, then:

```
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :4,
    "method" :"xvm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

- `jsonrpc` specifies the version of the JSON RPC protocol. (In practice is always 2.0)
- `method` specifies the service (`xvm`) and method (`getTxStatus`) that we want to invoke.
- `params` specifies the arguments to the method.
- `id` is the ID of this request. Request IDs should be unique.

That's it!

### JSON RPC Success Response[​](#json-rpc-success-response "Direct link to heading")

If the call is successful, the response will look like this:

```
{
  "jsonrpc": "2.0",
  "result": {
    "Status": "Accepted"
  },
  "id": 1
}
```

- `id` is the ID of the request that this response corresponds to.
- `result` is the returned values of `getTxStatus`.

### JSON RPC Error Response[​](#json-rpc-error-response "Direct link to heading")

If the API method invoked returns an error then the response will have a field `error` in place of `result`. Additionally, there is an extra field, `data`, which holds additional information about the error that occurred.

Such a response would look like:

```
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "[Some error message here]",
        "data": [Object with additional information about the error]
    },
    "id": 1
}
```

Other API Formats[​](#other-api-formats "Direct link to heading")
-----------------------------------------------------------------

Some APIs may use a standard other than JSON RPC 2.0 to format their requests and responses. Such extension should specify how to make calls and parse responses to them in their documentation.

Sending and Receiving Bytes[​](#sending-and-receiving-bytes "Direct link to heading")
-------------------------------------------------------------------------------------

Unless otherwise noted, when bytes are sent in an API call/response, they are in hex representation. However, Transaction IDs (TXIDs), ChainIDs, and subnetIDs are in [CB58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) representation, a base-58 encoding with a checksum.


# Transaction Fees (/docs/rpcs/other/guides/txn-fees)

---
title: Transaction Fees
---

In order to prevent spam, transactions on Lux require the payment of a transaction fee. The fee is paid in LUX. **The transaction fee is burned (destroyed forever).**

When you issue a transaction through Lux's API, the transaction fee is automatically deducted from one of the addresses you control. 

The [luxgo wallet](https://github.com/luxfi/luxgo/blob/master/wallet/chain) contains example code written in golang for building and signing transactions on all three mainnet chains. 

Exchange-Chain Fees[​](#fee-schedule)
-------------------------------------------------------

The Exchange-Chain currently operates under a fixed fee mechanism. This table shows the Exchange-Chain transaction fee schedule:

```
+----------+---------------------------+--------------------------------+
| Chain    | Transaction Type          | Mainnet Transaction Fee (LUX) |
+----------+---------------------------+--------------------------------+
| X        | Send                      |                          0.001 |
+----------+---------------------------+--------------------------------+
| X        | Create Asset              |                           0.01 |
+----------+---------------------------+--------------------------------+
| X        | Mint Asset                |                          0.001 |
+----------+---------------------------+--------------------------------+
| X        | Import LUX               |                          0.001 |
+----------+---------------------------+--------------------------------+
| X        | Export LUX               |                          0.001 |
+----------+---------------------------+--------------------------------+
```

LUExchange-Chain Fees[​](#c-chain-fees)
-------------------------------------------------------

The Lux LUExchange-Chain uses an algorithm to determine the "base fee" for a transaction. The base fee increases when network utilization is above the target utilization and decreases when network utilization is below the target.

### Dynamic Fee Transactions[​](#dynamic-fee-transactions )

Transaction fees for non-atomic transactions are based on Ethereum's EIP-1559 style Dynamic Fee Transactions, which consists of a gas fee cap and a gas tip cap.

The fee cap specifies the maximum price the transaction is willing to pay per unit of gas. The tip cap (also called the priority fee) specifies the maximum amount above the base fee that the transaction is willing to pay per unit of gas. Therefore, the effective gas price paid by a transaction will be `min(gasFeeCap, baseFee + gasTipCap)`. Unlike in Ethereum, where the priority fee is paid to the miner that produces the block, in Lux both the base fee and the priority fee are burned. For legacy transactions, which only specify a single gas price, the gas price serves as both the gas fee cap and the gas tip cap.

Use the [`eth_baseFee`](/docs/rpcs/c-chain#eth_basefee) API method to estimate the base fee for the next block. If more blocks are produced in between the time that you construct your transaction and it is included in a block, the base fee could be different from the base fee estimated by the API call, so it is important to treat this value as an estimate.

Next, use [eth\_maxPriorityFeePerGas](/docs/rpcs/c-chain#eth_maxpriorityfeepergas) API call to estimate the priority fee needed to be included in a block. This API call will look at the most recent blocks and see what tips have been paid by recent transactions in order to be included in the block.

Transactions are ordered by the priority fee, then the timestamp (oldest first).

Based off of this information, you can specify the `gasFeeCap` and `gasTipCap` to your liking based on how you prioritize getting your transaction included as quickly as possible vs. minimizing the price paid per unit of gas.

#### Base Fee[​](#base-fee)

The base fee can go as low as 1 nLUX (Gwei) and has no upper bound. You can use the [`eth_baseFee`](/docs/rpcs/c-chain#eth_basefee) and [eth\_maxPriorityFeePerGas](/docs/rpcs/c-chain#eth_maxpriorityfeepergas) API methods, or [Snowtrace's LUExchange-Chain Gas Tracker](https://snowtrace.io/gastracker), to estimate the gas price to use in your transactions.

### Atomic Transaction Fees[​](#atomic-transaction-fees)

LUExchange-Chain atomic transactions (that is imports and exports from/to other chains) charge dynamic fees based on the amount of gas used by the transaction and the base fee of the block that includes the atomic transaction.

Gas Used:

```
+---------------------+-------+
| Item                : Gas   |
+---------------------+-------+
| Unsigned Tx Byte    : 1     |
+---------------------+-------+
| Signature           : 1000  |
+---------------------+-------+
| Per Atomic Tx       : 10000 |
+---------------------+-------+
```

Therefore, the gas used by an atomic transaction is `1 * len(unsignedTxBytes) + 1,000 * numSignatures + 10,000`

The TX fee additionally takes the base fee into account. Due to the fact that atomic transactions use units denominated in 9 decimal places, the base fee must be converted to 9 decimal places before calculating the actual fee paid by the transaction. Therefore, the actual fee is: `gasUsed * baseFee (converted to 9 decimals)`.


Platform-Chain Fees[​](#p-chain-fees)
-------------------------------------------------------

The Lux Platform-Chain utilizes a dynamic fee mechanism to optimize transaction costs and network utilization. This system adapts fees based on gas consumption to maintain a target utilization rate.

### Dimensions of Gas Consumption
Gas consumption is measured across four dimensions:

1. **Bandwidth** The transaction size in bytes.
2. **Reads** The number of state/database reads.
3. **Writes** The number of state/database writes.
4. **Compute** The compute time in microseconds.

The total gas consumed ($G$) by a transaction is:

```math
G = B + 1000R + 1000W + 4C
```

The current fee dimension weight configurations as well as the parameter configurations of the Platform-Chain can be read at any time with the [`platform.getFeeConfig`](/docs/rpcs/p-chain#platformgetfeeconfig) API endpoint. 

### Fee Adjustment Mechanism
Fees adjust dynamically based on excess gas consumption, the difference between current gas usage and the target gas rate. The exponential adjustment ensures consistent reactivity regardless of the current gas price. Fee changes scale proportionally with excess gas consumption, maintaining fairness and network stability. The technical specification of this mechanism is documented in [LP-103](/docs/lps/103-dynamic-fees#mechanism).



# Exchange-Chain Migration (/docs/rpcs/other/guides/x-chain-migration)

---
title: Exchange-Chain Migration
---
Overview[​](#overview "Direct link to heading")
-----------------------------------------------

This document summarizes all of the changes made to the Exchange-Chain API to support Lux Cortina (v1.10.0), which migrates the Exchange-Chain to run Snowman++. In summary, the core transaction submission and confirmation flow is unchanged, however, there are new APIs that must be called to index all transactions.

Transaction Broadcast and Confirmation[​](#transaction-broadcast-and-confirmation "Direct link to heading")
-----------------------------------------------------------------------------------------------------------

The transaction format on the Exchange-Chain does not change in Cortina. This means that wallets that have already integrated with the Exchange-Chain don't need to change how they sign transactions. Additionally, there is no change to the format of the [xvm.issueTx](/docs/rpcs/x-chain#avmissuetx) or the [xvm.getTx](/docs/rpcs/x-chain#avmgettx) API.

However, the [xvm.getTxStatus](/docs/rpcs/x-chain#avmgettxstatus) endpoint is now deprecated and its usage should be replaced with [xvm.getTx](/docs/rpcs/x-chain#avmgettx) (which only returns accepted transactions for LuxGo >= v1.9.12). [xvm.getTxStatus](/docs/rpcs/x-chain#avmgettxstatus) will still work up to and after the Cortina activation if you wish to migrate after the network upgrade has occurred.

Vertex -> Block Indexing[​](#vertex---block-indexing "Direct link to heading")
------------------------------------------------------------------------------

Before Cortina, indexing the Exchange-Chain required polling the `/ext/index/X/vtx` endpoint to fetch new vertices. During the Cortina activation, a “stop vertex” will be produced using a [new codec version](https://github.com/luxfi/luxgo/blob/c27721a8da1397b218ce9e9ec69839b8a30f9860/snow/engine/lux/vertex/codec.go#L17-L18) that will contain no transactions. This new vertex type will be the [same format](https://github.com/luxfi/luxgo/blob/c27721a8da1397b218ce9e9ec69839b8a30f9860/snow/engine/lux/vertex/stateless_vertex.go#L95-L102) as previous vertices. To ensure historical data can still be accessed in Cortina, the `/ext/index/X/vtx` will remain accessible even though it will no longer be populated with chain data.


<Callout title="Note">
The index for the X-chain tx and vtx endpoints will never increase again. The index for the X-chain blocks will increase as new blocks are added.
</Callout>

After Cortina activation, you will need to migrate to using the new _ext/index/X/block_ endpoint (shares the same semantics as [/ext/index/P/block](/docs/rpcs/other/index-rpc#p-chain-blocks)) to continue indexing Exchange-Chain activity. Because Exchange-Chain ordering is deterministic in Cortina, this means that Exchange-Chain blocks across all heights will be consistent across all nodes and will include a timestamp. Here is an example of iterating over these blocks in Golang:

```
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/luxfi/luxgo/indexer"
	"github.com/luxfi/luxgo/vms/proposervm/block"
	"github.com/luxfi/luxgo/wallet/chain/x"
	"github.com/luxfi/luxgo/wallet/subnet/primary"
)

func main() {
	var (
		uri       = fmt.Sprintf("%s/ext/index/X/block", primary.LocalAPIURI)
		client    = indexer.NewClient(uri)
		ctx       = context.Background()
		nextIndex uint64
	)
	for {
		log.Printf("polling for next accepted block")
		container, err := client.GetContainerByIndex(ctx, nextIndex)
		if err != nil {
			time.Sleep(time.Second)
			continue
		}

		proposerVMBlock, err := block.Parse(container.Bytes)
		if err != nil {
			log.Fatalf("failed to parse proposervm block: %s\n", err)
		}

		avmBlockBytes := proposerVMBlock.Block()
		avmBlock, err := x.Parser.ParseBlock(avmBlockBytes)
		if err != nil {
			log.Fatalf("failed to parse xvm block: %s\n", err)
		}

		acceptedTxs := avmBlock.Txs()
		log.Printf("accepted block %s with %d transactions", avmBlock.ID(), len(acceptedTxs))

		for _, tx := range acceptedTxs {
			log.Printf("accepted transaction %s", tx.ID())
		}

		nextIndex++
	}
}
```

After Cortina activation, it will also be possible to fetch Exchange-Chain blocks directly without enabling the Index API. You can use the [xvm.getBlock](/docs/rpcs/x-chain#avmgetblock), [xvm.getBlockByHeight](/docs/rpcs/x-chain#avmgetblockbyheight), and [xvm.getHeight](/docs/rpcs/x-chain#avmgetheight) endpoints to do so. This, again, will be similar to the [Platform-Chain semantics](/docs/rpcs/p-chain#platformgetblock).

Deprecated API Calls[​](#deprecated-api-calls "Direct link to heading")
-----------------------------------------------------------------------

This long-term deprecation effort will better align usage of LuxGo with its purpose, to be a minimal and efficient runtime that supports only what is required to validate the Primary Network and Lux L1s. Integrators should make plans to migrate to tools and services that are better optimized for serving queries over Lux Network state and avoid keeping any keys on the node itself.


<Callout title="Note">
This deprecation ONLY applies to APIs that LuxGo exposes over the HTTP port. Transaction types with similar names to these APIs are NOT being deprecated.
</Callout>
- ipcs
    - ipcs.publishBlockchain
    - ipcs.unpublishBlockchain
    - ipcs.getPublishedBlockchains
- keystore
    - keystore.createUser
    - keystore.deleteUser
    - keystore.listUsers
    - keystore.importUser
    - keystore.exportUser
- xvm/pubsub
- xvm
    - xvm.getAddressTxs
    - xvm.getBalance
    - xvm.getAllBalances
    - xvm.createAsset
    - xvm.createFixedCapAsset
    - xvm.createVariableCapAsset
    - xvm.createNFTAsset
    - xvm.createAddress
    - xvm.listAddresses
    - xvm.exportKey
    - xvm.importKey
    - xvm.mint
    - xvm.sendNFT
    - xvm.mintNFT
    - xvm.import
    - xvm.export
    - xvm.send
    - xvm.sendMultiple
- xvm/wallet
    - wallet.issueTx
    - wallet.send
    - wallet.sendMultiple
- platform
    - platform.exportKey
    - platform.importKey
    - platform.getBalance
    - platform.createAddress
    - platform.listAddresses
    - platform.getSubnets
    - platform.addValidator
    - platform.addDelegator
    - platform.addSubnetValidator
    - platform.createSubnet
    - platform.exportLUX
    - platform.importLUX
    - platform.createBlockchain
    - platform.getBlockchains
    - platform.getStake
    - platform.getMaxStakeAmount
    - platform.getRewardUTXOs

Cortina FAQ[​](#cortina-faq "Direct link to heading")
-----------------------------------------------------

### Do I Have to Upgrade my Node?[​](#do-i-have-to-upgrade-my-node "Direct link to heading")

If you don't upgrade your validator to `v1.10.0` before the Lux Mainnet activation date, your node will be marked as offline and other nodes will report your node as having lower uptime, which may jeopardize your staking rewards.

### Is There any Change in Hardware Requirements?[​](#is-there-any-change-in-hardware-requirements "Direct link to heading")

No.

### Will Updating Decrease my Validator's Uptime?[​](#will-updating-decrease-my-validators-uptime "Direct link to heading")

No. As a reminder, you can check your validator's estimated uptime using the [`info.uptime` API call](/docs/rpcs/other/info-rpc#infouptime).

### I Think Something Is Wrong. What Should I Do?[​](#i-think-something-is-wrong-what-should-i-do "Direct link to heading")

First, make sure that you've read the documentation thoroughly and checked the [FAQs](https://support.lux.network/en/). If you don't see an answer to your question, go to our [Discord](https://discord.com/invite/RwXY7P6) server and search for your question. If it has not already been asked, please post it in the appropriate channel.


# Lux Network Protocol (/docs/rpcs/other/standards/avalanche-network-protocol)

---
title: Lux Network Protocol 
---

Overview[​](#overview "Direct link to heading")
-----------------------------------------------

Lux network defines the core communication format between Lux nodes. It uses the [primitive serialization](/docs/rpcs/other/standards/serialization-primitives) format for payload packing.

`"Containers"` are mentioned extensively in the description. A Container is simply a generic term for blocks.

This document describes the protocol for peer-to-peer communication using Protocol Buffers (proto3). The protocol defines a set of messages exchanged between peers in a peer-to-peer network. Each message is represented by the `Message` proto message, which can encapsulate various types of messages, including network messages, state-sync messages, bootstrapping messages, consensus messages, and application messages.

Message[​](#message "Direct link to heading")
---------------------------------------------

The `Message` proto message is the main container for all peer-to-peer communication. It uses the `oneof` construct to represent different message types. The supported compression algorithms include Gzip and Zstd.

```
message Message {
  oneof message {
    bytes compressed_gzip = 1;
    bytes compressed_zstd = 2;
    // ... (other compression algorithms can be added)
    Ping ping = 11;
    Pong pong = 12;
    Version version = 13;
    PeerList peer_list = 14;
    // ... (other message types)
  }
}
```

### Compression[​](#compression "Direct link to heading")

The `compressed_gzip` and `compressed_zstd` fields are used for Gzip and Zstd compression, respectively, of the encapsulated message. These fields are set only if the message type supports compression.

Network Messages[​](#network-messages "Direct link to heading")
---------------------------------------------------------------

### Ping[​](#ping "Direct link to heading")

The `Ping` message reports a peer's perceived uptime percentage.

```
message Ping {
  uint32 uptime = 1;
  repeated SubnetUptime subnet_uptimes = 2;
}
```

- `uptime`: Uptime percentage on the primary network \[0, 100\].
- `subnet_uptimes`: Uptime percentages on Lux L1s.

### Pong[​](#pong "Direct link to heading")

The `Pong` message is sent in response to a `Ping` with the perceived uptime of the peer.

```
message Pong {
  uint32 uptime = 1; // Deprecated: uptime is now sent in Ping
  repeated SubnetUptime subnet_uptimes = 2; // Deprecated: uptime is now sent in Ping
}
```

### Version[​](#version "Direct link to heading")

The `Version` message is the first outbound message sent to a peer during the p2p handshake.

```
message Version {
  uint32 network_id = 1;
  uint64 my_time = 2;
  bytes ip_addr = 3;
  uint32 ip_port = 4;
  string my_version = 5;
  uint64 my_version_time = 6;
  bytes sig = 7;
  repeated bytes tracked_subnets = 8;
}
```

- `network_id`: Network identifier (e.g., local, testnet, Mainnet).
- `my_time`: Unix timestamp when the `Version` message was created.
- `ip_addr`: IP address of the peer.
- `ip_port`: IP port of the peer.
- `my_version`: Lux client version.
- `my_version_time`: Timestamp of the IP.
- `sig`: Signature of the peer IP port pair at a provided timestamp.
- `tracked_subnets`: Lux L1s the peer is tracking.

### PeerList[​](#peerlist "Direct link to heading")

The `PeerList` message contains network-level metadata for a set of validators.

```
message PeerList {
  repeated ClaimedIpPort claimed_ip_ports = 1;
}
```

- `claimed_ip_ports`: List of claimed IP and port pairs.

### PeerListAck[​](#peerlistack "Direct link to heading")

The `PeerListAck` message is sent in response to `PeerList` to acknowledge the subset of peers that the peer will attempt to connect to.

```
message PeerListAck {
  reserved 1; // deprecated; used to be tx_ids
  repeated PeerAck peer_acks = 2;
}
```

- `peer_acks`: List of acknowledged peers.

State-Sync Messages[​](#state-sync-messages "Direct link to heading")
---------------------------------------------------------------------

### GetStateSummaryFrontier[​](#getstatesummaryfrontier "Direct link to heading")

The `GetStateSummaryFrontier` message requests a peer's most recently accepted state summary.

```
message GetStateSummaryFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.

### StateSummaryFrontier[​](#statesummaryfrontier "Direct link to heading")

The `StateSummaryFrontier` message is sent in response to a `GetStateSummaryFrontier` request.

```
message StateSummaryFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes summary = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetStateSummaryFrontier` request.
- `summary`: The requested state summary.

### GetAcceptedStateSummary[​](#getacceptedstatesummary "Direct link to heading")

The `GetAcceptedStateSummary` message requests a set of state summaries at specified block heights.

```
message GetAcceptedStateSummary {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  repeated uint64 heights = 4;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `heights`: Heights being requested.

### AcceptedStateSummary[​](#acceptedstatesummary "Direct link to heading")

The `AcceptedStateSummary` message is sent in response to `GetAcceptedStateSummary`.

```
message AcceptedStateSummary {
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes summary_ids = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAcceptedStateSummary` request.
- `summary_ids`: State summary IDs.

Bootstrapping Messages[​](#bootstrapping-messages "Direct link to heading")
---------------------------------------------------------------------------

### GetAcceptedFrontier[​](#getacceptedfrontier "Direct link to heading")

The `GetAcceptedFrontier` message requests the accepted frontier from a peer.

```
message GetAcceptedFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  EngineType engine_type = 4;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `engine_type`: Consensus type the remote peer should use to handle this message.

### AcceptedFrontier[​](#acceptedfrontier "Direct link to heading")

The `AcceptedFrontier` message contains the remote peer's last accepted frontier.

```
message AcceptedFrontier {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes container_id = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAcceptedFrontier` request.
- `container_id`: The ID of the last accepted frontier.

### GetAccepted[​](#getaccepted "Direct link to heading")

The `GetAccepted` message sends a request with the sender's accepted frontier to a remote peer.

```
message GetAccepted {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  repeated bytes container_ids = 4;
  EngineType engine_type = 5;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this message.
- `deadline`: Timeout (ns) for this request.
- `container_ids`: The

sender's accepted frontier.

- `engine_type`: Consensus type to handle this message.

### Accepted[​](#accepted "Direct link to heading")

The `Accepted` message is sent in response to `GetAccepted`.

```
message Accepted {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes container_ids = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAccepted` request.
- `container_ids`: Subset of container IDs from the `GetAccepted` request that the sender has accepted.

### GetAncestors[​](#getancestors "Direct link to heading")

The `GetAncestors` message requests the ancestors for a given container.

```
message GetAncestors {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container_id`: Container for which ancestors are being requested.
- `engine_type`: Consensus type to handle this message.

### Ancestors[​](#ancestors "Direct link to heading")

The `Ancestors` message is sent in response to `GetAncestors`.

```
message Ancestors {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes containers = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAncestors` request.
- `containers`: Ancestry for the requested container.

Consensus Messages[​](#consensus-messages "Direct link to heading")
-------------------------------------------------------------------

### Get[​](#get "Direct link to heading")

The `Get` message requests a container from a remote peer.

```
message Get {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container_id`: Container being requested.
- `engine_type`: Consensus type to handle this message.

### Put[​](#put "Direct link to heading")

The `Put` message is sent in response to `Get` with the requested block.

```
message Put {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes container = 3;
  EngineType engine_type = 4;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `Get` request.
- `container`: Requested container.
- `engine_type`: Consensus type to handle this message.

### PushQuery[​](#pushquery "Direct link to heading")

The `PushQuery` message requests the preferences of a remote peer given a container.

```
message PushQuery {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container = 4;
  EngineType engine_type = 5;
  uint64 requested_height = 6;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container`: Container being gossiped.
- `engine_type`: Consensus type to handle this message.
- `requested_height`: Requesting peer's last accepted height.

### PullQuery[​](#pullquery "Direct link to heading")

The `PullQuery` message requests the preferences of a remote peer given a container id.

```
message PullQuery {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
  uint64 requested_height = 6;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container_id`: Container id being gossiped.
- `engine_type`: Consensus type to handle this message.
- `requested_height`: Requesting peer's last accepted height.

### Chits[​](#chits "Direct link to heading")

The `Chits` message contains the preferences of a peer in response to a `PushQuery` or `PullQuery` message.

```
message Chits {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes preferred_id = 3;
  bytes accepted_id = 4;
  bytes preferred_id_at_height = 5;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `PushQuery`/`PullQuery` request.
- `preferred_id`: Currently preferred block.
- `accepted_id`: Last accepted block.
- `preferred_id_at_height`: Currently preferred block at the requested height.

Application Messages[​](#application-messages "Direct link to heading")
-----------------------------------------------------------------------

### AppRequest[​](#apprequest "Direct link to heading")

The `AppRequest` message is a VM-defined request.

```
message AppRequest {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes app_bytes = 4;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `app_bytes`: Request body.

### AppResponse[​](#appresponse "Direct link to heading")

The `AppResponse` message is a VM-defined response sent in response to `AppRequest`.

```
message AppResponse {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes app_bytes = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `AppRequest`.
- `app_bytes`: Response body.

### AppGossip[​](#appgossip "Direct link to heading")

The `AppGossip` message is a VM-defined message.

```
message AppGossip {
  bytes chain_id = 1;
  bytes app_bytes = 2;
}
```

- `chain_id`: Chain the message is for.
- `app_bytes`: Message body.


# Cryptographic Primitives (/docs/rpcs/other/standards/cryptographic-primitives)

---
title: Cryptographic Primitives
---

Lux uses a variety of cryptographic primitives for its different functions. This file summarizes the type and kind of cryptography used at the network and blockchain layers.

## Cryptography in the Network Layer

Lux uses Transport Layer Security, TLS, to protect node-to-node communications from eavesdroppers. TLS combines the practicality of public-key cryptography with the efficiency of symmetric-key cryptography. This has resulted in TLS becoming the standard for internet communication. Whereas most classical consensus protocols employ public-key cryptography to prove receipt of messages to third parties, the novel Snow\* consensus family does not require such proofs. This enables Lux to employ TLS in authenticating stakers and eliminates the need for costly public-key cryptography for signing network messages.

### TLS Certificates

Lux does not rely on any centralized third-parties, and in particular, it does not use certificates issued by third-party authenticators. All certificates used within the network layer to identify endpoints are self-signed, thus creating a self-sovereign identity layer. No third parties are ever involved.

### TLS Addresses

To avoid posting the full TLS certificate to the Platform-Chain, the certificate is first hashed. For consistency, Lux employs the same hashing mechanism for the TLS certificates as is used in Bitcoin. Namely, the DER representation of the certificate is hashed with sha256, and the result is then hashed with ripemd160 to yield a 20-byte identifier for stakers.

This 20-byte identifier is represented by "NodeID-" followed by the data's [CB58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) encoded string.

## Cryptography in the Lux Virtual Machine

The Lux virtual machine uses elliptic curve cryptography, specifically `secp256k1`, for its signatures on the blockchain.

This 32-byte identifier is represented by "PrivateKey-" followed by the data's [CB58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) encoded string.

### Secp256k1 Addresses

Lux is not prescriptive about addressing schemes, choosing to instead leave addressing up to each blockchain.

The addressing scheme of the Exchange-Chain and the Platform-Chain relies on secp256k1. Lux follows a similar approach as Bitcoin and hashes the ECDSA public key. The 33-byte compressed representation of the public key is hashed with sha256 **once**. The result is then hashed with ripemd160 to yield a 20-byte address.

Lux uses the convention `chainID-address` to specify which chain an address exists on. `chainID` may be replaced with an alias of the chain. When transmitting information through external applications, the CB58 convention is required.

### Bech32

Addresses on the Exchange-Chain and Platform-Chain use the [Bech32](http://support.avalabs.org/en/articles/4587392-what-is-bech32) standard outlined in [BIP 0173](https://en.bitcoin.it/wiki/BIP_0173). There are four parts to a Bech32 address scheme. In order of appearance:

- A human-readable part (HRP). On Mainnet this is `lux`.
- The number `1`, which separates the HRP from the address and error correction code.
- A base-32 encoded string representing the 20 byte address.
- A 6-character base-32 encoded error correction code.

Additionally, an Lux address is prefixed with the alias of the chain it exists on, followed by a dash. For example, Exchange-Chain addresses are prefixed with `X-`.

The following regular expression matches addresses on the Exchange-Chain, Platform-Chain and LUExchange-Chain for Mainnet, Testnet and localhost. Note that all valid Lux addresses will match this regular expression, but some strings that are not valid Lux addresses may match this regular expression.

```
^([XPC]|[a-km-zA-HJ-NP-Z1-9]{36,72})-[a-zA-Z]{1,83}1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{38}$
```

Read more about Lux's [addressing scheme](https://support.avalabs.org/en/articles/4596397-what-is-an-address).

<Accordions>
<Accordion title="Bech32 and NetworkID Mapping">
For example the following Bech32 address, `X-lux19rknw8l0grnfunjrzwxlxync6zrlu33y2jxhrg`, is composed like so:

1.  HRP: `lux`
2.  Separator: `1`
3.  Address: `9rknw8l0grnfunjrzwxlxync6zrlu33y`
4.  Checksum: `2jxhrg`

Depending on the `networkID`, the encoded addresses will have a distinctive HRP per each network.

- 0 - X-`custom`19rknw8l0grnfunjrzwxlxync6zrlu33yeg5dya
- 1 - X-`lux`19rknw8l0grnfunjrzwxlxync6zrlu33y2jxhrg
- 2 - X-`cascade`19rknw8l0grnfunjrzwxlxync6zrlu33ypmtvnh
- 3 - X-`denali`19rknw8l0grnfunjrzwxlxync6zrlu33yhc357h
- 4 - X-`everest`19rknw8l0grnfunjrzwxlxync6zrlu33yn44wty
- 5 - X-`testnet`19rknw8l0grnfunjrzwxlxync6zrlu33yxqzg0h
- 1337 - X-`custom`19rknw8l0grnfunjrzwxlxync6zrlu33yeg5dya
- 12345 - X-`local`19rknw8l0grnfunjrzwxlxync6zrlu33ynpm3qq

Here's the mapping of `networkID` to bech32 HRP.

```
  0: "custom",
  1: "lux",
  2: "cascade",
  3: "denali",
  4: "everest",
  5: "testnet",
  1337: "custom",
  12345: "local"
```
</Accordion>
</Accordions>

### Secp256k1 Recoverable Signatures

Recoverable signatures are stored as the 65-byte **`[R || S || V]`** where **`V`** is 0 or 1 to allow quick public key recoverability. **`S`** must be in the lower half of the possible range to prevent signature malleability. Before signing a message, the message is hashed using sha256.

### Secp256k1 Example

Suppose Rick and Morty are setting up a secure communication channel. Morty creates a new public-private key pair.

Private Key: `0x98cb077f972feb0481f1d894f272c6a1e3c15e272a1658ff716444f465200070`

Public Key (33-byte compressed): `0x02b33c917f2f6103448d7feb42614037d05928433cb25e78f01a825aa829bb3c27`

Because of Rick's infinite wisdom, he doesn't trust himself with carrying around Morty's public key, so he only asks for Morty's address. Morty follows the instructions, SHA256's his public key, and then ripemd160's that result to produce an address.

SHA256(Public Key): `0x28d7670d71667e93ff586f664937f52828e6290068fa2a37782045bffa7b0d2f`

Address: `0xe8777f38c88ca153a6fdc25942176d2bf5491b89`

Morty is quite confused because a public key should be safe to be public knowledge. Rick belches and explains that hashing the public key protects the private key owner from potential future security flaws in elliptic curve cryptography. In the event cryptography is broken and a private key can be derived from a public key, users can transfer their funds to an address that has never signed a transaction before, preventing their funds from being compromised by an attacker. This enables coin owners to be protected while the cryptography is upgraded across the clients.

Later, once Morty has learned more about Rick's backstory, Morty attempts to send Rick a message. Morty knows that Rick will only read the message if he can verify it was from him, so he signs the message with his private key.

Message: `0x68656c702049276d207472617070656420696e206120636f6d7075746572`

Message Hash: `0x912800c29d554fb9cdce579c0abba991165bbbc8bfec9622481d01e0b3e4b7da`

Message Signature: `0xb52aa0535c5c48268d843bd65395623d2462016325a86f09420c81f142578e121d11bd368b88ca6de4179a007e6abe0e8d0be1a6a4485def8f9e02957d3d72da01`

Morty was never seen again.

### Signed Messages

A standard for interoperable generic signed messages based on the Bitcoin Script format and Ethereum format.

```
sign(sha256(length(prefix) + prefix + length(message) + message))
```

The prefix is simply the string `\x1ALux Signed Message:\n`, where `0x1A` is the length of the prefix text and `length(message)` is an [integer](/docs/rpcs/other/standards/serialization-primitives#integer) of the message size.

### Gantt Pre-Image Specification

```
+---------------+-----------+------------------------------+
| prefix        : [26]byte  |                     26 bytes |
+---------------+-----------+------------------------------+
| messageLength : int       |                      4 bytes |
+---------------+-----------+------------------------------+
| message       : []byte    |          size(message) bytes |
+---------------+-----------+------------------------------+
                            |       26 + 4 + size(message) |
                            +------------------------------+
```

### Example

As an example we will sign the message "Through consensus to the stars"

```
// prefix size: 26 bytes
0x1a
// prefix: Lux Signed Message:\n
0x41 0x76 0x61 0x6c 0x61 0x6e 0x63 0x68 0x65 0x20 0x53 0x69 0x67 0x6e 0x65 0x64 0x20 0x4d 0x65 0x73 0x73 0x61 0x67 0x65 0x3a 0x0a
// msg size: 30 bytes
0x00 0x00 0x00 0x1e
// msg: Through consensus to the stars
54 68 72 6f 75 67 68 20 63 6f 6e 73 65 6e 73 75 73 20 74 6f 20 74 68 65 20 73 74 61 72 73
```

After hashing with `sha256` and signing the pre-image we return the value [cb58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) encoded: `4Eb2zAHF4JjZFJmp4usSokTGqq9mEGwVMY2WZzzCmu657SNFZhndsiS8TvL32n3bexd8emUwiXs8XqKjhqzvoRFvghnvSN`. Here's an example using [Core web](https://core.app/tools/signing-tools/sign/).

<Callout title="Note">
A full guide on how to sign messages with Core web can be found [here](https://support.lux.network/en/articles/7206948-core-web-how-do-i-use-the-signing-tools).
</Callout>

![Sign message](/images/cryptography1.png)

## Cryptography in Ethereum Virtual Machine

Lux nodes support the full Ethereum Virtual Machine (EVM) and precisely duplicate all of the cryptographic constructs used in Ethereum. This includes the Keccak hash function and the other mechanisms used for cryptographic security in the EVM.

## Cryptography in Other Virtual Machines

Since Lux is an extensible platform, we expect that people will add additional cryptographic primitives to the system over time.


# Serialization Primitives (/docs/rpcs/other/standards/serialization-primitives)

---
title: Serialization Primitives
---

Lux uses a simple, uniform, and elegant representation for all internal data. This document describes how primitive types are encoded on the Lux platform. Transactions are encoded in terms of these basic primitive types.

Byte[​](#byte "Direct link to heading")
---------------------------------------

Bytes are packed as-is into the message payload.

Example:

```
Packing:
    0x01
Results in:
    [0x01]
```

Short[​](#short "Direct link to heading")
-----------------------------------------

Shorts are packed in BigEndian format into the message payload.

Example:

```
Packing:
    0x0102
Results in:
    [0x01, 0x02]
```

Integer[​](#integer "Direct link to heading")
---------------------------------------------

Integers are 32-bit values packed in BigEndian format into the message payload.

Example:

```
Packing:
    0x01020304
Results in:
    [0x01, 0x02, 0x03, 0x04]
```

Long Integers[​](#long-integers "Direct link to heading")
---------------------------------------------------------

Long integers are 64-bit values packed in BigEndian format into the message payload.

Example:

```
Packing:
    0x0102030405060708
Results in:
    [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]
```

IP Addresses[​](#ip-addresses "Direct link to heading")
-------------------------------------------------------

IP addresses are represented as 16-byte IPv6 format, with the port appended into the message payload as a Short. IPv4 addresses are padded with 12 bytes of leading 0x00s.

IPv4 example:

```
Packing:
    "127.0.0.1:9650"
Results in:
    [
        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        0x00, 0x00, 0xff, 0xff, 0x7f, 0x00, 0x00, 0x01,
        0x25, 0xb2,
    ]
```

IPv6 example:

```
Packing:
    "[2001:0db8:ac10:fe01::]:12345"
Results in:
    [
        0x20, 0x01, 0x0d, 0xb8, 0xac, 0x10, 0xfe, 0x01,
        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        0x30, 0x39,
    ]
```

Fixed-Length Array[​](#fixed-length-array "Direct link to heading")
-------------------------------------------------------------------

Fixed-length arrays, whose length is known ahead of time and by context, are packed in order.

Byte array example:

```
Packing:
    [0x01, 0x02]
Results in:
    [0x01, 0x02]
```

Integer array example:

```
Packing:
    [0x03040506]
Results in:
    [0x03, 0x04, 0x05, 0x06]
```

Variable Length Array[​](#variable-length-array "Direct link to heading")
-------------------------------------------------------------------------

The length of the array is prefixed in Integer format, followed by the packing of the array contents in Fixed Length Array format.

Byte array example:

```
Packing:
    [0x01, 0x02]
Results in:
    [0x00, 0x00, 0x00, 0x02, 0x01, 0x02]
```

Int array example:

```
Packing:
    [0x03040506]
Results in:
    [0x00, 0x00, 0x00, 0x01, 0x03, 0x04, 0x05, 0x06]
```

String[​](#string "Direct link to heading")
-------------------------------------------

A String is packed similarly to a variable-length byte array. However, the length prefix is a short rather than an int. Strings are encoded in UTF-8 format.

Example:

```
Packing:
    "Lux"
Results in:
    [0x00, 0x04, 0x41, 0x76, 0x61, 0x78]

```



# Deploy Custom VM (/docs/tooling/avalanche-cli/create-avalanche-nodes/deploy-custom-vm)

---
title: Deploy Custom VM
description: This page demonstrates how to deploy a custom VM into cloud-based validators using Lux-CLI.
---

<Callout title="Note">
Currently, only Testnet network and Devnets are supported.
</Callout>

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to have:

- Created a cloud server node as described [here](/docs/tooling/lux-cli/create-lux-nodes/run-validators-aws)
- Created a Custom VM, as described [here](/docs/primary-network/virtual-machines).
- (Ignore for Devnet) Set up a key to be able to pay for transaction Fees, as described [here](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet).

Currently, only AWS & GCP cloud services are supported.

Deploying the VM[​](#deploying-the-vm "Direct link to heading")
---------------------------------------------------------------

We will be deploying the [MorpheusVM](https://github.com/luxfi/hypersdk/tree/main/examples/morpheusvm) example built with the HyperSDK.

The following settings will be used:

- Repo url: `https://github.com/luxfi/hypersdk/`
- Branch Name: `vryx-poc`
- Build Script: `examples/morpheusvm/scripts/build.sh`

<Callout title="Note">
The CLI needs a public repo url in order to be able to download and install the custom VM on cloud.
</Callout>

### Genesis File[​](#genesis-file "Direct link to heading")

The following contents will serve as the chain genesis. They were generated using `morpheus-cli` as shown [here](https://github.com/luxfi/hypersdk/blob/main/examples/morpheusvm/scripts/run.sh).

Save it into a file with path `<genesisPath>` (for example `~/morpheusvm_genesis.json`):

```bash
{
  "stateBranchFactor":16,
  "minBlockGap":1000,
  "minUnitPrice":[1,1,1,1,1],
  "maxChunkUnits":[1800000,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],
  "epochDuration":60000,
  "validityWindow":59000,
  "partitions":8,
  "baseUnits":1,
  "baseWarpUnits":1024,
  "warpUnitsPerSigner":128,
  "outgoingWarpComputeUnits":1024,
  "storageKeyReadUnits":5,
  "storageValueReadUnits":2,
  "storageKeyAllocateUnits":20,
  "storageValueAllocateUnits":5,
  "storageKeyWriteUnits":10,
  "storageValueWriteUnits":3,
  "customAllocation": [
    {
      "address":"morpheus1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjk97rwu",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qryyvfut6td0l2vwn8jwae0pmmev7eqxs2vw0fxpd2c4lr37jj7wvrj4vc3",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qp52zjc3ul85309xn9stldfpwkseuth5ytdluyl7c5mvsv7a4fc76g6c4w4",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qzqjp943t0tudpw06jnvakdc0y8w790tzk7suc92aehjw0epvj93s0uzasn",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qz97wx3vl3upjuquvkulp56nk20l3jumm3y4yva7v6nlz5rf8ukty8fh27r",
      "balance":3000000000000000000
    }
  ]
}
```

Create the Lux L1[​](#create-the-lux-l1 "Direct link to heading")
-----------------------------------------------------------------

Let's create an Lux L1 called `<blockchainName>`, with custom VM binary and genesis.

```bash
lux blockchain create <blockchainName>
```

Choose custom

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
    Subnet-EVM
  ▸ Custom
```

Provide path to genesis:

```bash
✗ Enter path to custom genesis: <genesisPath>
```

Provide the source code repo url:

```bash
✗ Source code repository URL: https://github.com/luxfi/hypersdk/
```

Set the branch and finally set the build script:

```bash
✗ Build script: examples/morpheusvm/scripts/build.sh
```

CLI will generate a locally compiled binary, and then create the Lux L1.

```bash
Cloning into ...

Successfully created subnet configuration
```

## Deploy Lux L1

For this example, we will deploy the Lux L1 and blockchain on Testnet. Run:

```bash
lux blockchain deploy <blockchainName>
```

Choose Testnet:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
    Local Network
  ▸ Testnet
    Mainnet
```

Use the stored key:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which key source should be used to pay transaction fees?:
  ▸ Use stored key
    Use ledger
```

Choose `<keyName>` as the key to use to pay the fees:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which stored key should be used to pay transaction fees?:
  ▸ <keyName>
```

Use the same key as the control key for the Lux L1:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? How would you like to set your control keys?:
  ▸ Use fee-paying key
    Use all stored keys
    Custom list
```

The successfully creation of our Lux L1 and blockchain is confirmed by the following output:

```bash
Your Subnet's control keys: [P-testnet1dlwux652lkflgz79g3nsphjzvl6t35xhmunfk1]
Your subnet auth keys for chain creation: [P-testnet1dlwux652lkflgz79g3nsphjzvl6t35xhmunfk1]
Subnet has been created with ID: RU72cWmBmcXber6ZBPT7R5scFFuVSoFRudcS3vayf3L535ZE3
Now creating blockchain...
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | blockchainName                                     |
+--------------------+----------------------------------------------------+
| Subnet ID          | RU72cWmBmcXber6ZBPT7R5scFFuVSoFRudcS3vayf3L535ZE3  |
+--------------------+----------------------------------------------------+
| VM ID              | srEXiWaHq58RK6uZMmUNaMF2FzG7vPzREsiXsptAHk9gsZNvN  |
+--------------------+----------------------------------------------------+
| Blockchain ID      | 2aDgZRYcSBsNoLCsC8qQH6iw3kUSF5DbRHM4sGEqVKwMSfBDRf |
+--------------------+                                                    +
| Platform-Chain TXID       |                                                    |
+--------------------+----------------------------------------------------+
```

Set the Config Files[​](#set-the-config-files "Direct link to heading")
-----------------------------------------------------------------------

Lux-CLI supports uploading the full set of configuration files for a blockchain:

- Genesis File
- Blockchain Config
- Lux L1 Config
- Network Upgrades
- LuxGo Config

The following example uses all of them, but the user can decide to provide a subset of those.

### LuxGo Flags[​](#luxgo-flags "Direct link to heading")

Save the following content (as defined [here](https://github.com/luxfi/hypersdk/blob/vryx-poc/examples/morpheusvm/tests/e2e/e2e_test.go))
into a file with path `<avagoFlagsPath>` (for example `~/morpheusvm_avago.json`):

```json
{
  "log-level":"INFO",
  "log-display-level":"INFO",
  "proposervm-use-current-height":true,
  "throttler-inbound-validator-alloc-size":"10737418240",
  "throttler-inbound-at-large-alloc-size":"10737418240",
  "throttler-inbound-node-max-processing-msgs":"1000000",
  "throttler-inbound-node-max-at-large-bytes":"10737418240",
  "throttler-inbound-bandwidth-refill-rate":"1073741824",
  "throttler-inbound-bandwidth-max-burst-size":"1073741824",
  "throttler-inbound-cpu-validator-alloc":"100000",
  "throttler-inbound-cpu-max-non-validator-usage":"100000",
  "throttler-inbound-cpu-max-non-validator-node-usage":"100000",
  "throttler-inbound-disk-validator-alloc":"10737418240000",
  "throttler-outbound-validator-alloc-size":"10737418240",
  "throttler-outbound-at-large-alloc-size":"10737418240",
  "throttler-outbound-node-max-at-large-bytes":"10737418240",
  "consensus-on-accept-gossip-validator-size":"10",
  "consensus-on-accept-gossip-peer-size":"10",
  "network-compression-type":"zstd",
  "consensus-app-concurrency":"128",
  "profile-continuous-enabled":true,
  "profile-continuous-freq":"1m",
  "http-host":"",
  "http-allowed-origins": "*",
  "http-allowed-hosts": "*"
}
```

Then set the Lux L1 to use it by executing:

```bash
lux blockchain configure blockchainName
```

Select node-config.json:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which configuration file would you like to provide?:
  ▸ node-config.json
    chain.json
    subnet.json
    per-node-chain.json
```

Provide the path to the LuxGo config file:

```bash
✗ Enter the path to your configuration file: <avagoFlagsPath>
```

Finally, choose no:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Would you like to provide the chain.json file as well?:
  ▸ No
    Yes
File ~/.lux-cli/subnets/blockchainName/node-config.json successfully written
```

### Blockchain Config[​](#blockchain-config "Direct link to heading")

`morpheus-cli` as shown [here](https://github.com/luxfi/hypersdk/blob/vryx-poc/examples/morpheusvm/scripts/run.sh).
Save the following content (generated by this [script](https://github.com/luxfi/hypersdk/blob/vryx-poc/examples/morpheusvm/scripts/run.sh))
in a known file path (for example `~/morpheusvm_chain.json`):

```json
{
  "chunkBuildFrequency": 250,
  "targetChunkBuildDuration": 250,
  "blockBuildFrequency": 100,
  "mempoolSize": 2147483648,
  "mempoolSponsorSize": 10000000,
  "authExecutionCores": 16,
  "precheckCores": 16,
  "actionExecutionCores": 8,
  "missingChunkFetchers": 48,
  "verifyAuth": true,
  "authRPCCores": 48,
  "authRPCBacklog": 10000000,
  "authGossipCores": 16,
  "authGossipBacklog": 10000000,
  "chunkStorageCores": 16,
  "chunkStorageBacklog": 10000000,
  "streamingBacklogSize": 10000000,
  "continuousProfilerDir":"/home/ubuntu/morpheusvm-profiles",
  "logLevel": "INFO"
}
```

Then set the Lux L1 to use it by executing:

```bash
lux blockchain configure blockchainName
```

Select chain.json:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which configuration file would you like to provide?:
    node-config.json
  ▸ chain.json
    subnet.json
    per-node-chain.json
```

Provide the path to the blockchain config file:

```bash
✗ Enter the path to your configuration file: ~/morpheusvm_chain.json
```

Finally choose no:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Would you like to provide the subnet.json file as well?:
  ▸ No
    Yes
File ~/.lux-cli/subnets/blockchainName/chain.json successfully written
```

### Lux L1 Config[​](#lux-l1-config "Direct link to heading")

Save the following content (generated by this [script](https://github.com/luxfi/hypersdk/blob/vryx-poc/examples/morpheusvm/scripts/run.sh))
in a known path (for example `~/morpheusvm_subnet.json`):

```json
{
  "proposerMinBlockDelay": 0,
  "proposerNumHistoricalBlocks": 512
}
```

Then set the Lux L1 to use it by executing:

```bash
lux blockchain configure blockchainName
```

Select `subnet.json`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which configuration file would you like to provide?:
    node-config.json
    chain.json
  ▸ subnet.json
    per-node-chain.json
```

Provide the path to the Lux L1 config file:

```bash
✗ Enter the path to your configuration file: ~/morpheusvm_subnet.json
```

Choose no:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Would you like to provide the chain.json file as well?:
  ▸ No
    Yes
File ~/.lux-cli/subnets/blockchainName/subnet.json successfully written
```

### Network Upgrades[​](#network-upgrades "Direct link to heading")

Save the following content (currently with no network upgrades) in a known path (for example `~/morpheusvm_upgrades.json`):

Then set the Lux L1 to use it by executing:

```bash
lux blockchain upgrade import blockchainName
```

Provide the path to the network upgrades file:

```bash
✗ Provide the path to the upgrade file to import: ~/morpheusvm_upgrades.json
```

Deploy Our Custom VM[​](#deploy-our-custom-vm "Direct link to heading")
-----------------------------------------------------------------------

To deploy our Custom VM, run:

```bash
lux node sync <clusterName> <blockchainName>
```

```bash
Node(s) successfully started syncing with Subnet!
```

Your custom VM is successfully deployed!

You can also use `lux node update blockchain <blockchainName>` to reinstall the binary when the branch is updated, or update the config files.

# Execute SSH Command (/docs/tooling/avalanche-cli/create-avalanche-nodes/execute-ssh-commands)

---
title: Execute SSH Command
description: This page demonstrates how to execute a SSH command on a Cluster or Node managed by Lux-CLI
---

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to have a cluster managed by CLI, either a [Testnet Cluster using AWS](/docs/tooling/lux-cli/create-lux-nodes/run-validators-aws), a [Testnet Cluster using GCP](/docs/tooling/lux-cli/create-lux-nodes/run-validators-gcp), or a [Devnet](/docs/tooling/lux-cli/create-lux-nodes/setup-devnet),

SSH Warning[​](#ssh-warning "Direct link to heading")
-----------------------------------------------------

Note: An expected warning may be seen when executing the command on a given cluster for the first time:

```bash
Warning: Permanently added 'IP' (ED25519) to the list of known hosts.
```

Get SSH Connection Instructions for All Clusters[​](#get-ssh-connection-instructions-for-all-clusters "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------------------

Just execute `node ssh`:

```bash
lux node ssh
Cluster "<clusterName>" (Devnet)
  [i-0cf58a280bf3ef9a1] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem 
  [i-0e2abd71a586e56b4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem 
  [i-027417a4f2ca0a478] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem 
  [i-0360a867aa295d8a4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem 
  [i-0759b102acfd5b585] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem 
```

Get the LuxGo PID for All Nodes in `<clusterName>`[​](#get-the-luxgo-pid-for-all-nodes-in-clustername "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------------------------------

```bash
lux node ssh <clusterName> pgrep luxgo
[i-0cf58a280bf3ef9a1] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem pgrep luxgo
14508

[i-0e2abd71a586e56b4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem pgrep luxgo
14555

[i-027417a4f2ca0a478] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem pgrep luxgo
14545

[i-0360a867aa295d8a4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem pgrep luxgo
14531

[i-0759b102acfd5b585] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem pgrep luxgo
14555
```

Please note that commands via `ssh` on cluster are executed sequentially by default. It's possible to run command on all nodes at the same time by using `--parallel=true` flag

Get the LuxGo Configuration for All Nodes in `<clusterName>`[​](#get-the-luxgo-configuration-for-all-nodes-in-clustername "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------------------------------------------

```bash
lux node ssh <clusterName> cat /home/ubuntu/.luxgo/configs/node.json
[i-0cf58a280bf3ef9a1] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem cat /home/ubuntu/.luxgo/configs/node.json
{
  "bootstrap-ids": "",
  "bootstrap-ips": "",
  "genesis-file": "/home/ubuntu/.luxgo/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "44.219.113.190",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-0e2abd71a586e56b4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem cat /home/ubuntu/.luxgo/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8",
  "bootstrap-ips": "44.219.113.190:9651",
  "genesis-file": "/home/ubuntu/.luxgo/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "3.212.206.161",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-027417a4f2ca0a478] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem cat /home/ubuntu/.luxgo/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8,NodeID-6veKG5dAz1uJvKc7qm7v6wAPDod8hctb9",
  "bootstrap-ips": "44.219.113.190:9651,3.212.206.161:9651",
  "genesis-file": "/home/ubuntu/.luxgo/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "54.87.168.26",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-0360a867aa295d8a4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem cat /home/ubuntu/.luxgo/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8,NodeID-6veKG5dAz1uJvKc7qm7v6wAPDod8hctb9,NodeID-ASseyUweBT82XquiGpmUFjd9QfkUjxiAY",
  "bootstrap-ips": "44.219.113.190:9651,3.212.206.161:9651,54.87.168.26:9651",
  "genesis-file": "/home/ubuntu/.luxgo/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "3.225.42.57",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-0759b102acfd5b585] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-lux-cli-us-east-1-kp.pem cat /home/ubuntu/.luxgo/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8,NodeID-6veKG5dAz1uJvKc7qm7v6wAPDod8hctb9,NodeID-ASseyUweBT82XquiGpmUFjd9QfkUjxiAY,NodeID-LfwbUp9dkhmWTSGffer9kNWNzqUQc2TEJ",
  "bootstrap-ips": "44.219.113.190:9651,3.212.206.161:9651,54.87.168.26:9651,3.225.42.57:9651",
  "genesis-file": "/home/ubuntu/.luxgo/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "107.21.158.224",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
```

Executing Command on a Single Node[​](#executing-command-on-a-single-node "Direct link to heading")
---------------------------------------------------------------------------------------------------

As we all know command can be executed on single node similar to the examples above To execute ssh command on a single node, use `<nodeID>`, `<IP>` or `<instanceID>` instead of `<clusterName>` as an argument. For example:

```bash
lux node ssh i-0225fc39626b1edd3 <command>
[or]
lux node ssh NodeID-9wdKQ3KJU3GqvgFTc4CUYvmefEFe8t6ka <command>
[or]
lux node ssh 54.159.59.123 <command>
```

In this case `--parallel=true` flag will be ignored

Opening SSH Shell for `<nodeID>`[​](#opening-ssh-shell-for-nodeid "Direct link to heading")
-------------------------------------------------------------------------------------------

If no command is provided, Lux-CLI will open an interactive session for the specified node. For example:

```bash
lux node ssh i-0225fc39626b1edd3
[or] 
lux node ssh NodeID-9wdKQ3KJU3GqvgFTc4CUYvmefEFe8t6ka
[or]
lux node ssh 54.159.59.123
```

Please use `exit` shell command or Ctrl+D to end this session.

# Run Load Test (/docs/tooling/avalanche-cli/create-avalanche-nodes/run-loadtest)

---
title: Run Load Test
description: This page demonstrates how to run load test on an Lux L1 deployed on a cluster of cloud-based validators using Lux-CLI.
---

## Prerequisites

Before we begin, you will need to have:

- Created an AWS account and have an updated AWS `credentials` file in home directory with [default] profile or set up your GCP account according to [here](/docs/tooling/lux-cli/create-lux-nodes/run-validators-gcp)
- Created a cluster of cloud servers with monitoring enabled
- Deployed an Lux L1 into the cluster
- Added the cloud servers as validator nodes in the Lux L1

## Run Load Test

When the load test command is run, a new cloud server will be created to run the load test. The  
created cloud server is referred by the name `<loadtestName>` and you can use any name of your 
choice.

To start load test, run:

```bash
lux node loadtest start <loadtestName> <clusterName> <blockchainName>
```

Next, you will need to provide the load test Git repository URL, load test Git Branch, the command 
to build the load test binary and the command to run the load test binary.

We will use an example of running load test on an Lux L1 running custom VM MorpheusVM built with 
[HyperSDK](https://github.com/luxfi/hypersdk/tree/main/examples/morpheusvm).

The following settings will be used:

- Load Test Repo URL: `https://github.com/luxfi/hypersdk/`
- Load Test Branch: `vryx-poc`
- Load Test Build Script: `cd /home/ubuntu/hypersdk/examples/morpheusvm; CGO_CFLAGS=\"-O -D__BLST_PORTABLE__\" go build -o ~/simulator ./cmd/morpheus-cli`
- Load Test Run Script: `/home/ubuntu/simulator spam run ed25519 --accounts=10000000 --txs-per-second=100000 --min-capacity=15000 --step-size=1000 --s-zipf=1.0001 --v-zipf=2.7 --conns-per-host=10 --cluster-info=/home/ubuntu/clusterInfo.yaml --private-key=323b1d8f4eed5f0da9da93071b034f2dce9d2d22692c172f3cb252a64ddfafd01b057de320297c29ad0c1f589ea216869cf1938d88c9fbd70d6748323dbf2fa7`

Once the command is run, you will be able to see the logs from the load test in the cluster's 
Grafana URL like the example below:

![Centralized Logs](/images/centralized-logs.png)

## Stop Load Test

To stop the load test process on the load test instance `<loadtestName>` and terminate the load test instance, run:

```bash
lux node loadtest stop <loadtestName>
```


# Run Validator on AWS (/docs/tooling/avalanche-cli/create-avalanche-nodes/run-validators-aws)

---
title: Run Validator on AWS
description: This page demonstrates how to deploy Lux validators on AWS using just one Lux-CLI command.
---

This page demonstrates how to deploy Lux validators on AWS using just one Lux-CLI command.

<Callout title="Note">
Currently, only Testnet network and Devnets are supported.
</Callout>

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to create an AWS account and have an AWS `credentials` file in home directory with \[default\] profile set. More info can be found [here](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds)

## Create Validators

To create Lux validators, run:

```bash
lux node create <clusterName>
```

The created nodes will be part of cluster `clusterName` and all lux node commands applied to cluster `clusterName` will apply to all nodes in the cluster.

<Callout title="Note">
Please note that running a validator on AWS will incur costs.

Lux Network is not responsible for the cost incurred from running an Lux validator on cloud services via Lux-CLI.
</Callout>

Currently, we have set the following specs of the AWS cloud server to a fixed value, but we plan to enable customization in the near future:

- OS Image: `Ubuntu 20.04 LTS (HVM), SSD Volume Type`
- Storage: `1 TB`

Instance type can be specified via `--node-type` parameter or via interactive menu. `c5.2xlarge` is the default(recommended) instance size.

The command will ask which region you want to set up your cloud server in:

```bash
 Which AWS region do you want to set up your node in?: 
  ▸ us-east-1
    us-east-2
    us-west-1
    us-west-2
    Choose custom region (list of regions available at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
```

The command will next ask whether you want to set up monitoring for your nodes.

```bash
  Do you want to set up a separate instance to host monitoring? (This enables you to monitor all your set up instances in one dashboard): 
  ▸ Yes
    No
```

Setting up monitoring on a separate AWS instance enables you to have a centralized Grafana logs and dashboard for all nodes in a cluster, as seen below:

![Centralized Logs](/images/centralized-logs.png)

![Main Dashboard](/images/run-validators1.png)

The separate monitoring AWS instance will have similar specs to the default AWS cloud server, except for its storage, which will be set to 50 GB.

Please note that setting up monitoring on a separate AWS instance will incur additional cost of setting up an additional AWS cloud server.

The command will then ask which Lux Go version you would like to install in the cloud server. You can choose `default` (which will install the latest version) or you can enter the name of an Lux L1 created with CLI that you plan to be validated by this node (we will get the latest version that is compatible with the deployed Lux L1's RPC version).

Once the command has successfully completed, Lux-CLI outputs all the created cloud server node IDs as well as the public IP that each node can be reached at.

Lux-CLI also outputs the command that you can use to ssh into each cloud server node.

Finally, if monitoring is set up, Lux-CLI will also output the Grafana link where the 
centralized dashboards and logs can be accessed.

By the end of successful run of `create` command, Lux-CLI would have:

- Installed Lux Go in cloud server
- Installed Lux CLI in cloud server
- Downloaded the `.pem` private key file to access the cloud server into your local `.ssh` directory. Back up this private key file as you will not be able to ssh into the cloud server node without it (unless `ssh-agent` is used).
- Downloaded `staker.crt` and `staker.key` files to your local `.lux-cli` directory so that you can back up your node. More info about node backup can be found [here](/docs/nodes/maintain/backup-restore)
- Started the process of bootstrapping your new Lux node to the Primary Network (for non-Devnet only).

Please note that Avalance CLI can be configured to use `ssh-agent` for ssh communication. In this case public key will be read from there and cloud server will be accessible using it. Yubikey hardware can be also used to store private ssh key. Please use official Yubikey documentation, for example \[[https://developers.yubico.com/PGP/SSH\_authentication/](https://developers.yubico.com/PGP/SSH_authentication/)\] for more details.

Check Bootstrap Status[​](#check-bootstrap-status "Direct link to heading")
---------------------------------------------------------------------------

<Callout title="Note">
Ignore for Devnet
</Callout>

Please note that you will have to wait until the nodes have finished bootstrapping before the nodes can be Primary Network or Lux L1 Validators. To check whether all the nodes in a cluster have finished bootstrapping, run `lux node status <clusterName>`.


# Run Validator on GCP (/docs/tooling/avalanche-cli/create-avalanche-nodes/run-validators-gcp)

---
title: Run Validator on GCP
description: This page demonstrates how to deploy Lux validators on GCP using just one Lux-CLI command.
---

This page demonstrates how to deploy Lux validators on GCP using just one Lux-CLI command.

<Callout title="Note">
Currently, only Testnet network and Devnets are supported.
</Callout>

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to:

- Create a GCP account [here](https://console.cloud.google.com/freetrial) and create a new project
- Enable Compute Engine API [here](https://console.cloud.google.com/apis/api/compute.googleapis.com)
- Download the key json for the automatically created service account as shown [here](https://cloud.google.com/iam/docs/keys-create-delete#creating)

## Create Validator

To create Lux validators, run:

```bash
lux node create <clusterName>
```

The created nodes will be part of cluster `clusterName` and all lux node commands applied to cluster `clusterName` will apply to all nodes in the cluster.

<Callout title="Note">
Please note that running a validator on GCP will incur costs.

Lux Network is not responsible for the cost incurred from running an Lux validator on cloud services via Lux-CLI.
</Callout>

Currently, we have set the following specs of the GCP cloud server to a fixed value, but we plan to enable customization in the near future:

- OS Image: `Ubuntu 20.04 LTS`
- Storage: `1 TB`

Instance type can be specified via `--node-type` parameter or via interactive menu. `e2-standard-8` is default(recommended) instance size.

The command will ask which region you want to set up your cloud server in:

```bash
Which Google Region do you want to set up your node(s) in?:
  ▸ us-east1
    us-central1
    us-west1
    Choose custom Google Region (list of Google Regions available at https://cloud.google.com/compute/docs/regions-zones/)
```

The command will next ask whether you want to set up monitoring for your nodes. 

```bash
  Do you want to set up a separate instance to host monitoring? (This enables you to monitor all your set up instances in one dashboard): 
  ▸ Yes
    No
```

Setting up monitoring on a separate GCP instance enables you to have a unified Grafana dashboard for all nodes in a cluster, as seen below:

![Centralized Logs](/images/centralized-logs.png)

![Main Dashboard](/images/gcp1.png)

The separate monitoring GCP instance will have similar specs to the default GCP cloud server, except for its storage, which will be set to 50 GB.

Please note that setting up monitoring on a separate GCP instance will incur additional cost of setting up an additional GCP cloud server.

The command will then ask which Lux Go version you would like to install in the cloud server. You can choose `default` (which will install the latest version) or you can enter the name of an Lux L1 created with CLI that you plan to be validated by this node (we will get the latest version that is compatible with the deployed Lux L1's RPC version).

Once the command has successfully completed, Lux-CLI outputs all the created cloud server node IDs as well as the public IP that each node can be reached at.

Lux-CLI also outputs the command that you can use to ssh into each cloud server node.

Finally, if monitoring is set up, Lux-CLI will also output the Grafana link where the centralized dashboards and logs can be accessed.

By the end of successful run of `create` command, Lux-CLI would have:

- Installed Lux Go in cloud server
- Installed Lux CLI in cloud server
- Downloaded the `.pem` private key file to access the cloud server into your local `.ssh` directory. Back up this private key file as you will not be able to ssh into the cloud server node without it (unless `ssh-agent` is used).
- Downloaded `staker.crt` and `staker.key` files to your local `.lux-cli` directory so that you can back up your node. More info about node backup can be found [here](/docs/nodes/maintain/backup-restore)
- Started the process of bootstrapping your new Lux node to the Primary Network

Please note that Lux CLI can be configured to use `ssh-agent` for ssh access to cloud server. Yubikey hardware can be also used to store private ssh key. Please use official Yubikey documentation, for example \[[https://developers.yubico.com/PGP/SSH\_authentication/](https://developers.yubico.com/PGP/SSH_authentication/)\] for more details.

Check Bootstrap Status[​](#check-bootstrap-status "Direct link to heading")
---------------------------------------------------------------------------

<Callout title="Note">
Ignore for Devnet
</Callout>

Please note that you will have to wait until the nodes have finished bootstrapping before the nodes can be Primary Network or Lux L1 Validators. To check whether all the nodes in a cluster have finished bootstrapping, run `lux node status <clusterName>`.

# Setup a Devnet (/docs/tooling/avalanche-cli/create-avalanche-nodes/setup-devnet)

---
title: Setup a Devnet
description: This page demonstrates how to setup a Devnet of cloud-based validators using Lux-CLI, and deploy a VM into it.
---

Devnets (Developer Networks) are isolated Lux networks deployed on the cloud. Similar to local networks in terms of configuration and usage but installed on remote nodes.

Think of DevNets as being an intermediate step in the developer testing process after local network and before Testnet network.

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to create an AWS account and have an updated AWS `credentials` file in home directory with [default] profile or set up your GCP account according to [here](/docs/tooling/lux-cli/create-lux-nodes/run-validators-gcp).

Note: the tutorial uses AWS hosts, but Devnets can also be created and operated in other supported cloud providers, such as GCP.

## Setting up a Devnet

Setting up a Devnet consists of:

- Creating a cluster of cloud servers
- Deploying an Lux L1 into the cluster
- Adding the cloud servers as validator nodes in the Lux L1

To execute all steps above in one command, run:

```bash
lux node devnet wiz <clusterName>
```

Command line flags can be used instead of interacting with the prompts. The complete command line
flags for `devnet wiz` command can be found [here](/docs/tooling/cli-commands#node-devnet-wiz).

Let's go through several examples with the full command (with flags) provided.

### Create a Devnet and Deploy Subnet-EVM Based Lux L1 into the Devnet

For example, to spin up a Devnet with 5 validator nodes and 1 API node in 5 regions each 
(us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1) in AWS with each node having spec of 
c7g.8xlarge AWS EC2 instance type and io2 volume type, with Lux L1 `<blockchainName>` deployed 
into the Devnet, we will run :

```bash
lux node devnet wiz <clusterName> <blockchainName> --authorize-access
  --aws --num-apis 1,1,1,1,1 --num-validators 5,5,5,5,5 
  --region us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1 --default-validator-params 
  --node-type c7g.8xlarge --aws-volume-type=io2

Creating the devnet
...
Waiting for node(s) in cluster <clusterName> to be healthy...
...
Nodes healthy after 33 seconds

Deploying the subnet
...
Setting the nodes as subnet trackers
...
Waiting for node(s) in cluster <clusterName>to be healthy...
Nodes healthy after 33 seconds
...
Waiting for node(s) in cluster <clusterName> to be syncing subnet <blockchainName>...
Nodes Syncing <blockchainName> after 5 seconds

Adding nodes as subnet validators
...
Waiting for node(s) in cluster <clusterName> to be validating subnet <blockchainName>...
Nodes Validating <blockchainName> after 23 seconds

Devnet <clusterName> has been created and is validating subnet <blockchainName>!
```

### Create a Devnet and Deploy a Custom VM based Lux L1 into the Devnet

For this example, we will be using the custom VM [MorpheusVM](https://github.com/luxfi/hypersdk/tree/main/examples/morpheusvm)
built with [HyperSDK](https://github.com/luxfi/hypersdk).

The following settings will be used:

- `<repoUrl>` `https://github.com/luxfi/hypersdk/`
- `<branch>` `vryx-poc`
- `<buildScript>` `examples/morpheusvm/scripts/build.sh`
- `<genesisPath>` [Genesis File](/docs/tooling/lux-cli/create-lux-nodes/deploy-custom-vm#genesis-file)
- `<chainConfigPath>` [Blockchain Config](/docs/tooling/lux-cli/create-lux-nodes/deploy-custom-vm#blockchain-config)
- `<subnetConfigPath>` [Lux L1 Config](/docs/tooling/lux-cli/create-lux-nodes/deploy-custom-vm#lux-l1-config)
- `<avagoConfigPath>` [LuxGo Config](/docs/tooling/lux-cli/create-lux-nodes/deploy-custom-vm#luxgo-flags)

To spin up a Devnet with 5 validator nodes and 1 API node in 5 regions each
(us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1) in AWS with each node having spec of
c7g.8xlarge AWS EC2 instance type and io2 volume type, with the Custom VM based Lux L1 
`<blockchainName>` deployed into the Devnet, we will run :

```bash
lux node devnet wiz <clusterName> <blockchainName> --custom-subnet \
  --subnet-genesis <genesisPath> --custom-vm-repo-url <repoUrl> \
  --custom-vm-branch <branch> --custom-vm-build-script <buildScript> \
  --chain-config <chainConfigPath> --subnet-config <subnetConfigPath> \
  --node-config <avagoConfigPath> --authorize-access --aws --num-apis 1,1,1,1,1 \
  --num-validators 5,5,5,5,5  --region us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1 \
  --default-validator-params --node-type default

Creating the subnet
...
Creating the devnet
...
Waiting for node(s) in cluster <clusterName> to be healthy...
...
Nodes healthy after 33 seconds

Deploying the subnet
...
Setting the nodes as subnet trackers
...
Waiting for node(s) in cluster <clusterName>to be healthy...
Nodes healthy after 33 seconds
...
Waiting for node(s) in cluster <clusterName> to be syncing subnet <blockchainName>...
Nodes Syncing <blockchainName> after 5 seconds

Adding nodes as subnet validators
...
Waiting for node(s) in cluster <clusterName> to be validating subnet <blockchainName>...
Nodes Validating <blockchainName> after 23 seconds

Devnet <clusterName> has been created and is validating subnet <blockchainName>!
```

# Terminate All Nodes (/docs/tooling/avalanche-cli/create-avalanche-nodes/stop-node)

---
title: Terminate All Nodes
description: This page provides instructions for terminating cloud server nodes created by Lux-CLI.
---

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

Terminating All Nodes[​](#terminating-all-nodes "Direct link to heading")
-------------------------------------------------------------------------

To terminate all nodes in a cluster, run:

```bash
lux node destroy <clusterName>
```

<Callout type="warn">
ALPHA WARNING: This command will delete all files associated with the cloud servers in the cluster. This includes the downloaded `staker.crt` and `staker.key` files in your local `.lux-cli` directory (which are used to back up your node). More info about node backup can be found [here](/docs/nodes/maintain/backup-restore).
</Callout>

Once completed, the instance set up on AWS / GCP would have been terminated and the Static Public IP associated with it would have been released.

# Validate the Primary Network (/docs/tooling/avalanche-cli/create-avalanche-nodes/validate-primary-network)

---
title: Validate the Primary Network
description: This page demonstrates how to configure nodes to validate the Primary Network. Validation via Lux-CLI is currently only supported on Testnet.
---

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to have:

- Created a Cloud Server node as described for [AWS](/docs/tooling/lux-cli/create-lux-nodes/run-validators-aws) or [GCP](/docs/tooling/lux-cli/create-lux-nodes/run-validators-gcp)
- A node bootstrapped to the Primary Network (run `lux node status <clusterName>`to check bootstrap status as described [here](/docs/tooling/lux-cli/create-lux-nodes/run-validators-aws#check-bootstrap-status)
- Stored key / Ledger with LUX to pay for gas fess associated with adding node as Primary Network. Instructions on how to fund stored key on Testnet can be found [here](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet#funding-the-key).

Be a Primary Network Validator[​](#be-a-primary-network-validator "Direct link to heading")
-------------------------------------------------------------------------------------------

Once all nodes in a cluster are bootstrapped to Primary Network, we can now have the nodes be Primary Network Validators.

To have all nodes in cluster `clusterName` be Primary Network Validators, run:

```bash
lux node validate primary <clusterName>
```

The nodes will start validating the Primary Network 20 seconds after the command is run.

The wizard will ask us how we want to pay for the transaction fee. Choose `Use stored key` for Testnet:

```bash
 Which key source should be used to pay transaction fees?:
  ▸ Use stored key
    Use ledger
```

Once you have selected the key to pay with, choose how many LUX you would like to stake in the validator. Default is the minimum amount of LUX that can be staked in a Testnet Network Validator. More info regarding minimum staking amount in different networks can be found [here](/docs/primary-network/validate/how-to-stake#testnet-testnet).

```bash
 What stake weight would you like to assign to the validator?:
  ▸ Default (1.00 LUX)
    Custom
```

Next, choose how long the node will be validating for:

```bash
 How long should your validator validate for?:
  ▸ Minimum staking duration on primary network
    Custom
```

Once all the inputs are completed you will see transaction IDs indicating that all the nodes in the cluster will be Primary Network Validators once the start time has elapsed.

# On Local Network (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-locally)

---
title: On Local Network
description: This guide shows you how to deploy an Lux L1 to a local Lux network.
---

This how-to guide focuses on taking an already created Lux L1 configuration and deploying it to a local Lux network.

## Prerequisites

- [Lux-CLI installed](/docs/tooling/lux-cli)
- You have [created an Lux L1 configuration](/docs/tooling/lux-cli#create-your-lux-l1-configuration)

Deploying Lux L1s Locally[​](#deploying-lux-l1s-locally "Direct link to heading")
---------------------------------------------------------------------------------

In the following commands, make sure to substitute the name of your Lux L1 configuration for `<blockchainName>`.

To deploy your Lux L1, run:

```bash
lux blockchain deploy <blockchainName>
```

and select `Local Network` to deploy on. Alternatively, you can bypass this prompt by providing the `--local` flag. For example:

```bash
lux blockchain deploy <blockchainName> --local
```

The command may take a couple minutes to run.

Note: If you run `bash` on your shell and are running Lux-CLI on ARM64 on Mac, you will require Rosetta 2 to be able to deploy Lux L1s locally. You can download Rosetta 2 using `softwareupdate --install-rosetta` .

### Results[​](#results "Direct link to heading")

If all works as expected, the command output should look something like this:

```bash
> lux blockchain deploy myblockchain

✔ Local Network
Deploying [myblockchain] to Local Network

LuxGo path: /Users/felipe.madero/.lux-cli/bin/luxgo/luxgo-v1.13.0/luxgo

Booting Network. Wait until healthy...

Node logs directory: /Users/felipe.madero/.lux-cli/runs/network_20250410_104205/<NodeID>/logs

Network ready to use.

Using [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p] to be set as a change owner for leftover LUX
LuxGo path: /Users/felipe.madero/.lux-cli/bin/luxgo/luxgo-v1.13.0/luxgo

✓ Local cluster myblockchain-local-node-local-network not found. Creating...
Starting local luxgo node using root: /Users/felipe.madero/.lux-cli/local/myblockchain-local-node-local-network ...
✓ Booting Network. Wait until healthy...
✓ Luxgo started and ready to use from /Users/felipe.madero/.lux-cli/local/myblockchain-local-node-local-network

Node logs directory: /Users/felipe.madero/.lux-cli/local/myblockchain-local-node-local-network/<NodeID>/logs

Network ready to use.

URI: http://127.0.0.1:60172
NodeID: NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN

Your blockchain control keys: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
Your blockchain auth keys for chain creation: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
CreateSubnetTx fee: 0.000010278 LUX
Blockchain has been created with ID: 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw
Now creating blockchain...
CreateChainTx fee: 0.000129564 LUX
+--------------------------------------------------------------------+
|                         DEPLOYMENT RESULTS                         |
+---------------+----------------------------------------------------+
| Chain Name    | myblockchain                                       |
+---------------+----------------------------------------------------+
| Subnet ID     | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw |
+---------------+----------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV  |
+---------------+----------------------------------------------------+
| Blockchain ID | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y  |
+---------------+                                                    |
| Platform-Chain TXID  |                                                    |
+---------------+----------------------------------------------------+
Now calling ConvertSubnetToL1Tx...
ConvertSubnetToL1Tx fee: 0.000036992 LUX
ConvertSubnetToL1Tx ID: 2d2EE7AorEhfKLBtnDGnAtcDYMGfPbWnHYDpNDm3SopYg6VtpV
Waiting for the Subnet to be converted into a sovereign L1 ... 100% [===============]

Validator Manager Protocol: LP99
Restarting node NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN to track newly deployed subnet/s
Waiting for blockchain Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y to be bootstrapped
✓ Local Network successfully tracking myblockchain
✓ Checking if node is healthy...
✓ Node is healthy after 0 seconds
Initializing Proof of Authority Validator Manager contract on blockchain myblockchain ...
✓ Proof of Authority Validator Manager contract successfully initialized on blockchain myblockchain

Your L1 is ready for on-chain interactions.

RPC Endpoint: http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc
ICM Messenger successfully deployed to myblockchain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to myblockchain (0xEc7018552DC7E197Af85f157515f5976b1A15B12)
ICM Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)
✓ ICM is successfully deployed

Generating relayer config file at /Users/felipe.madero/.lux-cli/runs/network_20250410_104205/icm-relayer-config.json
Relayer version icm-relayer-v1.6.2
Executing Relayer
✓ Relayer is successfully deployed

+--------------------------------------------------------------------------------------------------------------------------------+
|                                                          MYBLOCKCHAIN                                                          |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Name          | myblockchain                                                                                                   |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV                                                              |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM Version    | v0.7.3                                                                                                         |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Validation    | Proof Of Authority                                                                                             |
+---------------+--------------------------+-------------------------------------------------------------------------------------+
| Local Network | ChainID                  | 888                                                                                 |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | SubnetID                 | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw                                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | Owners (Threhold=1)      | P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p                                     |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (CB58)      | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y                                   |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (HEX)       | 0x48644613a5ef255fa171bf4773df668b57ea0ea9593df8927a6d9f32376a9c6f                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | RPC Endpoint             | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+---------------+--------------------------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------+
|                                         ICM                                        |
+---------------+-----------------------+--------------------------------------------+
| Local Network | ICM Messenger Address | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf |
|               +-----------------------+--------------------------------------------+
|               | ICM Registry Address  | 0xEc7018552DC7E197Af85f157515f5976b1A15B12 |
+---------------+-----------------------+--------------------------------------------+

+--------------------------+
|           TOKEN          |
+--------------+-----------+
| Token Name   | TST Token |
+--------------+-----------+
| Token Symbol | TST       |
+--------------+-----------+

+---------------------------------------------------------------------------------------------------------------------------------------+
|                                                        INITIAL TOKEN ALLOCATION                                                       |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| DESCRIPTION             | ADDRESS AND PRIVATE KEY                                          | AMOUNT (TST) | AMOUNT (WEI)              |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Main funded account     | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000      | 1000000000000000000000000 |
| ewoq                    | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Used by ICM             | 0xf34408C05e3B339B1c89d15163d4B9D96845597A                       | 600          | 600000000000000000000     |
| cli-teleporter-deployer | 30d57c7b6e7e393e2e4ce8166768b497cc37930361a15b1c647d6e665d88afff |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+

+----------------------------------------------------------------------------------------------------------------------------------+
|                                                          SMART CONTRACTS                                                         |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION                            | ADDRESS                                    | DEPLOYER                                   |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Validator Messages Lib                 | 0x9C00629cE712B0255b17A4a657171Acd15720B8C |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin                            | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| LP99 Compatible PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy                      | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

+-------------------------------------------------------------------------------------------------+
|                                      MYBLOCKCHAIN RPC URLS                                      |
+-----------+-------------------------------------------------------------------------------------+
| Localhost | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------+
|                           PRIMARY NODES                          |
+------------------------------------------+-----------------------+
| NODE ID                                  | LOCALHOST ENDPOINT    |
+------------------------------------------+-----------------------+
| NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg | http://127.0.0.1:9650 |
+------------------------------------------+-----------------------+
| NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ | http://127.0.0.1:9652 |
+------------------------------------------+-----------------------+
+----------------------------------------------------------------------------------+
|                                     L1 NODES                                     |
+------------------------------------------+------------------------+--------------+
| NODE ID                                  | LOCALHOST ENDPOINT     | L1           |
+------------------------------------------+------------------------+--------------+
| NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN | http://127.0.0.1:60172 | myblockchain |
+------------------------------------------+------------------------+--------------+

+-------------------------------------------------------------------------------------------------------+
|                                           WALLET CONNECTION                                           |
+-----------------+-------------------------------------------------------------------------------------+
| Network RPC URL | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------------+-------------------------------------------------------------------------------------+
| Network Name    | myblockchain                                                                        |
+-----------------+-------------------------------------------------------------------------------------+
| Chain ID        | 888                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Symbol    | TST                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Name      | TST Token                                                                           |
+-----------------+-------------------------------------------------------------------------------------+
✓ L1 is successfully deployed on Local Network
```

You can use the deployment details to connect to and interact with your Lux L1.

Deploying Lux L1s Locally[​](#deploying-lux-l1s-locally)
---------------------------------------------------------------------------------

To deploy your Lux L1, run:

```bash
lux blockchain deploy myblockchain
```

Make sure to substitute the name of your Lux L1 if you used a different one than `myblockchain`.

```bash
? Choose a network for the operation: 
  ▸ Local Network
    Devnet
    Etna Devnet
    Testnet Testnet
    Mainnet
```

Next, select `Local Network`.

This command boots a three node Lux network on your machine:

- Two nodes to act as primary validators for the local network, that will validate the local P and C chains (unrelated to testnet/mainnet)..
- One node to act as sovereign validator for the new L1 that is deployed into the local network.

The command needs to download the latest versions of LuxGo and Subnet-EVM. It may take a couple minutes to run.

Note: If you run `bash` on your shell and are running Lux-CLI on ARM64 on Mac, you will require Rosetta 2 to be able to deploy Lux L1s locally. You can download Rosetta 2 using `softwareupdate --install-rosetta` .

If all works as expected, the command output should look something like this:

```bash
lux blockchain deploy myblockchain

# output
✔ Local Network
Deploying [myblockchain] to Local Network

LuxGo path: /Users/felipe.madero/.lux-cli/bin/luxgo/luxgo-v1.13.0/luxgo

Booting Network. Wait until healthy...

Node logs directory: /Users/felipe.madero/.lux-cli/runs/network_20250410_104205/<NodeID>/logs

Network ready to use.

Using [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p] to be set as a change owner for leftover LUX
LuxGo path: /Users/felipe.madero/.lux-cli/bin/luxgo/luxgo-v1.13.0/luxgo

✓ Local cluster myblockchain-local-node-local-network not found. Creating...
Starting local luxgo node using root: /Users/felipe.madero/.lux-cli/local/myblockchain-local-node-local-network ...
✓ Booting Network. Wait until healthy...
✓ Luxgo started and ready to use from /Users/felipe.madero/.lux-cli/local/myblockchain-local-node-local-network

Node logs directory: /Users/felipe.madero/.lux-cli/local/myblockchain-local-node-local-network/<NodeID>/logs

Network ready to use.

URI: http://127.0.0.1:60172
NodeID: NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN

Your blockchain control keys: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
Your blockchain auth keys for chain creation: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
CreateSubnetTx fee: 0.000010278 LUX
Blockchain has been created with ID: 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw
Now creating blockchain...
CreateChainTx fee: 0.000129564 LUX
+--------------------------------------------------------------------+
|                         DEPLOYMENT RESULTS                         |
+---------------+----------------------------------------------------+
| Chain Name    | myblockchain                                       |
+---------------+----------------------------------------------------+
| Subnet ID     | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw |
+---------------+----------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV  |
+---------------+----------------------------------------------------+
| Blockchain ID | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y  |
+---------------+                                                    |
| Platform-Chain TXID  |                                                    |
+---------------+----------------------------------------------------+
Now calling ConvertSubnetToL1Tx...
ConvertSubnetToL1Tx fee: 0.000036992 LUX
ConvertSubnetToL1Tx ID: 2d2EE7AorEhfKLBtnDGnAtcDYMGfPbWnHYDpNDm3SopYg6VtpV
Waiting for the Subnet to be converted into a sovereign L1 ... 100% [===============]

Validator Manager Protocol: LP99
Restarting node NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN to track newly deployed subnet/s
Waiting for blockchain Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y to be bootstrapped
✓ Local Network successfully tracking myblockchain
✓ Checking if node is healthy...
✓ Node is healthy after 0 seconds
Initializing Proof of Authority Validator Manager contract on blockchain myblockchain ...
✓ Proof of Authority Validator Manager contract successfully initialized on blockchain myblockchain

Your L1 is ready for on-chain interactions.

RPC Endpoint: http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc
ICM Messenger successfully deployed to myblockchain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to myblockchain (0xEc7018552DC7E197Af85f157515f5976b1A15B12)
ICM Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)
✓ ICM is successfully deployed

Generating relayer config file at /Users/felipe.madero/.lux-cli/runs/network_20250410_104205/icm-relayer-config.json
Relayer version icm-relayer-v1.6.2
Executing Relayer
✓ Relayer is successfully deployed

+--------------------------------------------------------------------------------------------------------------------------------+
|                                                          MYBLOCKCHAIN                                                          |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Name          | myblockchain                                                                                                   |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV                                                              |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM Version    | v0.7.3                                                                                                         |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Validation    | Proof Of Authority                                                                                             |
+---------------+--------------------------+-------------------------------------------------------------------------------------+
| Local Network | ChainID                  | 888                                                                                 |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | SubnetID                 | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw                                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | Owners (Threhold=1)      | P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p                                     |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (CB58)      | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y                                   |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (HEX)       | 0x48644613a5ef255fa171bf4773df668b57ea0ea9593df8927a6d9f32376a9c6f                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | RPC Endpoint             | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+---------------+--------------------------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------+
|                                         ICM                                        |
+---------------+-----------------------+--------------------------------------------+
| Local Network | ICM Messenger Address | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf |
|               +-----------------------+--------------------------------------------+
|               | ICM Registry Address  | 0xEc7018552DC7E197Af85f157515f5976b1A15B12 |
+---------------+-----------------------+--------------------------------------------+

+--------------------------+
|           TOKEN          |
+--------------+-----------+
| Token Name   | TST Token |
+--------------+-----------+
| Token Symbol | TST       |
+--------------+-----------+

+---------------------------------------------------------------------------------------------------------------------------------------+
|                                                        INITIAL TOKEN ALLOCATION                                                       |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| DESCRIPTION             | ADDRESS AND PRIVATE KEY                                          | AMOUNT (TST) | AMOUNT (WEI)              |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Main funded account     | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000      | 1000000000000000000000000 |
| ewoq                    | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Used by ICM             | 0xf34408C05e3B339B1c89d15163d4B9D96845597A                       | 600          | 600000000000000000000     |
| cli-teleporter-deployer | 30d57c7b6e7e393e2e4ce8166768b497cc37930361a15b1c647d6e665d88afff |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+

+----------------------------------------------------------------------------------------------------------------------------------+
|                                                          SMART CONTRACTS                                                         |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION                            | ADDRESS                                    | DEPLOYER                                   |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Validator Messages Lib                 | 0x9C00629cE712B0255b17A4a657171Acd15720B8C |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin                            | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| LP99 Compatible PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy                      | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

+-------------------------------------------------------------------------------------------------+
|                                      MYBLOCKCHAIN RPC URLS                                      |
+-----------+-------------------------------------------------------------------------------------+
| Localhost | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------+
|                           PRIMARY NODES                          |
+------------------------------------------+-----------------------+
| NODE ID                                  | LOCALHOST ENDPOINT    |
+------------------------------------------+-----------------------+
| NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg | http://127.0.0.1:9650 |
+------------------------------------------+-----------------------+
| NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ | http://127.0.0.1:9652 |
+------------------------------------------+-----------------------+
+----------------------------------------------------------------------------------+
|                                     L1 NODES                                     |
+------------------------------------------+------------------------+--------------+
| NODE ID                                  | LOCALHOST ENDPOINT     | L1           |
+------------------------------------------+------------------------+--------------+
| NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN | http://127.0.0.1:60172 | myblockchain |
+------------------------------------------+------------------------+--------------+

+-------------------------------------------------------------------------------------------------------+
|                                           WALLET CONNECTION                                           |
+-----------------+-------------------------------------------------------------------------------------+
| Network RPC URL | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------------+-------------------------------------------------------------------------------------+
| Network Name    | myblockchain                                                                        |
+-----------------+-------------------------------------------------------------------------------------+
| Chain ID        | 888                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Symbol    | TST                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Name      | TST Token                                                                           |
+-----------------+-------------------------------------------------------------------------------------+
✓ L1 is successfully deployed on Local Network
```

To manage the newly deployed local Lux network, see [the `lux network` command tree](/docs/tooling/cli-commands#lux-network).

You can use the deployment details to connect to and interact with your Lux L1. Now it's time to interact with it.

## Interacting with Your Lux L1

You can use the value provided by `Browser Extension connection details` to connect to your Lux L1 with Core, MetaMask, or any other wallet.

<Callout title="Note">
To allow API calls from other machines, use `--http-host=0.0.0.0` in the config.
</Callout>

```bash
Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/2BK8CKA4Vfvi69TBTc5GW94JQ9nPiL8xPpPNeeckb9UFSPYedD/rpc
Funded address:   0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC with 1000000 (10^18) - private key: 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
Network name:     myblockchain
Chain ID:         888
Currency Symbol:  TST
```

This tutorial uses Core.

### Importing the Test Private Key[​](#importing-the-test-private-key)

<Callout type="warn">
This address derives from a well-known private key. Anyone can steal funds sent to this address. Only use it on development networks that only you have access to. If you send production funds to this address, attackers may steal them instantly.
</Callout>

First, you need to import your airdrop private key into Core.

In the Accounts screen, select the `Imported` tab. Click on `Import private key`.

![](/images/deploy-subnet1.png)

Here, enter the private key. Import the well-known private key `0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027`.

![](/images/deploy-subnet2.png)

Next, rename the Core account to prevent confusion. On the `Imported` tab, click on the pen icon next to your account. Rename the account `DO NOT USE -- Public test key` to prevent confusion with any personal wallets.

![Rename Account](/images/deploy-subnet3.png)

![Rename Account](/images/deploy-subnet4.png)

### Connect to the Lux L1[​](#connect-to-the-lux-l1)

Next, you need to add your Lux L1 to Core's networks.

In the Core Extension click, `See All Networks` and then select the `+` icon in the top right.

![Add network](/images/deploy-subnet5.png)

Enter your Lux L1's details, found in the output of your `lux blockchain deploy` [command](#deploying-lux-l1s-locally), into the form and click `Save`.

![Add network 2](/images/deploy-subnet6.png)

If all worked as expected, your balance should read 1 million tokens. Your Lux L1 is ready for action. You might want to try to [Deploy a Smart Contract on Your Subnet-EVM Using Remix and Core](/docs/lux-l1s/add-utility/deploy-smart-contract).

![Lux L1 in Core](/images/deploy-subnet7.png)

## Deploying Multiple Lux L1s[​](#deploying-multiple-lux-l1s "Direct link to heading")

You may deploy multiple Lux L1s concurrently, but you can't deploy the same Lux L1 multiple times without resetting all deployed Lux L1 state.

## Redeploying the Lux L1

To redeploy the Lux L1, you first need to wipe the Lux L1 state. This permanently deletes all data from all locally deployed Lux L1s. To do so, run

```bash
lux network clean
```

You are now free to redeploy your Lux L1 with

```bash
lux blockchain deploy <blockchainName> --local
```

## Stopping the Local Network

To gracefully stop a running local network while preserving state, run:

```bash
lux network stop

# output
Network stopped successfully.
```

When restarted, all of your deployed Lux L1s resume where they left off.

### Resuming the Local Network

To resume a stopped network, run:

```bash
lux network start

# output
Starting previously deployed and stopped snapshot
Booting Network. Wait until healthy...
...............
Network ready to use. Local network node endpoints:
+-------+----------+------------------------------------------------------------------------------------+
| NODE  |    VM    |                                        URL                                         |
+-------+----------+------------------------------------------------------------------------------------+
| node5 | myblockchain | http://127.0.0.1:9658/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node1 | myblockchain | http://127.0.0.1:9650/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node2 | myblockchain | http://127.0.0.1:9652/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node3 | myblockchain | http://127.0.0.1:9654/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node4 | myblockchain | http://127.0.0.1:9656/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
```

The network resumes with the same state it paused with.

## Next Steps

After you feel comfortable with this deployment flow, try deploying smart contracts on your chain with [Remix](https://remix.ethereum.org/), [Hardhat](https://hardhat.org/), or [Foundry](https://github.com/foundry-rs/foundry). You can also experiment with customizing your Lux L1 by addingprecompiles or adjusting the airdrop.

Once you've developed a stable Lux L1 you like, see [Create an EVM Lux L1 on Testnet Testnet](/docs/lux-l1s/evm-configuration/customize-lux-l1) to take your Lux L1 one step closer to production.

## FAQ

**How is the Lux L1 ID (SubnetID) determined upon creation?**

The Lux L1 ID (SubnetID) is the hash of the transaction that created the Lux L1.


# On Testnet Testnet (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-fuji-testnet)

---
title: On Testnet Testnet
description: This tutorial shows how to deploy an Lux L1 on Testnet Testnet.
---

<Callout title="Note">
This document describes how to use the new Lux-CLI to deploy an Lux L1 on `Testnet`.
</Callout>

After trying out an Lux L1 on a local box by following [this tutorial](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-locally), next step is to try it out on `Testnet` Testnet.

In this article, it's shown how to do the following on `Testnet` Testnet.

- Create an Lux L1.
- Deploy a virtual machine based on Subnet-EVM.
- Join a node to the newly created Lux L1.
- Add a node as a validator to the Lux L1.

All IDs in this article are for illustration purposes. They can be different in your own run-through of this tutorial.

## Prerequisites

- [`Lux-CLI`](https://github.com/luxfi/lux-cli) installed

Virtual Machine[​](#virtual-machine "Direct link to heading")
-------------------------------------------------------------

Lux can run multiple blockchains. Each blockchain is an instance of a [Virtual Machine](/docs/primary-network/virtual-machines), much like an object in an object-oriented language is an instance of a class. That's, the VM defines the behavior of the blockchain.

[Subnet-EVM](https://github.com/luxfi/subnet-evm) is the VM that defines the Lux L1 Contract Chains. Subnet-EVM is a simplified version of [Lux LUExchange-Chain](https://github.com/luxfi/luxgo/tree/master/graft/coreth).

This chain implements the Ethereum Virtual Machine and supports Solidity smart contracts as well as most other Ethereum client features.


Lux-CLI[​](#lux-cli "Direct link to heading")
---------------------------------------------------------

If not yet installed, install `Lux-CLI` following the tutorial at [Lux-CLI installation](/docs/tooling/lux-cli)

### Private Key[​](#private-key "Direct link to heading")

All commands which issue a transaction require either a private key loaded into the tool, or a connected ledger device.

This tutorial focuses on stored key usage and leave ledger operation details for the `Mainnet` deploy one, as `Mainnet` operations requires ledger usage, while for `Testnet` it's optional.

`Lux-CLI` supports the following key operations:

- create
- delete
- export
- list

<Callout type="warn">
You should only use the private key created for this tutorial for testing operations on `Testnet` or other testnets. Don't use this key on `Mainnet`. CLI is going to store the key on your file system. Whoever gets access to that key is going to have access to all funds secured by that private key.
</Callout>

Run `create` if you don't have any private key available yet. You can create multiple named keys. Each command requiring a key is going to therefore require the appropriate key name you want to use.

```bash
lux key create mytestkey
```

This is going to generate a new key named `mytestkey`. The command is going to then also print addresses associated with the key:

```bash
Generating new key...
Key created
+-----------+-------------------------------+-------------------------------------------------+---------------+
| KEY NAME  |             CHAIN             |                     ADDRESS                     |    NETWORK    |
+-----------+-------------------------------+-------------------------------------------------+---------------+
| mytestkey | LUExchange-Chain (Ethereum hex format) | 0x86BB07a534ADF43786ECA5Dd34A97e3F96927e4F      | All           |
+           +-------------------------------+-------------------------------------------------+---------------+
|           | Platform-Chain (Bech32 format)       | P-custom1a3azftqvygc4tlqsdvd82wks2u7nx85rg7v8ta | Local Network |
+           +                               +-------------------------------------------------+---------------+
|           |                               | P-testnet1a3azftqvygc4tlqsdvd82wks2u7nx85rhk6zqh   | Testnet          |
+-----------+-------------------------------+-------------------------------------------------+---------------+
```

You may use the LUExchange-Chain address (`0x86BB07a534ADF43786ECA5Dd34A97e3F96927e4F`) to fund your key:
- **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet tokens automatically
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/)

The command also prints Platform-Chain addresses for both the default local network and `Testnet`. The latter (`P-testnet1a3azftqvygc4tlqsdvd82wks2u7nx85rhk6zqh`) is the one needed for this tutorial.

The `delete` command of course deletes a private key:

```bash
lux key delete mytestkey
```

Be careful though to always have a key available for commands involving transactions.

The `export` command is going to **print your private key** in hex format to stdout.

```bash
lux key export mytestkey
21940fbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb5f0b
```

This key is intentionally modified.

You can also **import** a key by using the `--file` flag with a path argument and also providing a name to it:

```bash
lux key create othertest --file /tmp/test.pk
Loading user key...
Key loaded
```

Finally, the `list` command is going to list all your keys in your system and their associated addresses (CLI stores the keys in a special directory on your file system, tampering with the directory is going to result in malfunction of the tool).

```bash
lux key list
+-----------+-------------------------------+-------------------------------------------------+---------------+
| KEY NAME  |             CHAIN             |                     ADDRESS                     |    NETWORK    |
+-----------+-------------------------------+-------------------------------------------------+---------------+
| othertest | LUExchange-Chain (Ethereum hex format) | 0x36c83263e33f9e87BB98D3fEb54a01E35a3Fa735      | All           |
+           +-------------------------------+-------------------------------------------------+---------------+
|           | Platform-Chain (Bech32 format)       | P-custom1n5n4h99j3nx8hdrv50v8ll7aldm383nap6rh42 | Local Network |
+           +                               +-------------------------------------------------+---------------+
|           |                               | P-testnet1n5n4h99j3nx8hdrv50v8ll7aldm383na7j4j7q   | Testnet          |
+-----------+-------------------------------+-------------------------------------------------+---------------+
| mytestkey | LUExchange-Chain (Ethereum hex format) | 0x86BB07a534ADF43786ECA5Dd34A97e3F96927e4F      | All           |
+           +-------------------------------+-------------------------------------------------+---------------+
|           | Platform-Chain (Bech32 format)       | P-custom1a3azftqvygc4tlqsdvd82wks2u7nx85rg7v8ta | Local Network |
+           +                               +-------------------------------------------------+---------------+
|           |                               | P-testnet1a3azftqvygc4tlqsdvd82wks2u7nx85rhk6zqh   | Testnet          |
+-----------+-------------------------------+-------------------------------------------------+---------------+
```

#### Funding the Key[​](#funding-the-key "Direct link to heading")

<Callout type="warn">
Do these steps only to follow this tutorial for `Testnet` addresses. To access the wallet for `Mainnet`, the use of a ledger device is strongly recommended.
</Callout>

1. A newly created key has no funds on it. You have several options to fund it:
   - **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet tokens automatically on LUExchange-Chain and Platform-Chain
   - **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/) with your LUExchange-Chain address. If you have an LUX balance on Mainnet, you can request tokens directly. Otherwise, request a faucet coupon on [Guild](https://guild.xyz/lux) or contact admins/mods on [Discord](https://discord.com/invite/RwXY7P6)
2. Export your key via the `lux key export` command. The output is your private key, which will help you [import](https://support.lux.network/en/articles/6821877-core-extension-how-can-i-import-an-account) your account into the Core extension.
3. Connect Core extension to [Core web](https://core.app/), and move the test funds from LUExchange-Chain to the Platform-Chain by clicking Stake, then Cross-Chain Transfer (find more details on [this tutorial](https://support.lux.network/en/articles/8133713-core-web-how-do-i-make-cross-chain-transfers-in-core-stake)).

After following these 3 steps, your test key should now have a balance on the Platform-Chain on `Testnet` Testnet.

Create an EVM Lux L1[​](#create-an-evm-lux-l1 "Direct link to heading")
-----------------------------------------------------------------------

Creating an Lux L1 with `Lux-CLI` for `Testnet` works the same way as with a local network. In fact, the `create` commands only creates a specification of your Lux L1 on the local file system. Afterwards the Lux L1 needs to be _deployed_. This allows to reuse configs, by creating the config with the `create` command, then first deploying to a local network and successively to `Testnet` - and eventually to `Mainnet`.

To create an EVM Lux L1, run the `blockchain create` command with a name of your choice:

```bash
lux blockchain create testblockchain
```

This is going to start a series of prompts to customize your EVM Lux L1 to your needs. Most prompts have some validation to reduce issues due to invalid input. The first prompt asks for the type of the virtual machine (see [Virtual Machine](#virtual-machine)).

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
  ▸ SubnetEVM
    Custom
```

As you want to create an EVM Lux L1, just accept the default `Subnet-EVM`.

Choose either Proof of Authority (PoA) or Proof of Stake (PoS) as your consensus mechanism.

```bash
? Which validator management type would you like to use in your blockchain?:
  ▸ Proof Of Authority
    Proof Of Stake
    Explain the difference
```
For this tutorial, select `Proof of Authority (PoA)`.

For more info, reference the [Validator Management Contracts](/docs/lux-l1s/validator-manager/contract).

```bash
Which address do you want to enable as controller of ValidatorManager contract?:
  ▸ Get address from an existing stored key (created from lux key create or lux key import)
    Custom
```
This address will be able to add and remove validators from your Lux L1. You can either use an existing key or create a new one.
In addition to being the PoA owner, this address will also be the owner of the `ProxyAdmin` contract of the Validator Manager's `TransparentUpgradeableProxy`. This address will be able to upgrade (PoA -> PoS) the Validator Manager implementation through updating the proxy.

Next, CLI will ask for blockchain configuration values. Since we are deploying to Testnet, select `I want to use defaults for a production environment`.

```bash
? Do you want to use default values for the Blockchain configuration?:
  ▸ I want to use defaults for a test environment
    I want to use defaults for a production environment
    I don't want to use default values
    Explain the difference
```

The default values for production environment:

- Use latest Subnet-EVM release
- Allocate 1 million tokens to:
    1. **a newly created key (production)**: name of this key will be in the format of `subnet_blockchainName_airdrop`
    2. **ewoq address (test)**: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
- Supply of the native token will be hard-capped
- Set gas fee config as low throughput (12 million gas per block)
- Use constant gas prices
- Disable further adjustments in transaction fee configuration
- Transaction fees are burned
- Enable interoperability with other blockchains
- Allow any user to deploy smart contracts, send transactions, and interact with your blockchain.

Next, CLI asks for the ChainID. You should provide your own ID. Check [chainlist.org](https://chainlist.org/) to see if the value you'd like is already in use.

```bash
✔ Subnet-EVM
creating Lux L1 test blockchain
Enter your Lux L1's ChainId. It can be any positive integer.
ChainId: 3333
```

Now, provide a symbol of your choice for the token of this EVM:

```bash
Select a symbol for your Lux L1's native token
Token symbol: TST
```

It's possible to end the process with Ctrl-C at any time.

At this point, CLI creates the specification of the new Lux L1 on disk, but isn't deployed yet.

Print the specification to disk by running the `describe` command:

```bash
lux blockchain describe testblockchain
```

```bash
+------------------------------------------------------------------+
|                          TESTBLOCKCHAIN                          |
+------------+-----------------------------------------------------+
| Name       | testblockchain                                      |
+------------+-----------------------------------------------------+
| VM ID      | tGBrM94jbkesczgqsL1UaxjrdxRQQobs3MZTNQ4GrfhzvpiE8   |
+------------+-----------------------------------------------------+
| VM Version | v0.6.12                                             |
+------------+-----------------------------------------------------+
| Validation | Proof Of Authority                                  |
+------------+-----------------------------------------------------+

+--------------------------+
|           TOKEN          |
+--------------+-----------+
| Token Name   | TST Token |
+--------------+-----------+
| Token Symbol | TST       |
+--------------+-----------+

+-----------------------------------------------------------------------------------------------------------------------------------+
|                                                      INITIAL TOKEN ALLOCATION                                                     |
+---------------------+------------------------------------------------------------------+--------------+---------------------------+
| DESCRIPTION         | ADDRESS AND PRIVATE KEY                                          | AMOUNT (TST) | AMOUNT (WEI)              |
+---------------------+------------------------------------------------------------------+--------------+---------------------------+
| Main funded account | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000      | 1000000000000000000000000 |
| ewoq                | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |              |                           |
+---------------------+------------------------------------------------------------------+--------------+---------------------------+

+-----------------------------------------------------------------------------------------------------------------+
|                                                 SMART CONTRACTS                                                 |
+-----------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION           | ADDRESS                                    | DEPLOYER                                   |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin           | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+-----------------------+--------------------------------------------+--------------------------------------------+
| PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy     | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

```


Deploy the Lux L1[​](#deploy-the-lux-l1 "Direct link to heading")
-----------------------------------------------------------------

<Callout title="Note">
To deploy the Lux L1, you will need some testnet LUX on the P-chain.
</Callout>

To deploy the new Lux L1, run:

```bash
lux blockchain deploy testblockchain
```

This is going to start a new prompt series.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Local Network
    Testnet
    Mainnet
```

This tutorial is about deploying to `Testnet`, so navigate with the arrow keys to `Testnet` and hit enter. The user is then asked to provide which private key to use for the deployment. Select a key to has Platform-Chain LUX to pay for transaction fees.

Also, this tutorial assumes that a node is up running, fully bootstrapped on `Testnet`, and runs from the **same** box.

```bash
✔ Testnet
Deploying [testblockchain] to Testnet
Use the arrow keys to navigate: ↓ ↑ → ←
? Which private key should be used to issue the transaction?:
    test
  ▸ mytestkey
```

Lux L1s require bootstrap validators during creation process. Lux CLI has enabled using local machine as a bootstrap validator on the blockchain.
This means that you don't have to to set up a remote server on a cloud service (e.g. AWS / GCP) to be a validator on the blockchain.

We will select `Yes` on using our local machine as a bootstrap validator. Note that since we need to sync our node with Testnet, this process will take around 3 minutes.

```bash
You can use your local machine as a bootstrap validator on the blockchain
This means that you don't have to to set up a remote server on a cloud service (e.g. AWS / GCP) to be a validator on the blockchain.
Use the arrow keys to navigate: ↓ ↑ → ←
? Do you want to use your local machine as a bootstrap validator?:
  ▸ Yes
    No
```

Well done. You have just created your own Lux L1 on `Testnet`.

You will be able to see information on the deployed L1 at the end of `lux blockchain deploy` command:

```bash
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | testblockchain                                     |
+--------------------+----------------------------------------------------+
| Subnet ID          | 2cNuyBhvAd4jH5bFSGndezhB66Z4UHYAsLCMGoCpvhXVhrZfgd |
+--------------------+----------------------------------------------------+
| VM ID              | qcvkEX1zWSz7PtGd7CKvPRBqLVTzA7qyMPvkh5NMDWkuhrcCu  |
+--------------------+----------------------------------------------------+
| Blockchain ID      | 2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx |
+--------------------+                                                    +
| Platform-Chain TXID       |                                                    |
+--------------------+----------------------------------------------------+
```

To get your new Lux L1 information, visit the [Lux L1 Explorer](https://subnets-test.lux.network/). The search best works by blockchain ID, so in this example, enter `2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx` into the search box and you should see your shiny new blockchain information.

Add a Validator[​](#add-a-validator "Direct link to heading")
-------------------------------------------------------------

Before proceeding to add a validator to our Lux L1, we will need to have the validator's NodeID, BLS public key and proof of possession. These can be obtained by ssh into the node itself and run the `getNodeID` API specified [here](/docs/rpcs/other/info-rpc#infogetnodeid).

To add a validator to an Lux L1, the owner of the key that acts as the controller of `ValidatorManager` contract specified in `lux blockchain create` command above run:

```bash
lux blockchain addValidator testblockchain
```

Choose `Testnet`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Testnet
```

You will need to specify which private key to use to pay for the transaction fees:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
?  Which key should be used to pay for transaction fees on Platform-Chain?:
    test
  ▸ mytestkey
```

Now enter the **NodeID** of the new validator to be added.

```bash
What is the NodeID of the validator you'd like to whitelist?: NodeID-BFa1paAAAAAAAAAAAAAAAAAAAAQGjPhUy
```

Next, enter the node's BLS public key and proof of possession.

Now, enter the amount of LUX that you would like to allocate to the new validator.

The validator's balance is used to pay for continuous fee to the Platform-Chain. When this Balance reaches 0, the validator will be considered inactive and will no longer participate in validating the L1.

1 LUX should last the validator about a month.

```bash
What balance would you like to assign to the validator (in LUX)?: 1
```

Next, select a key that will receive the leftover LUX if the validator is removed from the L1:

```bash
 Which stored key should be used be set as a change owner for leftover LUX?:
    test
  ▸ mytestkey
```

Next, select a key that can remove the validator:

```bash
? Which stored key should be used be able to disable the validator using Platform-Chain transactions?:
    test
  ▸ mytestkey
```

By the end of the command, you would have successfully added a new validator to the Lux L1 on Testnet Testnet!

Appendix[​](#appendix "Direct link to heading")
-----------------------------------------------

### Connect with Core[​](#connect-with-core "Direct link to heading")

To connect Core (or MetaMask) with your blockchain on the new Lux L1 running on your local computer, you can add a new network on your Core wallet with the following values:

```bash
- Network Name: testblockchain
- RPC URL: [http://127.0.0.1:9650/ext/bc/2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx/rpc]
- Chain ID: 3333
- Symbol: TST
```


# On Lux Mainnet (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-mainnet)

---
title: On Lux Mainnet
description: Deploy an Lux L1 to Lux Mainnet
---
<Callout type="warn">
Deploying an Lux L1 to Mainnet has many risks. Doing so safely requires a laser focus on security. This tutorial does its best to point out common pitfalls, but there may be other risks not discussed here.

This tutorial is an educational resource and provides no guarantees that following it results in a secure deployment. Additionally, this tutorial takes some shortcuts that aid the understanding of the deployment process at the expense of security. The text highlights these shortcuts and they shouldn't be used for a production deployment.
</Callout>

After managing a successful Lux L1 deployment on the `Testnet Testnet`, you're ready to deploy your Lux L1 on Mainnet. If you haven't done so, first [Deploy an Lux L1 on Testnet](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet).

This tutorial shows how to do the following on `Mainnet`.

- Deploy an Lux L1.
- Add a node as a validator to the Lux L1.

<Callout title="Note">
All IDs in this article are for illustration purposes only. They are guaranteed to be different in your own run-through of this tutorial.
</Callout>

## Prerequisites

- An Lux node running and [fully bootstrapped](/docs/nodes) on `Mainnet`
- [Lux-CLI is installed](/docs/tooling/lux-cli) on each validator node's box
- A [Ledger](https://www.ledger.com/) device
- You've [created an Lux L1 configuration](/docs/tooling/lux-cli#create-your-lux-l1-configuration) and fully tested a [Testnet Testnet Lux L1 deployment](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet)

### Setting up Your Ledger[​](#setting-up-your-ledger "Direct link to heading")

In the interest of security, all Lux-CLI `Mainnet` operations require the use of a connected Ledger device. You must unlock your Ledger and run the Lux App. See [How to Use Ledger](https://support.lux.network/en/articles/6150237-how-to-use-a-ledger-nano-s-or-nano-x-with-lux) for help getting set up.

Ledger devices support TX signing for any address inside a sequence automatically generated by the device.

By default, Lux-CLI uses the first address of the derivation, and that address needs funds to issue the TXs to create the Lux L1 and add validators.

To get the first `Mainnet` address of your Ledger device, first make sure it is connected, unblocked, and running the Lux app. Then execute the `key list` command:

```bash
lux key list --ledger 0 --mainnet
```

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | Platform-Chain (Bech32 format) | P-lux1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j |      11 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

The command prints the Platform-Chain address for `Mainnet`, `P-lux1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j`, and its balance.

<Callout title="Note">
You can use the `key list` command to get any Ledger address in the derivation sequence by changing the index parameter from `0` to the one desired, or to a list of them (for example: `2`, or `0,4,7`). Also, you can ask for addresses on `Mainnet` with the `--mainnet` parameter, and local networks with the `--local` parameter.
</Callout>

#### Funding the Ledger[​](#funding-the-ledger "Direct link to heading")

A new Ledger device has no funds on the addresses it controls. You'll need to send funds to it by exporting them from LUExchange-Chain to the Platform-Chain using [Core web](https://core.app/) connected to [Core extension](https://core.app/).

You can load the Ledger's LUExchange-Chain address in Core extension, or load in a different private key to [Core extension](https://core.app/), and then connect to Core web .

You can move test funds from the LUExchange-Chain to the Platform-Chain by clicking Stake on Core web , then Cross-Chain Transfer (find more details on [this tutorial](https://support.lux.network/en/articles/8133713-core-web-how-do-i-make-cross-chain-transfers-in-core-stake)).

Deploy the Lux L1[​](#deploy-the-lux-l1 "Direct link to heading")
-----------------------------------------------------------------

<Callout title="Note">
To deploy the Lux L1, you will need some LUX on the Platform-Chain.
</Callout>

For our Testnet example, we used our local machine as a bootstrap validator. However, since bootstrapping a node to Mainnet will take several hours,
we will use an Lux node set up on an AWS server that is already bootstrapped to Mainnet for this example.

To check if the Lux node is done bootstrapping, ssh into the node and call [`info.isBootstrapped`](/docs/rpcs/other/info-rpc#infoisbootstrapped) by copying and pasting the following command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"P"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If this returns `true`, it means that the chain is bootstrapped and we will proceed to deploying our L1.

We will need to have the Lux node's NodeID, BLS public key and proof of possession. These can be obtained by ssh into the node itself and run the `getNodeID` API specified [here](/docs/rpcs/other/info-rpc#infogetnodeid)

To deploy the new Lux L1, with your Ledger unlocked and running the Lux app, run:

```bash
lux blockchain deploy testblockchain
```

This is going to start a new prompt series.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
    Local Network
    Testnet
  ▸ Mainnet
```

This tutorial is about deploying to `Mainnet`, so navigate with the arrow keys to `Mainnet` and hit enter. The user is then asked to provide which private key to use for the deployment. Select a key to has Platform-Chain LUX to pay for transaction fees.

```bash
✔ Mainnet
Deploying [testblockchain] to Mainnet
```

After that, CLI shows the `Mainnet` Ledger address used to fund the deployment:

```bash
Ledger address: P-lux1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j
```

Select `No` to using local machine as a bootstrap validator on the blockchain.

```bash
You can use your local machine as a bootstrap validator on the blockchain
This means that you don't have to to set up a remote server on a cloud service (e.g. AWS / GCP) to be a validator on the blockchain.
Use the arrow keys to navigate: ↓ ↑ → ←
? Do you want to use your local machine as a bootstrap validator?:
    Yes
  ▸ No
```

Enter 1 as the number of bootstrap validators we will be setting up.

```bash
✔ No
✗ How many bootstrap validators do you want to set up?: 1
```

Select `Yes` since we have already set up our Lux Node on AWS.

```bash
If you have set up your own Lux Nodes, you can provide the Node ID and BLS Key from those nodes in the next step.
Otherwise, we will generate new Node IDs and BLS Key for you.
Use the arrow keys to navigate: ↓ ↑ → ←
? Have you set up your own Lux Nodes?:
  ▸ Yes
    No
```

Next, we will enter the node's Node-ID:

```bash
Getting info for bootstrap validator 1
✗ What is the NodeID of the node you want to add as bootstrap validator?: █
```

And BLS public key and proof of possession:

```bash
Next, we need the public key and proof of possession of the node's BLS
Check https://build.lux.network/docs/rpcs/other/info-rpc#infogetnodeid for instructions on calling info.getNodeID API
✗ What is the node's BLS public key?: █
```

Next, the CLI generates a CreateSubnet TX to create the Subnet and asks the user to sign it by using the Ledger.

```bash
*** Please sign Lux L1 creation hash on the ledger device ***
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

If the Ledger doesn't have enough funds, the user may see an error message:

```bash
*** Please sign Lux L1 creation hash on the ledger device ***
Error: insufficient funds: provided UTXOs need 1000000000 more units of asset "U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK"
```

If successful, the CLI next asks you to sign a CreateChain Tx. Once CreateChain Tx is signed, it will then ask you to sign ConvertSubnetToL1 Tx.

Well done. You have just created your own Lux L1 on `Mainnet`.

You will be able to see information on the deployed L1 at the end of `lux blockchain deploy` command:

```bash
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | testblockchain                                     |
+--------------------+----------------------------------------------------+
| Subnet ID          | 2cNuyBhvAd4jH5bFSGndezhB66Z4UHYAsLCMGoCpvhXVhrZfgd |
+--------------------+----------------------------------------------------+
| VM ID              | qcvkEX1zWSz7PtGd7CKvPRBqLVTzA7qyMPvkh5NMDWkuhrcCu  |
+--------------------+----------------------------------------------------+
| Blockchain ID      | 2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx |
+--------------------+                                                    +
| Platform-Chain TXID       |                                                    |
+--------------------+----------------------------------------------------+
```

To get your new Lux L1 information, there are two options:

- Call `lux blockchain describe` command or
- Visit the [Lux L1 Explorer](https://subnets-test.lux.network/). The search best works by blockchain ID, so in this example, enter `2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx` into the search box and you should see your shiny new blockchain information.

Add a Validator[​](#add-a-validator "Direct link to heading")
-------------------------------------------------------------

Before proceeding to add a validator to our Lux L1, we will need to have the validator's NodeID, BLS public key and proof of possession. These can be obtained by ssh into the node itself and run the `getNodeID` API specified [here](/docs/rpcs/other/info-rpc#infogetnodeid)

To add a validator to an Lux L1, the owner of the key that acts as the controller of ValidatorManager contract specified in `lux blockchain create` command above run:

```bash
lux blockchain addValidator testblockchain
```

Choose `Mainnet`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Mainnet
```

The CLI will show the Ledger address that will be used to pay for add validator tx:

```bash
Ledger address: P-lux1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j
```

Now enter the **NodeID** of the new validator to be added.

```bash
What is the NodeID of the validator you'd like to whitelist?: NodeID-BFa1paAAAAAAAAAAAAAAAAAAAAQGjPhUy
```

Next, enter the node's BLS public key and proof of possession.

Now, enter the amount of LUX that you would like to allocate to the new validator.

The validator's balance is used to pay for continuous fee to the Platform-Chain. When this Balance reaches 0, the validator will be considered inactive and will no longer participate in validating the L1.

1 LUX should last the validator about a month.

```bash
What balance would you like to assign to the validator (in LUX)?: 1
```

Sign the addValidatorTx with your Ledger:

```bash
*** Please sign add validator hash on the ledger device ***
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

This might take a couple of seconds. After, it prints:

```bash
Transaction successful, transaction ID: r3tJ4Wr2CWA8AaticmFrKdKgAs5AhW2wwWTaQHRBZKwJhsXzb
```

This means the node is now a validator on the given Lux L1 on `Mainnet`!

Going Live[​](#going-live "Direct link to heading")
---------------------------------------------------

For the safety of your validators, you should setup dedicated API nodes to process transactions, but for test purposes, you can issue transactions directly to one of your validator's RPC interface.

# On Production Infra (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-production-infra)

---
title: On Production Infra
description: Learn how to deploy an Lux L1 on production infrastructure.
---

After architecting your Lux L1 environment on the [local machine](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-locally), proving the design and testing it out on [the Testnet Testnet](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet), eventually you will need to deploy your Lux L1 to production environment.

Running an Lux L1 in production is much more involved than local and Testnet deploys, as your Lux L1 will have to take care of real world usage, maintaining uptime, upgrades and all of that in a potentially adversarial environment. The purpose of this document is to point out a set of general considerations and propose potential solutions to them.

The architecture of the environment your particular Lux L1 will use will be greatly influenced by the type of load and activity your Lux L1 is designed to support so your solution will most likely differ from what we propose here. Still, it might be useful to follow along, to build up the intuition for the type of questions you will need to consider.

Node Setup[​](#node-setup "Direct link to heading")
---------------------------------------------------

Lux nodes are essential elements for running your Lux L1 in production. At a minimum, your Lux L1 will need validator nodes, potentially also nodes that act as RPC servers, indexers or explorers. Running a node is basically running an instance of [LuxGo](/docs/nodes) on a server.

### Server OS[​](#server-os "Direct link to heading")

Although LuxGo can run on a MacOS or a Windows computer, we strongly recommend running nodes on computers running Linux as they are designed specifically for server loads and all the tools and utilities needed for administering a server are native to Linux.

### Hardware Specification[​](#hardware-specification "Direct link to heading")

For running LuxGo as a validator on the Primary Network the recommended configuration is as follows:

- CPU: Equivalent of 8 AWS vCPU
- RAM: 16 GiB
- Storage: 1 TiB with at least 3000 IOPS
- OS: Ubuntu 20.04
- Network: Reliable IPv4 or IPv6 network connection, with an open public port

That is the configuration sufficient for running a Primary Network node. Any resource requirements for your Lux L1 come on top of this, so you should not go below this configuration, but may need to step up the specification if you expect your Lux L1 to handle a significant amount of transactions.

Be sure to set up monitoring of resource consumption for your nodes because resource exhaustion may cause your node to slow down or even halt, which may severely impact your Lux L1 negatively.

### Server Location[​](#server-location "Direct link to heading")

You can run a node on a physical computer that you own and run, or on a cloud instance. Although running on your own HW may seem like a good idea, unless you have a sizeable DevOps 24/7 staff we recommend using cloud service providers as they generally provide reliable computing resources that you can count on to be properly maintained and monitored.

#### Local Servers[​](#local-servers "Direct link to heading")

If you plan on running nodes on your own hardware, make sure they satisfy the minimum HW specification as outlined earlier. Pay close attention to proper networking setup, making sure the p2p port (9651) is accessible and public IP properly configured on the node. Make sure the node is connected to the network physically (not over Wi-Fi), and that the router is powerful enough to handle a couple of thousands of persistent TCP connections and that network bandwidth can accommodate at least 5Mbps of steady upstream and downstream network traffic.

When installing the LuxGo node on the machines, unless you have a dedicated DevOps staff that will take care of node setup and configuration, we recommend using the [installer script](/docs/nodes/run-a-node/using-install-script/installing-lux-go) to set up the nodes. It will abstract most of the setup process for you, set up the node as a system service and will enable easy node upgrades.

#### Cloud Providers[​](#cloud-providers "Direct link to heading")

There are a number of different cloud providers. We have documents that show how to set up a node on the most popular ones:

- [Amazon Web Services](/docs/nodes/run-a-node/on-third-party-services/amazon-web-services)
- [Azure](/docs/nodes/run-a-node/on-third-party-services/microsoft-azure)
- [Google Cloud Platform](/docs/nodes/run-a-node/on-third-party-services/google-cloud)

There is a whole range of other cloud providers that may offer lower prices or better deals for your particular needs, so it makes sense to shop around.

Once you decide on a provider (or providers), if they offer instances in multiple data centers, it makes sense to spread the nodes geographically since that provides a better resilience and stability against outages.

### Number of Validators[​](#number-of-validators "Direct link to heading")

Number of validators on an Lux L1 is a crucial decision you need to make. For stability and decentralization, you should strive to have as many validators as possible.

For stability reasons our recommendation is to have **at least** 5 full validators on your Lux L1. If you have less than 5 validators your Lux L1 liveness will be at risk whenever a single validator goes offline, and if you have less than 4 even one offline node will halt your Lux L1.

You should be aware that 5 is the minimum we recommend. But, from a decentralization standpoint having more validators is always better as it increases the stability of your Lux L1 and makes it more resilient to both technical failures and adversarial action. In a nutshell: run as many Lux L1 validators as you can.

Considering that at times you will have to take nodes offline, for routine maintenance (at least for node upgrades which happen with some regularity) or unscheduled outages and failures you need to be able to routinely handle at least one node being offline without your Lux L1 performance degrading.

### Node Bootstrap[​](#node-bootstrap "Direct link to heading")

Once you set up the server and install LuxGo on them, nodes will need to bootstrap (sync with the network). This is a lengthy process, as the nodes need to catch up and replay all the network activity since the genesis up to the present moment. Full bootstrap on a node can take more than a week, but there are ways to shorten that process, depending on your circumstances.

#### State Sync[​](#state-sync "Direct link to heading")

If the nodes you will be running as validators don't need to have the full transaction history, then you can use [state sync](/docs/nodes/chain-configs/primary-network/c-chain#state-sync-enabled). With this flag enabled, instead of replaying the whole history to get to the current state, nodes simply download only the current state from other network peers, shortening the bootstrap process from multiple days to a couple of hours. If the nodes will be used for Lux L1 validation exclusively, you can use the state sync without any issues. Currently, state sync is only available for the LUExchange-Chain, but since the bulk of the transactions on the platform happen there it still has a significant impact on the speed of bootstrapping.

#### Database Copy[​](#database-copy "Direct link to heading")

Good way to cut down on bootstrap times on multiple nodes is database copy. Database is identical across nodes, and as such can safely be copied from one node to another. Just make sure to that the node is not running during the copy process, as that can result in a corrupted database. Database copy procedure is explained in detail [here](/docs/nodes/maintain/backup-restore#database).

Please make sure you don't reuse any node's NodeID by accident, especially don't restore another node's ID, see [here](/docs/nodes/maintain/backup-restore#nodeid) for details. Each node must has its own unique NodeID, otherwise, the nodes sharing the same ID will not behave correctly, which will impact your validator's uptime, thus staking rewards, and the stability of your Lux L1.

Lux L1 Deploy[​](#lux-l1-deploy "Direct link to heading")
---------------------------------------------------------

Once you have the nodes set up you are ready to deploy the actual Lux L1. Right now, the recommended tool to do that is [Lux-CLI](https://github.com/luxfi/lux-cli).

Instructions for deployment by Lux-CLI can be found [here](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-mainnet).

### Ledger Hardware Wallet[​](#ledger-hw-wallet "Direct link to heading")

When creating the Lux L1, you will be required to have a private key that will control the administrative functions of the Lux L1 (adding validators, managing the configuration). Needless to say, whoever has this private key has complete control over the Lux L1 and the way it runs. Therefore, protecting that key is of the utmost operational importance. Which is why we strongly recommend using a hardware wallet such as a [Ledger HW Wallet](https://www.ledger.com/) to store and access that private key.

General instruction on how to use a Ledger device with Lux can be found [here](https://support.lux.network/en/articles/6150237-how-to-use-a-ledger-nano-s-or-nano-x-with-lux).

### Genesis File[​](#genesis-file "Direct link to heading")

The structure that defines the most important parameters in an Lux L1 is found in the genesis file, which is a `json` formatted, human-readable file. Describing the contents and the options available in the genesis file is beyond the scope of this document, and if you're ready to deploy your Lux L1 to production you probably have it mapped out already.

If you want to review, we have a description of the genesis file in our document on [customizing EVM Lux L1s](/docs/lux-l1s/evm-configuration/customize-lux-l1).

Validator Configuration[​](#validator-configuration "Direct link to heading")
-----------------------------------------------------------------------------

Running nodes as Lux L1 validators warrants some additional considerations, above those when running a regular node or a Primary Network-only validator.

### Joining an Lux L1[​](#joining-a-lux-l1 "Direct link to heading")

For a node to join an Lux L1, there are two prerequisites:

- Primary Network validation
- Lux L1 tracking

Primary Network validation means that a node cannot join an Lux L1 as a validator before becoming a validator on the Primary Network itself. So, after you add the node to the validator set on the Primary Network, node can join an Lux L1. Of course, this is valid only for Lux L1 validators, if you need a non-validating Lux L1 node, then the node doesn't need to be a validator at all.

To have a node start syncing the Lux L1, you need to add the `--track-subnets` command line option, or `track-subnets` key to the node config file (found at `.luxgo/configs/node.json` for installer-script created nodes). A single node can sync multiple Layer 1s, so you can add them as a comma-separated list of Lux L1 IDs (SubnetID).

An example of a node config syncing two Lux L1s:

```json
{
  "public-ip-resolution-service": "opendns",
  "http-host": "",
  "track-subnets": "28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY,Ai42MkKqk8yjXFCpoHXw7rdTWSHiKEMqh5h8gbxwjgkCUfkrk"
}
```

But that is not all. Besides tracking the SubnetID, the node also needs to have the plugin that contains the VM instance the blockchain in the Lux L1 will run. You should have already been through that on Testnet and Testnet, but for a refresher, you can refer to [this tutorial](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet).

So, name the VM plugin binary as the `VMID` of the Lux L1 chain and place it in the `plugins` directory where the node binary is (for installer-script created nodes that would be `~/lux-node/plugins/`).

### Lux L1 Bootstrapping[​](#lux-l1-bootstrapping "Direct link to heading")

After you have tracked the Lux L1 and placed the VM binary in the correct directory, your node is ready to start syncing with the Lux L1. Restart the node and monitor the log output. You should notice something similar to:

```bash
Jul 30 18:26:31 node-testnet luxgo[1728308]: [07-30|18:26:31.422] INFO chains/manager.go:262 creating chain:
Jul 30 18:26:31 node-testnet luxgo[1728308]:     ID: 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt
Jul 30 18:26:31 node-testnet luxgo[1728308]:     VMID:srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
```

That means the node has detected the Lux L1, and is attempting to initialize it and start bootstrapping the Lux L1. It might take some time (if there are already transactions on the Lux L1), and eventually it will finish the bootstrap with a message like:

```bash
Jul 30 18:27:21 node-testnet luxgo[1728308]: [07-30|18:27:21.055] INFO <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain> snowman/transitive.go:333 consensus starting with J5wjmotMCrM2DKxeBTBPfwgCPpvsjtuqWNozLog2TomTjSuGK as the last accepted block
```

That means the node has successfully bootstrapped the Lux L1 and is now in sync. If the node is one of the validators, it will start validating any transactions that get posted to the Lux L1.

### Monitoring[​](#monitoring "Direct link to heading")

If you want to inspect the process of Lux L1 syncing, you can use the RPC call to check for the [blockchain status](/docs/rpcs/p-chain#platformgetblockchainstatus).

For a more in-depth look into Lux L1 operation, check out the blockchain log. By default, the log can be found in `~/.luxgo/logs/ChainID.log` where you replace the `ChainID` with the actual ID of the blockchain in your Lux L1.

For an even more thorough (and pretty!) insight into how the node and the Lux L1 is behaving, you can install the Prometheus+Grafana monitoring system with the custom dashboards for the regular node operation, as well as a dedicated dashboard for Lux L1 data. Check out the [tutorial](/docs/nodes/maintain/monitoring) for information on how to set it up.

### Managing Validation[​](#managing-validation "Direct link to heading")

On Lux all validations are limited in time and can range from two weeks up to one year. Furthermore, Lux L1 validations are always a subset of the Primary Network validation period (must be shorter or the same). That means that periodically your validators will expire and you will need to submit a new validation transaction for both the Primary Network and your Lux L1.

Unless managed properly and in a timely manner, that can be disruptive for your Lux L1 (if all validators expire at the same time your Lux L1 will halt). To avoid that, keep notes on when a particular validation is set to expire and be ready to renew it as soon as possible. Also, when initially setting up the nodes, make sure to stagger the validator expiry so they don't all expire on the same date. Setting end dates at least a day apart is a good practice, as well as setting reminders for each expiry.

Conclusion[​](#conclusion "Direct link to heading")
---------------------------------------------------

Hopefully, by reading this document you have a better picture of the requirements and considerations you need to make when deploying your Lux L1 to production and you are now better prepared to launch your Lux L1 successfully.

Keep in mind, running an Lux L1 in production is not a one-and-done kind of situation, it is in fact running a fleet of servers 24/7. And as with any real time service, you should have a robust logging, monitoring and alerting systems to constantly check the nodes and Lux L1 health and alert you if anything out of the ordinary happens.

If you have any questions, doubts or would like to chat, please check out our [Discord server](https://discord.gg/lux/), where we host a dedicated `#subnet-chat` channel dedicated to talking about all things Lux L1.


# With Custom VM (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-with-custom-vm)

---
title: With Custom VM
description: Learn how to create an Lux L1 with a custom virtual machine and deploy it locally.
---

This tutorial walks through the process of creating an Lux L1 with a custom virtual machine and deploying it locally. Although the tutorial uses a fork of Subnet-EVM as an example, you can extend its lessons to support any custom VM binary.

Fork Subnet-EVM[​](#fork-subnet-evm "Direct link to heading")
-------------------------------------------------------------

Instead of building a custom VM from scratch, this tutorial starts with forking Subnet-EVM.

### Clone Subnet-EVM[​](#clone-subnet-evm "Direct link to heading")

First off, clone the Subnet-EVM repository into a directory of your choosing.

```bash
git clone https://github.com/luxfi/subnet-evm.git
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:luxfi/subnet-evm.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

### Modify and Build Subnet-EVM[​](#modify-and-build-subnet-evm "Direct link to heading")

To prove you're running your custom binary and not the stock Subnet-EVM included with Lux-CLI, you need to modify the Subnet-EVM binary by making a minor change.

Navigate to the directory you cloned Subnet-EVM into and generate a new commit:

```bash
git commit -a --allow-empty -m "custom vm commit"
```

Take note of the new commit hash:

```bash
git rev-parse HEAD
c0fe6506a40da466285f37dd0d3c044f494cce32
```

In this case, `c0fe6506a40da466285f37dd0d3c044f494cce32`.

Now build your custom binary by running:

```bash
./scripts/build.sh custom_vm.bin
```

This command builds the binary and saves it at `./custom_vm.bin`.

### Create a Custom Genesis[​](#create-a-custom-genesis "Direct link to heading")

To start a VM, you need to provide a genesis file. Here is a basic Subnet-EVM genesis that's compatible with your custom VM.
This genesis includes the PoA Validator Manager, a Transparent Proxy and Proxy Admin as predeployed contracts.

`0c0deba5e0000000000000000000000000000000` is the ValidatorManager address.
`0feedc0de0000000000000000000000000000000` is the Transparent Proxy address.
`c0ffee1234567890abcdef1234567890abcdef34` is the Proxy Admin contract.

These proxy contracts are from [OpenZeppelin v4.9](https://github.com/OpenZeppelin/openzeppelin-contracts/tree/release-v4.9/contracts/proxy/transparent)
You can add your own predeployed contracts by running `forge build` and collecting the `deployedBytecode` output from `out/MyContract.sol`


```json
{
    "config": {
        "berlinBlock": 0,
        "byzantiumBlock": 0,
        "chainId": 1,
        "constantinopleBlock": 0,
        "eip150Block": 0,
        "eip155Block": 0,
        "eip158Block": 0,
        "feeConfig": {
            "gasLimit": 12000000,
            "targetBlockRate": 2,
            "minBaseFee": 25000000000,
            "targetGas": 60000000,
            "baseFeeChangeDenominator": 36,
            "minBlockGasCost": 0,
            "maxBlockGasCost": 1000000,
            "blockGasCostStep": 200000
        },
        "homesteadBlock": 0,
        "istanbulBlock": 0,
        "londonBlock": 0,
        "muirGlacierBlock": 0,
        "petersburgBlock": 0,
        "warpConfig": {
            "blockTimestamp": 1736356569,
            "quorumNumerator": 67,
            "requirePrimaryNetworkSigners": true
        }
    },
    "nonce": "0x0",
    "timestamp": "0x677eb2d9",
    "extraData": "0x",
    "gasLimit": "0xb71b00",
    "difficulty": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x0000000000000000000000000000000000000000",
    "alloc": {
        "0c0deba5e0000000000000000000000000000000": {
            "code": "0x608060405234801561000f575f80fd5b5060043610610132575f3560e01c80639ba96b86116100b4578063c974d1b611610079578063c974d1b6146102a7578063d588c18f146102af578063d5f20ff6146102c2578063df93d8de146102e2578063f2fde38b146102ec578063fd7ac5e7146102ff575f80fd5b80639ba96b861461024c578063a3a65e481461025f578063b771b3bc14610272578063bc5fbfec14610280578063bee0a03f14610294575f80fd5b8063715018a6116100fa578063715018a6146101be578063732214f8146101c65780638280a25a146101db5780638da5cb5b146101f557806397fb70d414610239575f80fd5b80630322ed981461013657806320d91b7a1461014b578063467ef06f1461015e57806360305d621461017157806366435abf14610193575b5f80fd5b610149610144366004612b01565b610312565b005b610149610159366004612b30565b610529565b61014961016c366004612b7e565b610a15565b610179601481565b60405163ffffffff90911681526020015b60405180910390f35b6101a66101a1366004612b01565b610a23565b6040516001600160401b03909116815260200161018a565b610149610a37565b6101cd5f81565b60405190815260200161018a565b6101e3603081565b60405160ff909116815260200161018a565b7f9016d09d72d40fdae2fd8ceac6b6234c7706214fd39c1cd1e609a0528c199300546001600160a01b03165b6040516001600160a01b03909116815260200161018a565b610149610247366004612b01565b610a4a565b6101cd61025a366004612bad565b610a5f565b61014961026d366004612b7e565b610a7b565b6102216005600160991b0181565b6101cd5f8051602061370d83398151915281565b6101496102a2366004612b01565b610c04565b6101e3601481565b6101496102bd366004612c06565b610d41565b6102d56102d0366004612b01565b610e4f565b60405161018a9190612cc3565b6101a66202a30081565b6101496102fa366004612d43565b610f9e565b6101cd61030d366004612d65565b610fdb565b5f8181525f8051602061372d8339815191526020526040808220815160e0810190925280545f8051602061370d83398151915293929190829060ff16600581111561035f5761035f612c42565b600581111561037057610370612c42565b815260200160018201805461038490612dd0565b80601f01602080910402602001604051908101604052809291908181526020018280546103b090612dd0565b80156103fb5780601f106103d2576101008083540402835291602001916103fb565b820191905f5260205f20905b8154815290600101906020018083116103de57829003601f168201915b505050918352505060028201546001600160401b038082166020840152600160401b820481166040840152600160801b820481166060840152600160c01b909104811660808301526003928301541660a0909101529091508151600581111561046657610466612c42565b146104a2575f8381526007830160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b60405180910390fd5b6005600160991b016001600160a01b031663ee5b48eb6104c78584606001515f611036565b6040518263ffffffff1660e01b81526004016104e39190612e16565b6020604051808303815f875af11580156104ff573d5f803e3d5ffd5b505050506040513d601f19601f820116820180604052508101906105239190612e28565b50505050565b7fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb09545f8051602061370d8339815191529060ff161561057b57604051637fab81e560e01b815260040160405180910390fd5b6005600160991b016001600160a01b0316634213cf786040518163ffffffff1660e01b8152600401602060405180830381865afa1580156105be573d5f803e3d5ffd5b505050506040513d601f19601f820116820180604052508101906105e29190612e28565b83602001351461060b576040516372b0a7e760e11b815260208401356004820152602401610499565b3061061c6060850160408601612d43565b6001600160a01b03161461065f5761063a6060840160408501612d43565b604051632f88120d60e21b81526001600160a01b039091166004820152602401610499565b5f61066d6060850185612e3f565b905090505f805b828163ffffffff161015610955575f6106906060880188612e3f565b8363ffffffff168181106106a6576106a6612e84565b90506020028101906106b89190612e98565b6106c190612fbc565b80516040519192505f9160088801916106d991613035565b9081526020016040518091039020541461070957805160405163a41f772f60e01b81526104999190600401612e16565b5f6002885f01358460405160200161073892919091825260e01b6001600160e01b031916602082015260240190565b60408051601f198184030181529082905261075291613035565b602060405180830381855afa15801561076d573d5f803e3d5ffd5b5050506040513d601f19601f820116820180604052508101906107909190612e28565b90508086600801835f01516040516107a89190613035565b90815260408051602092819003830181209390935560e0830181526002835284518284015284810180516001600160401b03908116858401525f60608601819052915181166080860152421660a085015260c0840181905284815260078a01909252902081518154829060ff1916600183600581111561082a5761082a612c42565b0217905550602082015160018201906108439082613091565b506040828101516002830180546060860151608087015160a08801516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909301516003909201805467ffffffffffffffff1916928416929092179091558301516108e8911685613164565b82516040519195506108f991613035565b60408051918290038220908401516001600160401b031682529082907f9d47fef9da077661546e646d61830bfcbda90506c2e5eed38195e82c4eb1cbdf9060200160405180910390a350508061094e90613177565b9050610674565b50600483018190555f61097361096a86611085565b6040015161119b565b90505f61097f87611328565b90505f6002826040516109929190613035565b602060405180830381855afa1580156109ad573d5f803e3d5ffd5b5050506040513d601f19601f820116820180604052508101906109d09190612e28565b90508281146109fc57604051631872fc8d60e01b81526004810182905260248101849052604401610499565b5050506009909201805460ff1916600117905550505050565b610a1e81611561565b505050565b5f610a2d82610e4f565b6080015192915050565b610a3f61189f565b610a485f6118fa565b565b610a5261189f565b610a5b8161196a565b5050565b5f610a6861189f565b610a728383611c4e565b90505b92915050565b5f8051602061370d8339815191525f80610aa0610a9785611085565b604001516121a1565b9150915080610ac657604051632d07135360e01b81528115156004820152602401610499565b5f82815260068401602052604090208054610ae090612dd0565b90505f03610b045760405163089938b360e11b815260048101839052602401610499565b60015f83815260078501602052604090205460ff166005811115610b2a57610b2a612c42565b14610b5d575f8281526007840160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b5f8281526006840160205260408120610b7591612a75565b5f828152600784016020908152604091829020805460ff1916600290811782550180546001600160401b0342818116600160c01b026001600160c01b0390931692909217928390558451600160801b9093041682529181019190915283917ff8fd1c90fb9cfa2ca2358fdf5806b086ad43315d92b221c929efc7f105ce7568910160405180910390a250505050565b5f8181527fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb066020526040902080545f8051602061370d8339815191529190610c4b90612dd0565b90505f03610c6f5760405163089938b360e11b815260048101839052602401610499565b60015f83815260078301602052604090205460ff166005811115610c9557610c95612c42565b14610cc8575f8281526007820160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b5f82815260068201602052604090819020905163ee5b48eb60e01b81526005600160991b019163ee5b48eb91610d019190600401613199565b6020604051808303815f875af1158015610d1d573d5f803e3d5ffd5b505050506040513d601f19601f82011682018060405250810190610a1e9190612e28565b7ff0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a008054600160401b810460ff1615906001600160401b03165f81158015610d855750825b90505f826001600160401b03166001148015610da05750303b155b905081158015610dae575080155b15610dcc5760405163f92ee8a960e01b815260040160405180910390fd5b845467ffffffffffffffff191660011785558315610df657845460ff60401b1916600160401b1785555b610e00878761235d565b8315610e4657845460ff60401b19168555604051600181527fc7f505b2f371ae2175ee4913f4499e1f2633a7b5936321eed1cdaeb6115181d29060200160405180910390a15b50505050505050565b610e57612aac565b5f8281525f8051602061372d833981519152602052604090819020815160e0810190925280545f8051602061370d833981519152929190829060ff166005811115610ea457610ea4612c42565b6005811115610eb557610eb5612c42565b8152602001600182018054610ec990612dd0565b80601f0160208091040260200160405190810160405280929190818152602001828054610ef590612dd0565b8015610f405780601f10610f1757610100808354040283529160200191610f40565b820191905f5260205f20905b815481529060010190602001808311610f2357829003601f168201915b505050918352505060028201546001600160401b038082166020840152600160401b820481166040840152600160801b820481166060840152600160c01b9091048116608083015260039092015490911660a0909101529392505050565b610fa661189f565b6001600160a01b038116610fcf57604051631e4fbdf760e01b81525f6004820152602401610499565b610fd8816118fa565b50565b6040515f905f8051602061370d833981519152907fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb089061101e9086908690613223565b90815260200160405180910390205491505092915050565b604080515f6020820152600360e01b602282015260268101949094526001600160c01b031960c093841b811660468601529190921b16604e830152805180830360360181526056909201905290565b60408051606080820183525f8083526020830152918101919091526040516306f8253560e41b815263ffffffff831660048201525f9081906005600160991b0190636f825350906024015f60405180830381865afa1580156110e9573d5f803e3d5ffd5b505050506040513d5f823e601f3d908101601f191682016040526111109190810190613241565b915091508061113257604051636b2f19e960e01b815260040160405180910390fd5b815115611158578151604051636ba589a560e01b81526004810191909152602401610499565b60208201516001600160a01b031615611194576020820151604051624de75d60e31b81526001600160a01b039091166004820152602401610499565b5092915050565b5f81516026146111d057815160405163cc92daa160e01b815263ffffffff909116600482015260266024820152604401610499565b5f805b600281101561121f576111e7816001613313565b6111f2906008613326565b61ffff1684828151811061120857611208612e84565b016020015160f81c901b91909117906001016111d3565b5061ffff8116156112495760405163407b587360e01b815261ffff82166004820152602401610499565b5f805b60048110156112a457611260816003613313565b61126b906008613326565b63ffffffff168561127d836002613164565b8151811061128d5761128d612e84565b016020015160f81c901b919091179060010161124c565b5063ffffffff8116156112ca57604051635b60892f60e01b815260040160405180910390fd5b5f805b602081101561131f576112e181601f613313565b6112ec906008613326565b866112f8836006613164565b8151811061130857611308612e84565b016020015160f81c901b91909117906001016112cd565b50949350505050565b60605f8083356020850135601461134487870160408901612d43565b6113516060890189612e3f565b60405160f09790971b6001600160f01b0319166020880152602287019590955250604285019290925260e090811b6001600160e01b0319908116606286015260609290921b6bffffffffffffffffffffffff191660668501529190911b16607a820152607e0160405160208183030381529060405290505f5b6113d76060850185612e3f565b9050811015611194576113ed6060850185612e3f565b828181106113fd576113fd612e84565b905060200281019061140f9190612e98565b61141d90602081019061333d565b905060301461143f5760405163180ffa0d60e01b815260040160405180910390fd5b8161144d6060860186612e3f565b8381811061145d5761145d612e84565b905060200281019061146f9190612e98565b611479908061333d565b90506114886060870187612e3f565b8481811061149857611498612e84565b90506020028101906114aa9190612e98565b6114b4908061333d565b6114c16060890189612e3f565b868181106114d1576114d1612e84565b90506020028101906114e39190612e98565b6114f190602081019061333d565b6114fe60608b018b612e3f565b8881811061150e5761150e612e84565b90506020028101906115209190612e98565b61153190606081019060400161337f565b6040516020016115479796959493929190613398565b60408051601f1981840301815291905291506001016113ca565b5f61156a612aac565b5f8051602061370d8339815191525f80611586610a9787611085565b9150915080156115ad57604051632d07135360e01b81528115156004820152602401610499565b5f828152600784016020526040808220815160e081019092528054829060ff1660058111156115de576115de612c42565b60058111156115ef576115ef612c42565b815260200160018201805461160390612dd0565b80601f016020809104026020016040519081016040528092919081815260200182805461162f90612dd0565b801561167a5780601f106116515761010080835404028352916020019161167a565b820191905f5260205f20905b81548152906001019060200180831161165d57829003601f168201915b505050918352505060028201546001600160401b038082166020840152600160401b820481166040840152600160801b820481166060840152600160c01b909104811660808301526003928301541660a090910152909150815160058111156116e5576116e5612c42565b14158015611706575060018151600581111561170357611703612c42565b14155b1561172757805160405163170cc93360e21b81526104999190600401612e08565b60038151600581111561173c5761173c612c42565b0361174a576004815261174f565b600581525b8360080181602001516040516117659190613035565b90815260408051602092819003830190205f908190558581526007870190925290208151815483929190829060ff191660018360058111156117a9576117a9612c42565b0217905550602082015160018201906117c29082613091565b5060408201516002820180546060850151608086015160a08701516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909201516003909101805467ffffffffffffffff1916919092161790558051600581111561186857611868612c42565b60405184907f1c08e59656f1a18dc2da76826cdc52805c43e897a17c50faefb8ab3c1526cc16905f90a39196919550909350505050565b336118d17f9016d09d72d40fdae2fd8ceac6b6234c7706214fd39c1cd1e609a0528c199300546001600160a01b031690565b6001600160a01b031614610a485760405163118cdaa760e01b8152336004820152602401610499565b7f9016d09d72d40fdae2fd8ceac6b6234c7706214fd39c1cd1e609a0528c19930080546001600160a01b031981166001600160a01b03848116918217845560405192169182907f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0905f90a3505050565b611972612aac565b5f8281525f8051602061372d8339815191526020526040808220815160e0810190925280545f8051602061370d83398151915293929190829060ff1660058111156119bf576119bf612c42565b60058111156119d0576119d0612c42565b81526020016001820180546119e490612dd0565b80601f0160208091040260200160405190810160405280929190818152602001828054611a1090612dd0565b8015611a5b5780601f10611a3257610100808354040283529160200191611a5b565b820191905f5260205f20905b815481529060010190602001808311611a3e57829003601f168201915b50505091835250506002828101546001600160401b038082166020850152600160401b820481166040850152600160801b820481166060850152600160c01b9091048116608084015260039093015490921660a09091015290915081516005811115611ac957611ac9612c42565b14611afc575f8481526007830160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b60038152426001600160401b031660c08201525f84815260078301602052604090208151815483929190829060ff19166001836005811115611b4057611b40612c42565b021790555060208201516001820190611b599082613091565b5060408201516002820180546060850151608086015160a08701516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909201516003909101805467ffffffffffffffff1916919092161790555f611bf78582612377565b6080840151604080516001600160401b03909216825242602083015291935083925087917f13d58394cf269d48bcf927959a29a5ffee7c9924dafff8927ecdf3c48ffa7c67910160405180910390a3509392505050565b7fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb09545f9060ff16611c9257604051637fab81e560e01b815260040160405180910390fd5b5f8051602061370d83398151915242611cb1606086016040870161337f565b6001600160401b0316111580611ceb5750611ccf6202a30042613164565b611cdf606086016040870161337f565b6001600160401b031610155b15611d2557611d00606085016040860161337f565b604051635879da1360e11b81526001600160401b039091166004820152602401610499565b6030611d34602086018661333d565b905014611d6657611d48602085018561333d565b6040516326475b2f60e11b8152610499925060040190815260200190565b611d70848061333d565b90505f03611d9d57611d82848061333d565b604051633e08a12560e11b8152600401610499929190613401565b5f60088201611dac868061333d565b604051611dba929190613223565b90815260200160405180910390205414611df357611dd8848061333d565b60405163a41f772f60e01b8152600401610499929190613401565b611dfd835f6124ce565b6040805160e08101909152815481525f908190611f099060208101611e22898061333d565b8080601f0160208091040260200160405190810160405280939291908181526020018383808284375f92019190915250505090825250602090810190611e6a908a018a61333d565b8080601f0160208091040260200160405190810160405280939291908181526020018383808284375f92019190915250505090825250602001611eb360608a0160408b0161337f565b6001600160401b03168152602001611ece60608a018a61342f565b611ed790613443565b8152602001611ee960808a018a61342f565b611ef290613443565b8152602001876001600160401b03168152506126a8565b5f82815260068601602052604090209193509150611f278282613091565b508160088401611f37888061333d565b604051611f45929190613223565b9081526040519081900360200181209190915563ee5b48eb60e01b81525f906005600160991b019063ee5b48eb90611f81908590600401612e16565b6020604051808303815f875af1158015611f9d573d5f803e3d5ffd5b505050506040513d601f19601f82011682018060405250810190611fc19190612e28565b6040805160e081019091529091508060018152602001611fe1898061333d565b8080601f0160208091040260200160405190810160405280939291908181526020018383808284375f9201829052509385525050506001600160401b0389166020808401829052604080850184905260608501929092526080840183905260a0909301829052868252600788019092522081518154829060ff1916600183600581111561207057612070612c42565b0217905550602082015160018201906120899082613091565b5060408201516002820180546060850151608086015160a08701516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909201516003909101805467ffffffffffffffff19169190921617905580612127888061333d565b604051612135929190613223565b6040518091039020847fb77297e3befc691bfc864a81e241f83e2ef722b6e7becaa2ecec250c6d52b430898b6040016020810190612173919061337f565b604080516001600160401b0393841681529290911660208301520160405180910390a4509095945050505050565b5f8082516027146121d757825160405163cc92daa160e01b815263ffffffff909116600482015260276024820152604401610499565b5f805b6002811015612226576121ee816001613313565b6121f9906008613326565b61ffff1685828151811061220f5761220f612e84565b016020015160f81c901b91909117906001016121da565b5061ffff8116156122505760405163407b587360e01b815261ffff82166004820152602401610499565b5f805b60048110156122ab57612267816003613313565b612272906008613326565b63ffffffff1686612284836002613164565b8151811061229457612294612e84565b016020015160f81c901b9190911790600101612253565b5063ffffffff81166002146122d357604051635b60892f60e01b815260040160405180910390fd5b5f805b6020811015612328576122ea81601f613313565b6122f5906008613326565b87612301836006613164565b8151811061231157612311612e84565b016020015160f81c901b91909117906001016122d6565b505f8660268151811061233d5761233d612e84565b016020015191976001600160f81b03199092161515965090945050505050565b612365612895565b61236e826128de565b610a5b816128f7565b5f8281525f8051602061372d833981519152602052604081206002015481905f8051602061370d83398151915290600160801b90046001600160401b03166123bf85826124ce565b5f6123c987612908565b5f8881526007850160205260408120600201805467ffffffffffffffff60801b1916600160801b6001600160401b038b16021790559091506005600160991b0163ee5b48eb6124198a858b611036565b6040518263ffffffff1660e01b81526004016124359190612e16565b6020604051808303815f875af1158015612451573d5f803e3d5ffd5b505050506040513d601f19601f820116820180604052508101906124759190612e28565b604080516001600160401b038a811682526020820184905282519394508516928b927f07de5ff35a674a8005e661f3333c907ca6333462808762d19dc7b3abb1a8c1df928290030190a3909450925050505b9250929050565b5f8051602061370d8339815191525f6001600160401b038084169085161115612502576124fb838561350a565b905061250f565b61250c848461350a565b90505b6040805160808101825260028401548082526003850154602083015260048501549282019290925260058401546001600160401b031660608201524291158061257157506001840154815161256d916001600160401b031690613164565b8210155b15612597576001600160401b0383166060820152818152604081015160208201526125b6565b82816060018181516125a9919061352a565b6001600160401b03169052505b60608101516125c690606461354a565b602082015160018601546001600160401b0392909216916125f19190600160401b900460ff16613326565b101561262157606081015160405163dfae880160e01b81526001600160401b039091166004820152602401610499565b856001600160401b03168160400181815161263c9190613164565b9052506040810180516001600160401b038716919061265c908390613313565b905250805160028501556020810151600385015560408101516004850155606001516005909301805467ffffffffffffffff19166001600160401b039094169390931790925550505050565b5f60608260400151516030146126d15760405163180ffa0d60e01b815260040160405180910390fd5b82516020808501518051604080880151606089015160808a01518051908701515193515f98612712988a986001989297929690959094909390929101613575565b60405160208183030381529060405290505f5b846080015160200151518110156127845781856080015160200151828151811061275157612751612e84565b602002602001015160405160200161276a92919061362f565b60408051601f198184030181529190529150600101612725565b5060a08401518051602091820151516040516127a4938593929101613665565b60405160208183030381529060405290505f5b8460a00151602001515181101561281657818560a001516020015182815181106127e3576127e3612e84565b60200260200101516040516020016127fc92919061362f565b60408051601f1981840301815291905291506001016127b7565b5060c084015160405161282d9183916020016136a0565b604051602081830303815290604052905060028160405161284e9190613035565b602060405180830381855afa158015612869573d5f803e3d5ffd5b5050506040513d601f19601f8201168201806040525081019061288c9190612e28565b94909350915050565b7ff0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a0054600160401b900460ff16610a4857604051631afcd79f60e31b815260040160405180910390fd5b6128e6612895565b6128ee61297d565b610fd881612985565b6128ff612895565b610fd881612a6d565b5f8181525f8051602061372d8339815191526020526040812060020180545f8051602061370d833981519152919060089061295290600160401b90046001600160401b03166136d1565b91906101000a8154816001600160401b0302191690836001600160401b031602179055915050919050565b610a48612895565b61298d612895565b80355f8051602061370d83398151915290815560146129b260608401604085016136ec565b60ff1611806129d157506129cc60608301604084016136ec565b60ff16155b15612a05576129e660608301604084016136ec565b604051634a59bbff60e11b815260ff9091166004820152602401610499565b612a1560608301604084016136ec565b60018201805460ff92909216600160401b0260ff60401b19909216919091179055612a46604083016020840161337f565b600191909101805467ffffffffffffffff19166001600160401b0390921691909117905550565b610fa6612895565b508054612a8190612dd0565b5f825580601f10612a90575050565b601f0160209004905f5260205f2090810190610fd89190612ae9565b6040805160e08101909152805f81526060602082018190525f604083018190529082018190526080820181905260a0820181905260c09091015290565b5b80821115612afd575f8155600101612aea565b5090565b5f60208284031215612b11575f80fd5b5035919050565b803563ffffffff81168114612b2b575f80fd5b919050565b5f8060408385031215612b41575f80fd5b82356001600160401b03811115612b56575f80fd5b830160808186031215612b67575f80fd5b9150612b7560208401612b18565b90509250929050565b5f60208284031215612b8e575f80fd5b610a7282612b18565b80356001600160401b0381168114612b2b575f80fd5b5f8060408385031215612bbe575f80fd5b82356001600160401b03811115612bd3575f80fd5b830160a08186031215612be4575f80fd5b9150612b7560208401612b97565b6001600160a01b0381168114610fd8575f80fd5b5f808284036080811215612c18575f80fd5b6060811215612c25575f80fd5b508291506060830135612c3781612bf2565b809150509250929050565b634e487b7160e01b5f52602160045260245ffd5b60068110612c7257634e487b7160e01b5f52602160045260245ffd5b9052565b5f5b83811015612c90578181015183820152602001612c78565b50505f910152565b5f8151808452612caf816020860160208601612c76565b601f01601f19169290920160200192915050565b60208152612cd5602082018351612c56565b5f602083015160e06040840152612cf0610100840182612c98565b905060408401516001600160401b0380821660608601528060608701511660808601528060808701511660a08601528060a08701511660c08601528060c08701511660e086015250508091505092915050565b5f60208284031215612d53575f80fd5b8135612d5e81612bf2565b9392505050565b5f8060208385031215612d76575f80fd5b82356001600160401b0380821115612d8c575f80fd5b818501915085601f830112612d9f575f80fd5b813581811115612dad575f80fd5b866020828501011115612dbe575f80fd5b60209290920196919550909350505050565b600181811c90821680612de457607f821691505b602082108103612e0257634e487b7160e01b5f52602260045260245ffd5b50919050565b60208101610a758284612c56565b602081525f610a726020830184612c98565b5f60208284031215612e38575f80fd5b5051919050565b5f808335601e19843603018112612e54575f80fd5b8301803591506001600160401b03821115612e6d575f80fd5b6020019150600581901b36038213156124c7575f80fd5b634e487b7160e01b5f52603260045260245ffd5b5f8235605e19833603018112612eac575f80fd5b9190910192915050565b634e487b7160e01b5f52604160045260245ffd5b604051606081016001600160401b0381118282101715612eec57612eec612eb6565b60405290565b604080519081016001600160401b0381118282101715612eec57612eec612eb6565b604051601f8201601f191681016001600160401b0381118282101715612f3c57612f3c612eb6565b604052919050565b5f6001600160401b03821115612f5c57612f5c612eb6565b50601f01601f191660200190565b5f82601f830112612f79575f80fd5b8135612f8c612f8782612f44565b612f14565b818152846020838601011115612fa0575f80fd5b816020850160208301375f918101602001919091529392505050565b5f60608236031215612fcc575f80fd5b612fd4612eca565b82356001600160401b0380821115612fea575f80fd5b612ff636838701612f6a565b8352602085013591508082111561300b575f80fd5b5061301836828601612f6a565b60208301525061302a60408401612b97565b604082015292915050565b5f8251612eac818460208701612c76565b601f821115610a1e57805f5260205f20601f840160051c8101602085101561306b5750805b601f840160051c820191505b8181101561308a575f8155600101613077565b5050505050565b81516001600160401b038111156130aa576130aa612eb6565b6130be816130b88454612dd0565b84613046565b602080601f8311600181146130f1575f84156130da5750858301515b5f19600386901b1c1916600185901b178555613148565b5f85815260208120601f198616915b8281101561311f57888601518255948401946001909101908401613100565b508582101561313c57878501515f19600388901b60f8161c191681555b505060018460011b0185555b505050505050565b634e487b7160e01b5f52601160045260245ffd5b80820180821115610a7557610a75613150565b5f63ffffffff80831681810361318f5761318f613150565b6001019392505050565b5f60208083525f84546131ab81612dd0565b806020870152604060018084165f81146131cc57600181146131e857613215565b60ff19851660408a0152604084151560051b8a01019550613215565b895f5260205f205f5b8581101561320c5781548b82018601529083019088016131f1565b8a016040019650505b509398975050505050505050565b818382375f9101908152919050565b80518015158114612b2b575f80fd5b5f8060408385031215613252575f80fd5b82516001600160401b0380821115613268575f80fd5b908401906060828703121561327b575f80fd5b613283612eca565b8251815260208084015161329681612bf2565b828201526040840151838111156132ab575f80fd5b80850194505087601f8501126132bf575f80fd5b835192506132cf612f8784612f44565b83815288828587010111156132e2575f80fd5b6132f184838301848801612c76565b80604084015250819550613306818801613232565b9450505050509250929050565b81810381811115610a7557610a75613150565b8082028115828204841417610a7557610a75613150565b5f808335601e19843603018112613352575f80fd5b8301803591506001600160401b0382111561336b575f80fd5b6020019150368190038213156124c7575f80fd5b5f6020828403121561338f575f80fd5b610a7282612b97565b5f88516133a9818460208d01612c76565b60e089901b6001600160e01b031916908301908152868860048301378681019050600481015f8152858782375060c09390931b6001600160c01b0319166004939094019283019390935250600c019695505050505050565b60208152816020820152818360408301375f818301604090810191909152601f909201601f19160101919050565b5f8235603e19833603018112612eac575f80fd5b5f60408236031215613453575f80fd5b61345b612ef2565b61346483612b18565b81526020808401356001600160401b0380821115613480575f80fd5b9085019036601f830112613492575f80fd5b8135818111156134a4576134a4612eb6565b8060051b91506134b5848301612f14565b81815291830184019184810190368411156134ce575f80fd5b938501935b838510156134f857843592506134e883612bf2565b82825293850193908501906134d3565b94860194909452509295945050505050565b6001600160401b0382811682821603908082111561119457611194613150565b6001600160401b0381811683821601908082111561119457611194613150565b6001600160401b0381811683821602808216919082811461356d5761356d613150565b505092915050565b61ffff60f01b8a60f01b1681525f63ffffffff60e01b808b60e01b166002840152896006840152808960e01b1660268401525086516135bb81602a850160208b01612c76565b8651908301906135d281602a840160208b01612c76565b60c087901b6001600160c01b031916602a9290910191820152613604603282018660e01b6001600160e01b0319169052565b61361d603682018560e01b6001600160e01b0319169052565b603a019b9a5050505050505050505050565b5f8351613640818460208801612c76565b60609390931b6bffffffffffffffffffffffff19169190920190815260140192915050565b5f8451613676818460208901612c76565b6001600160e01b031960e095861b8116919093019081529290931b16600482015260080192915050565b5f83516136b1818460208801612c76565b60c09390931b6001600160c01b0319169190920190815260080192915050565b5f6001600160401b0380831681810361318f5761318f613150565b5f602082840312156136fc575f80fd5b813560ff81168114612d5e575f80fdfee92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb00e92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb07a164736f6c6343000819000a",
            "balance": "0x0",
            "nonce": "0x1"
        },
        "0feedc0de0000000000000000000000000000000": {
            "code": "0x60806040523661001357610011610017565b005b6100115b61001f610169565b6001600160a01b0316330361015f5760606001600160e01b0319600035166364d3180d60e11b810161005a5761005361019c565b9150610157565b63587086bd60e11b6001600160e01b031982160161007a576100536101f3565b63070d7c6960e41b6001600160e01b031982160161009a57610053610239565b621eb96f60e61b6001600160e01b03198216016100b95761005361026a565b63a39f25e560e01b6001600160e01b03198216016100d9576100536102aa565b60405162461bcd60e51b815260206004820152604260248201527f5472616e73706172656e745570677261646561626c6550726f78793a2061646d60448201527f696e2063616e6e6f742066616c6c6261636b20746f2070726f78792074617267606482015261195d60f21b608482015260a4015b60405180910390fd5b815160208301f35b6101676102be565b565b60007fb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d61035b546001600160a01b0316919050565b60606101a66102ce565b60006101b53660048184610683565b8101906101c291906106c9565b90506101df816040518060200160405280600081525060006102d9565b505060408051602081019091526000815290565b60606000806102053660048184610683565b81019061021291906106fa565b91509150610222828260016102d9565b604051806020016040528060008152509250505090565b60606102436102ce565b60006102523660048184610683565b81019061025f91906106c9565b90506101df81610305565b60606102746102ce565b600061027e610169565b604080516001600160a01b03831660208201529192500160405160208183030381529060405291505090565b60606102b46102ce565b600061027e61035c565b6101676102c961035c565b61036b565b341561016757600080fd5b6102e28361038f565b6000825111806102ef5750805b15610300576102fe83836103cf565b505b505050565b7f7e644d79422f17c01e4894b5f4f588d331ebfa28653d42ae832dc59e38c9798f61032e610169565b604080516001600160a01b03928316815291841660208301520160405180910390a1610359816103fb565b50565b60006103666104a4565b905090565b3660008037600080366000845af43d6000803e80801561038a573d6000f35b3d6000fd5b610398816104cc565b6040516001600160a01b038216907fbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b90600090a250565b60606103f4838360405180606001604052806027815260200161083060279139610560565b9392505050565b6001600160a01b0381166104605760405162461bcd60e51b815260206004820152602660248201527f455243313936373a206e65772061646d696e20697320746865207a65726f206160448201526564647265737360d01b606482015260840161014e565b807fb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d61035b80546001600160a01b0319166001600160a01b039290921691909117905550565b60007f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc61018d565b6001600160a01b0381163b6105395760405162461bcd60e51b815260206004820152602d60248201527f455243313936373a206e657720696d706c656d656e746174696f6e206973206e60448201526c1bdd08184818dbdb9d1c9858dd609a1b606482015260840161014e565b807f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc610483565b6060600080856001600160a01b03168560405161057d91906107e0565b600060405180830381855af49150503d80600081146105b8576040519150601f19603f3d011682016040523d82523d6000602084013e6105bd565b606091505b50915091506105ce868383876105d8565b9695505050505050565b60608315610647578251600003610640576001600160a01b0385163b6106405760405162461bcd60e51b815260206004820152601d60248201527f416464726573733a2063616c6c20746f206e6f6e2d636f6e7472616374000000604482015260640161014e565b5081610651565b6106518383610659565b949350505050565b8151156106695781518083602001fd5b8060405162461bcd60e51b815260040161014e91906107fc565b6000808585111561069357600080fd5b838611156106a057600080fd5b5050820193919092039150565b80356001600160a01b03811681146106c457600080fd5b919050565b6000602082840312156106db57600080fd5b6103f4826106ad565b634e487b7160e01b600052604160045260246000fd5b6000806040838503121561070d57600080fd5b610716836106ad565b9150602083013567ffffffffffffffff8082111561073357600080fd5b818501915085601f83011261074757600080fd5b813581811115610759576107596106e4565b604051601f8201601f19908116603f01168101908382118183101715610781576107816106e4565b8160405282815288602084870101111561079a57600080fd5b8260208601602083013760006020848301015280955050505050509250929050565b60005b838110156107d75781810151838201526020016107bf565b50506000910152565b600082516107f28184602087016107bc565b9190910192915050565b602081526000825180602084015261081b8160408501602087016107bc565b601f01601f1916919091016040019291505056fe416464726573733a206c6f772d6c6576656c2064656c65676174652063616c6c206661696c6564a2646970667358221220b22984eb1f3348f5b2148862b6f80392e497e3c65d0d2cfbb5e53d737e5a6c6a64736f6c63430008190033",
            "storage": {
                "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc": "0x0000000000000000000000000c0deba5e0000000000000000000000000000000",
                "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103": "0x000000000000000000000000c0ffee1234567890abcdef1234567890abcdef34"
            },
            "balance": "0x0",
            "nonce": "0x1"
        },
        "32aaa04b1c166d02b0ee152dd221367687f72108": {
            "balance": "0x2086ac351052600000"
        },
        "48a90c916ad48a72f49fa72a9f889c1ba9cc9b4b": {
            "balance": "0x8ac7230489e80000"
        },
        "8db97c7cece249c2b98bdc0226cc4c2a57bf52fc": {
            "balance": "0xd3c21bcecceda1000000"
        },
        "c0ffee1234567890abcdef1234567890abcdef34": {
            "code": "0x60806040526004361061007b5760003560e01c80639623609d1161004e5780639623609d1461011157806399a88ec414610124578063f2fde38b14610144578063f3b7dead1461016457600080fd5b8063204e1c7a14610080578063715018a6146100bc5780637eff275e146100d35780638da5cb5b146100f3575b600080fd5b34801561008c57600080fd5b506100a061009b366004610499565b610184565b6040516001600160a01b03909116815260200160405180910390f35b3480156100c857600080fd5b506100d1610215565b005b3480156100df57600080fd5b506100d16100ee3660046104bd565b610229565b3480156100ff57600080fd5b506000546001600160a01b03166100a0565b6100d161011f36600461050c565b610291565b34801561013057600080fd5b506100d161013f3660046104bd565b610300565b34801561015057600080fd5b506100d161015f366004610499565b610336565b34801561017057600080fd5b506100a061017f366004610499565b6103b4565b6000806000836001600160a01b03166040516101aa90635c60da1b60e01b815260040190565b600060405180830381855afa9150503d80600081146101e5576040519150601f19603f3d011682016040523d82523d6000602084013e6101ea565b606091505b5091509150816101f957600080fd5b8080602001905181019061020d91906105e2565b949350505050565b61021d6103da565b6102276000610434565b565b6102316103da565b6040516308f2839760e41b81526001600160a01b038281166004830152831690638f283970906024015b600060405180830381600087803b15801561027557600080fd5b505af1158015610289573d6000803e3d6000fd5b505050505050565b6102996103da565b60405163278f794360e11b81526001600160a01b03841690634f1ef2869034906102c990869086906004016105ff565b6000604051808303818588803b1580156102e257600080fd5b505af11580156102f6573d6000803e3d6000fd5b5050505050505050565b6103086103da565b604051631b2ce7f360e11b81526001600160a01b038281166004830152831690633659cfe69060240161025b565b61033e6103da565b6001600160a01b0381166103a85760405162461bcd60e51b815260206004820152602660248201527f4f776e61626c653a206e6577206f776e657220697320746865207a65726f206160448201526564647265737360d01b60648201526084015b60405180910390fd5b6103b181610434565b50565b6000806000836001600160a01b03166040516101aa906303e1469160e61b815260040190565b6000546001600160a01b031633146102275760405162461bcd60e51b815260206004820181905260248201527f4f776e61626c653a2063616c6c6572206973206e6f7420746865206f776e6572604482015260640161039f565b600080546001600160a01b038381166001600160a01b0319831681178455604051919092169283917f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e09190a35050565b6001600160a01b03811681146103b157600080fd5b6000602082840312156104ab57600080fd5b81356104b681610484565b9392505050565b600080604083850312156104d057600080fd5b82356104db81610484565b915060208301356104eb81610484565b809150509250929050565b634e487b7160e01b600052604160045260246000fd5b60008060006060848603121561052157600080fd5b833561052c81610484565b9250602084013561053c81610484565b9150604084013567ffffffffffffffff8082111561055957600080fd5b818601915086601f83011261056d57600080fd5b81358181111561057f5761057f6104f6565b604051601f8201601f19908116603f011681019083821181831017156105a7576105a76104f6565b816040528281528960208487010111156105c057600080fd5b8260208601602083013760006020848301015280955050505050509250925092565b6000602082840312156105f457600080fd5b81516104b681610484565b60018060a01b03831681526000602060406020840152835180604085015260005b8181101561063c57858101830151858201606001528201610620565b506000606082860101526060601f19601f83011685010192505050939250505056fea264697066735822122019f39983a6fd15f3cffa764efd6fb0234ffe8d71051b3ebddc0b6bd99f87fa9764736f6c63430008190033",
            "storage": {
                "0x0000000000000000000000000000000000000000000000000000000000000000": "0x00000000000000000000000048a90c916ad48a72f49fa72a9f889c1ba9cc9b4b"
            },
            "balance": "0x0",
            "nonce": "0x1"
        }
    },
    "airdropHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "airdropAmount": null,
    "number": "0x0",
    "gasUsed": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "baseFeePerGas": null,
    "excessBlobGas": null,
    "blobGasUsed": null
}
```

Open a text editor and copy the preceding text into a file called `custom_genesis.json`. For full breakdown of the genesis file, see the [Genesis File](/docs/lux-l1s/evm-configuration/customize-lux-l1#genesis).

<Callout title="Note">
The `timestamp` field is the Unix timestamp of the genesis block. `0x677eb2d9` represents
the timestamp 1736356569 which is the time this tutorial was written. You should use the
timestamp when you create your genesis file.
</Callout>

Create the Lux L1 Configuration[​](#create-the-lux-l1-configuration "Direct link to heading")
---------------------------------------------------------------------------------------------

Now that you have your binary, it's time to create the Lux L1 configuration. This tutorial uses `myblockchain` as it's Lux L1 name. Invoke the Lux L1 Creation Wizard with this command:

```bash
lux blockchain create myblockchain
```

### Choose Your VM[​](#choose-your-vm "Direct link to heading")

Select `Custom` for your VM.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
    Subnet-EVM
  ▸ Custom
```

### Select Validator Manager type
```bash
Which validator management type would you like to use in your blockchain?:
  ▸ Proof Of Authority
    Proof Of Stake
    Explain the difference
```
Select the Validator manager that matches the `deployedBytecode` in your genesis. This tutorial is using Proof Of Authority.

Next, select the key that will be used to controller the PoA ValidatorManager contract:

```bash
Which address do you want to enable as controller of ValidatorManager contract?:
  ▸ Get address from an existing stored key (created from lux key create or lux key import)
    Custom
```
This key can add, remove and change weight of the validator set.

### Enter the Path to Your Genesis[​](#enter-the-path-to-your-genesis "Direct link to heading")

Enter the path to the genesis file you created in this [step](#create-a-custom-genesis).

```bash
✔ Enter path to custom genesis: ./custom_genesis.json
```

### ICM Setup

```bash
? Do you want to connect your blockchain with other blockchains or the LUExchange-Chain?:
    Yes, I want to enable my blockchain to interoperate with other blockchains and the LUExchange-Chain
  ▸ No, I want to run my blockchain isolated
    Explain the difference
```

Select no for now as we can setup ICM after deployment.

### Enter the Path to Your VM Binary[​](#enter-the-path-to-your-vm-binary "Direct link to heading")
```bash
? How do you want to set up the VM binary?:
    Download and build from a git repository (recommended for cloud deployments)
  ▸ I already have a VM binary (local network deployments only)
```
Select `I already have a VM binary`.
Next, enter the path to your VM binary. This should be the path to the `custom_evm.bin` you created [previously](#modify-and-build-subnet-evm).

```bash
✔ Enter path to vm binary: ./custom_vm.bin
```

### Wrapping Up[​](#wrapping-up "Direct link to heading")

If all worked successfully, the command prints:
```bash
✓ Successfully created blockchain configuration
Run 'lux blockchain describe' to view all created addresses and what their roles are
```

Now it's time to deploy it.

Deploy the Lux L1 Locally[​](#deploy-the-lux-l1-locally "Direct link to heading")
---------------------------------------------------------------------------------

To deploy your Lux L1, run:
```bash
lux blockchain deploy myblockchain
```


Make sure to substitute the name of your Lux L1 if you used a different one than `myblockchain`.

Next, select `Local Network`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Local Network
    Testnet
    Mainnet
```

This command boots a five node Lux network on your machine. It needs to download the latest versions of LuxGo and Subnet-EVM. The command may take a couple minutes to run.

If all works as expected, the command output should look something like this:

```bash
Deploying [myblockchain] to Local Network

Backend controller started, pid: 49158, output at: /Users/l1-dev/.lux-cli/runs/server_20250108_140532/lux-cli-backend.log

Installing luxgo-v1.12.1...
luxgo-v1.12.1 installation successful
LuxGo path: /Users/l1-dev/.lux-cli/bin/luxgo/luxgo-v1.12.1/luxgo

Booting Network. Wait until healthy...

Node logs directory: /Users/l1-dev/.lux-cli/runs/network_20250108_140538/node<i>/logs

Network ready to use.

Your blockchain control keys: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
Your subnet auth keys for chain creation: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
CreateSubnetTx fee: 0.000010278 LUX
Subnet has been created with ID: GEieSy2doZ96bpMo5CuHPaX1LvaxpKZ9C72L22j94t6YyUb6X
Now creating blockchain...
CreateChainTx fee: 0.000095896 LUX
+-------------------------------------------------------------------+
|                         DEPLOYMENT RESULTS                        |
+---------------+---------------------------------------------------+
| Chain Name    | myblockchain                                      |
+---------------+---------------------------------------------------+
| Subnet ID     | GEieSy2doZ96bpMo5CuHPaX1LvaxpKZ9C72L22j94t6YyUb6X |
+---------------+---------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV |
+---------------+---------------------------------------------------+
| Blockchain ID | 9FrNVEPkVpQyWDECQhEPDuT9oK98EhWQdg7anypKujVt9uSVT |
+---------------+                                                   |
| Platform-Chain TXID  |                                                   |
+---------------+---------------------------------------------------+

Restarting node node2 to track subnet
Restarting node node1 to track subnet
Waiting for http://127.0.0.1:9652/ext/bc/9FrNVEPkVpQyWDECQhEPDuT9oK98EhWQdg7anypKujVt9uSVT/rpc to be available
Waiting for http://127.0.0.1:9650/ext/bc/9FrNVEPkVpQyWDECQhEPDuT9oK98EhWQdg7anypKujVt9uSVT/rpc to be available
✓ Local Network successfully tracking myblockchain
✓ Subnet is successfully deployed Local Network
```

Use the describe command to find your L1s RPC: 
```bash
lux blockchain describe myblockchain
```

You can use the `RPC URL` to connect to and interact with your Lux L1.

Interact with Your Lux L1[​](#interact-with-your-lux-l1 "Direct link to heading")
---------------------------------------------------------------------------------

### Check the Version[​](#check-the-version "Direct link to heading")

You can verify that your Lux L1 has deployed correctly by querying the local node to see what Lux L1s it's running. You need to use the [`getNodeVersion`](/docs/rpcs/other/info-rpc#infogetnodeversion) endpoint. Try running this curl command:

```bash
curl --location --request POST 'http://127.0.0.1:9650/ext/info' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeVersion",
    "params" :{
    }
}'
```

The command returns a list of all the VMs your local node is currently running along with their versions.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "version": "lux/1.10.8",
    "databaseVersion": "v1.4.5",
    "rpcProtocolVersion": "27",
    "gitCommit": "e70a17d9d988b5067f3ef5c4a057f15ae1271ac4",
    "vmVersions": {
      "xvm": "v1.10.8",
      "evm": "v0.12.5",
      "platform": "v1.10.8",
      "qDMnZ895HKpRXA2wEvujJew8nNFEkvcrH5frCR9T1Suk1sREe": "v0.5.4@c0fe6506a40da466285f37dd0d3c044f494cce32"
    }
  },
  "id": 1
}
```

Your results may be slightly different, but you can see that in addition to the Exchange-Chain's `xvm`, the LUExchange-Chain's `evm`, and the Platform-Chain's `platform` VM, the node is running the custom VM with commit `c0fe6506a40da466285f37dd0d3c044f494cce32`.

### Check a Balance[​](#check-a-balance "Direct link to heading")

If you used the default genesis, your custom VM has a prefunded address. You can verify its balance with a curl command. Make sure to substitute the command's URL with the `RPC URL` from your deployment output.

```bash
curl --location --request POST 'http://127.0.0.1:9650/ext/bc/myblockchain/rpc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
        "0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc",
        "latest"
    ],
    "id": 1
}'
```

The command should return:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xd3c21bcecceda1000000"
}
```

The balance is hex encoded, so this means the address has a balance of 1 million tokens.

Note, this command doesn't work on all custom VMs, only VMs that implement the EVM's `eth_getBalance` interface.

Next Steps[​](#next-steps "Direct link to heading")
---------------------------------------------------

You've now unlocked the ability to deploy custom VMs. Go build something cool!


# With Multisig Auth (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-with-multisig-auth)

---
title: With Multisig Auth
description: Learn how to create an Lux L1 with a multisig authorization.
---

Lux L1 creators can control critical Lux L1 operations with a N of M multisig. This multisig must be setup at deployment time and can't be edited afterward. Multisigs can are available on both the Testnet Testnet and Mainnet.

To setup your multisig, you need to know the Platform-Chain address of each key holder and what you want your signing threshold to be.

<Callout title="Note">
Lux-CLI requires Ledgers for Mainnet deployments. This how-to guide assumes the use of Ledgers for setting up your multisig.
</Callout>

## Prerequisites

- [`Lux-CLI`](https://github.com/luxfi/lux-cli) installed
- Familiarity with process of [Deploying an Lux L1 on Testnet](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-testnet-testnet) and [Deploying a Permissioned Lux L1 on Mainnet](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-mainnet)
- Multiple Ledger devices [configured for Lux](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-mainnet#setting-up-your-ledger)
- an Lux L1 configuration ready to deploy to either Testnet Testnet or Mainnet

Getting Started[​](#getting-started "Direct link to heading")
-------------------------------------------------------------

When issuing the transactions to create the Lux L1, you need to sign the TXs with multiple keys from the multisig.

### Specify Network[​](#specify-network "Direct link to heading")

Start the Lux L1 deployment with

```bash
lux blockchain deploy testLux L1
```

First step is to specify `Testnet` or `Mainnet` as the network:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
    Local Network
    Testnet
  ▸ Mainnet
```

```bash
Deploying [testblockchain] to Mainnet
```

Ledger is automatically recognized as the signature mechanism on `Mainnet`.

After that, the CLI shows the first `Mainnet` Ledger address.

```bash
Ledger address: P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
```

### Set Control Keys[​](#set-control-keys "Direct link to heading")

Next the CLI asks the user to specify the control keys. This is where you setup your multisig.

```bash
Configure which addresses may make changes to the Lux L1.
These addresses are known as your control keys. You are going to also
set how many control keys are required to make an Lux L1 change (the threshold).
Use the arrow keys to navigate: ↓ ↑ → ←
? How would you like to set your control keys?:
  ▸ Use ledger address
    Custom list
```

Select `Custom list` and add every address that you'd like to be a key holder on the multisig.

```bash
✔ Custom list
? Enter control keys:
  ▸ Add
    Delete
    Preview
    More Info
↓   Done
```

Use the given menu to add each key, and select `Done` when finished.

The output at this point should look something like:

```bash
✔ Custom list
✔ Add
Enter Platform-Chain address (Example: P-...): P-lux1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28
✔ Add
Enter Platform-Chain address (Example: P-...): P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
✔ Add
Enter Platform-Chain address (Example: P-...): P-lux12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8
✔ Add
Enter Platform-Chain address (Example: P-...): P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
✔ Add
Enter Platform-Chain address (Example: P-...): P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
✔ Done
Your Lux L1's control keys: [P-lux1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28 P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5 P-lux12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8 P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g]
```

<Callout title="Note">
When deploying an Lux L1 with Ledger, you must include the Ledger's default address determined in [Specify Network](#specify-network) for the deployment to succeed. You may see an error like

```
Error: wallet does not contain Lux L1 auth keys
exit status 1
```
</Callout>

### Set Threshold[​](#set-threshold "Direct link to heading")

Next, specify the threshold. In your N of M multisig, your threshold is N, and M is the number of control keys you added in the previous step.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Select required number of control key signatures to make an Lux L1 change:
  ▸ 1
    2
    3
    4
    5
```

### Specify Control Keys to Sign the Chain Creation TX[​](#specify-control-keys-to-sign-the-chain-creation-tx "Direct link to heading")

You now need N of your key holders to sign the Lux L1 deployment transaction. You must select which addresses you want to sign the TX.

```bash
? Choose an Lux L1 auth key:
  ▸ P-lux1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28
    P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
    P-lux12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8
    P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
    P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
```

A successful control key selection looks like:

```bash
✔ 2
✔ P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
✔ P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
Your subnet auth keys for chain creation: [P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5 P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af]
*** Please sign Lux L1 creation hash on the ledger device ***
```

#### Potential Errors[​](#potential-errors "Direct link to heading")

If the currently connected Ledger address isn't included in your TX signing group, the operation fails with:

```bash
✔ 2
✔ P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
✔ P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
Your Lux L1 auth keys for chain creation: [P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g]
Error: wallet does not contain Lux L1 auth keys
exit status 1
```

This can happen either because the original specified control keys -previous step- don't contain the Ledger address, or because the Ledger address control key wasn't selected in the current step.

If the user has the correct address but doesn't have sufficient balance to pay for the TX, the operation fails with:

```bash
✔ 2
✔ P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
✔ P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
Your Lux L1 auth keys for chain creation: [P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g]
*** Please sign Lux L1 creation hash on the ledger device ***
Error: insufficient funds: provided UTXOs need 1000000000 more units of asset "rgNLkDPpANwqg3pHC4o9aGJmf2YU4GgTVUMRKAdnKodihkqgr"
exit status 1
```

### Sign Lux L1 Deployment TX with the First Address[​](#sign-lux-l1-deployment-tx-with-the-first-address "Direct link to heading")

The Lux L1 Deployment TX is ready for signing.

```bash
*** Please sign Lux L1 creation hash on the ledger device ***
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

```bash
Lux L1 has been created with ID: 2qUKjvPx68Fgc1NMi8w4mtaBt5hStgBzPhsQrS1m7vSub2q9ew. Now creating blockchain...
*** Please sign blockchain creation hash on the ledger device ***
```

After successful Lux L1 creation, the CLI asks the user to sign the blockchain creation TX.

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

On success, the CLI provides Lux L1 deploy details. As only one address signed the chain creation TX, the CLI writes a file to disk to save the TX to continue the signing process with another command.

```bash
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | testblockchain                                         |
+--------------------+----------------------------------------------------+
| Subnet ID          | 2qUKjvPx68Fgc1NMi8w4mtaBt5hStgBzPhsQrS1m7vSub2q9ew |
+--------------------+----------------------------------------------------+
| VM ID              | rW1esjm6gy4BtGvxKMpHB2M28MJGFNsqHRY9AmnchdcgeB3ii  |
+--------------------+----------------------------------------------------+

1 of 2 required Blockchain Creation signatures have been signed. Saving TX to disk to enable remaining signing.

Path to export partially signed TX to:
```

Enter the name of file to write to disk, such as `partiallySigned.txt`. This file shouldn't exist already.

```bash
Path to export partially signed TX to: partiallySigned.txt

Addresses remaining to sign the tx: P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af

Connect a ledger with one of the remaining addresses or choose a stored key and run the signing command, or send "partiallySigned.txt" to another user for signing.

Signing command: lux transaction sign testblockchain --input-tx-filepath partiallySigned.txt
```

Gather Remaining Signatures and Issue the Lux L1 Deployment TX[​](#gather-remaining-signatures-and-issue-the-lux-l1-deployment-tx "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------------------------------------------------

So far, one address has signed the Lux L1 deployment TX, but you need N signatures. Your Lux L1 has not been fully deployed yet. To get the remaining signatures, you may connect a different Ledger to the same computer you've been working on. Alternatively, you may send the `partiallySigned.txt` file to other users to sign themselves.

The remainder of this section assumes that you are working on a machine with access to both the remaining keys and the `partiallySigned.txt` file.

### Issue the Command to Sign the Chain Creation TX[​](#issue-the-command-to-sign-the-chain-creation-tx "Direct link to heading")

Lux-CLI can detect the deployment network automatically. For `Mainnet` TXs, it uses your Ledger automatically. For `Testnet Testnet`, the CLI prompts the user to choose the signing mechanism.

You can start the signing process with the `transaction sign` command:

```bash
lux transaction sign testblockchain --input-tx-filepath partiallySigned.txt
```

```bash
Ledger address: P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
*** Please sign TX hash on the ledger device ***
```

Next, the CLI starts a new signing process for the Lux L1 deployment TX. If the Ledger isn't the correct one, the following error should appear instead:

```bash
Ledger address: P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
Error: wallet does not contain Lux L1 auth keys
exit status 1
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

Repeat this processes until all required parties have signed the TX. You should see a message like this:

```bash
All 2 required Tx signatures have been signed. Saving TX to disk to enable commit.

Overwriting partiallySigned.txt

Tx is fully signed, and ready to be committed

Commit command: lux transaction commit testblockchain --input-tx-filepath partiallySigned.txt
```

Now, `partiallySigned.txt` contains a fully signed TX.

### Commit the Lux L1 Deployment TX[​](#commit-the-lux-l1-deployment-tx "Direct link to heading")

To run submit the fully signed TX, run:

```bash
lux transaction commit testblockchain --input-tx-filepath partiallySigned.txt
```

The CLI recognizes the deployment network automatically and submits the TX appropriately.

```bash
+--------------------+-------------------------------------------------------------------------------------+
| DEPLOYMENT RESULTS |                                                                                     |
+--------------------+-------------------------------------------------------------------------------------+
| Chain Name         | testblockchain                                                                          |
+--------------------+-------------------------------------------------------------------------------------+
| Subnet ID          | 2qUKjvPx68Fgc1NMi8w4mtaBt5hStgBzPhsQrS1m7vSub2q9ew                                  |
+--------------------+-------------------------------------------------------------------------------------+
| VM ID              | rW1esjm6gy4BtGvxKMpHB2M28MJGFNsqHRY9AmnchdcgeB3ii                                   |
+--------------------+-------------------------------------------------------------------------------------+
| Blockchain ID      | 2fx9EF61C964cWBu55vcz9b7gH9LFBkPwoj49JTSHA6Soqqzoj                                  |
+--------------------+-------------------------------------------------------------------------------------+
| RPC URL            | http://127.0.0.1:9650/ext/bc/2fx9EF61C964cWBu55vcz9b7gH9LFBkPwoj49JTSHA6Soqqzoj/rpc |
+--------------------+-------------------------------------------------------------------------------------+
| Platform-Chain TXID       | 2fx9EF61C964cWBu55vcz9b7gH9LFBkPwoj49JTSHA6Soqqzoj                                  |
+--------------------+-------------------------------------------------------------------------------------+
```

Your Lux L1 successfully deployed with a multisig.

Add Validators Using the Multisig[​](#add-validators-using-the-multisig "Direct link to heading")
-------------------------------------------------------------------------------------------------

The `addValidator` command also requires use of the multisig. Before starting, make sure to connect, unlock, and run the Lux Ledger app.

```bash
lux blockchain addValidator testblockchain
```

### Select Network[​](#select-network "Direct link to heading")

First specify the network. Select either `Testnet` or `Mainnet`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to add validator to.:
  ▸ Testnet
    Mainnet
```

### Choose Signing Keys[​](#choose-signing-keys "Direct link to heading")

Then, similar to the `deploy` command, the command asks the user to select the N control keys needed to sign the TX.

```bash
✔ Mainnet
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose an Lux L1 auth key:
  ▸ P-lux1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28
    P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
    P-lux12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8
    P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
    P-lux1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
```

```bash
✔ Mainnet
✔ P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
✔ P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
Your subnet auth keys for add validator TX creation: [P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5 P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af].
```

### Finish Assembling the TX[​](#finish-assembling-the-tx "Direct link to heading")

Take a look at [Add a Validator](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-mainnet#add-a-validator) for additional help issuing this transaction.

<Callout title="Note">
If setting up a multisig, don't select your validator start time to be in one minute. Finishing the signing process takes significantly longer when using a multisig.
</Callout>

```bash
Next, we need the NodeID of the validator you want to whitelist.

Check https://build.lux.network/docs/rpcs/other/info-rpc#info-getnodeid for instructions about how to query the NodeID from your node
(Edit host IP address and port to match your deployment, if needed).
What is the NodeID of the validator you'd like to whitelist?: NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
✔ Default (20)
When should your validator start validating?
If your validator is not ready by this time, Lux L1 downtime can occur.
✔ Custom
When should the validator start validating? Enter a UTC datetime in 'YYYY-MM-DD HH:MM:SS' format: 2022-11-22 23:00:00
✔ Until primary network validator expires
NodeID: NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
Network: Local Network
Start time: 2022-11-22 23:00:00
End time: 2023-11-22 15:57:27
Weight: 20
Inputs complete, issuing transaction to add the provided validator information...
```

```bash
Ledger address: P-lux1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
*** Please sign add validator hash on the ledger device ***
```

After that, the command shows the connected Ledger's address, and asks the user to sign the TX with the Ledger.

```bash
Partial TX created

1 of 2 required Add Validator signatures have been signed. Saving TX to disk to enable remaining signing.

Path to export partially signed TX to:
```

Because you've setup a multisig, TX isn't fully signed, and the commands asks a file to write into. Use something like `partialAddValidatorTx.txt`.

```bash
Path to export partially signed TX to: partialAddValidatorTx.txt

Addresses remaining to sign the tx: P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af

Connect a Ledger with one of the remaining addresses or choose a stored key and run the signing command, or send "partialAddValidatorTx.txt" to another user for signing.

Signing command: lux transaction sign testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

Sign and Commit the Add Validator TX[​](#sign-and-commit-the-add-validator-tx "Direct link to heading")
-------------------------------------------------------------------------------------------------------

The process is very similar to signing of Lux L1 Deployment TX. So far, one address has signed the TX, but you need N signatures. To get the remaining signatures, you may connect a different Ledger to the same computer you've been working on. Alternatively, you may send the `partialAddValidatorTx.txt` file to other users to sign themselves.

The remainder of this section assumes that you are working on a machine with access to both the remaining keys and the `partialAddValidatorTx.txt` file.

### Issue the Command to Sign the Add Validator TX[​](#issue-the-command-to-sign-the-add-validator-tx "Direct link to heading")

Lux-CLI can detect the deployment network automatically. For `Mainnet` TXs, it uses your Ledger automatically. For `Testnet Testnet`, the CLI prompts the user to choose the signing mechanism.

```bash
lux transaction sign testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

```bash
Ledger address: P-lux1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
*** Please sign TX hash on the ledger device ***
```

Next, the command is going to start a new signing process for the Add Validator TX.

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

Repeat this processes until all required parties have signed the TX. You should see a message like this:

```bash
All 2 required Tx signatures have been signed. Saving TX to disk to enable commit.

Overwriting partialAddValidatorTx.txt

Tx is fully signed, and ready to be committed

Commit command: lux transaction commit testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

Now, `partialAddValidatorTx.txt` contains a fully signed TX.

### Issue the Command to Commit the add validator TX[​](#issue-the-command-to-commit-the-add-validator-tx "Direct link to heading")

To run submit the fully signed TX, run:

```bash
lux transaction commit testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

The CLI recognizes the deployment network automatically and submits the TX appropriately.

```bash
Transaction successful, transaction ID: K7XNSwcmgjYX7BEdtFB3hEwQc6YFKRq9g7hAUPhW4J5bjhEJG
```

You've successfully added the validator to the Lux L1.


# Teleporter on Devnet (/docs/tooling/avalanche-cli/cross-chain/teleporter-devnet)

---
title: Teleporter on Devnet
description: This how-to guide focuses on deploying Teleporter-enabled Lux L1s to a Devnet.
---

After this tutorial, you would have created a Devnet and deployed two Lux L1s in it, and have enabled them to cross-communicate with each other and with the LUExchange-Chain through Teleporter and the underlying Warp technology.

For more information on cross chain messaging through Teleporter and Warp, check:

- [Cross Chain References](/docs/cross-chain)

Note that currently only [Subnet-EVM](https://github.com/luxfi/subnet-evm) and [Subnet-EVM-Based](/docs/lux-l1s/evm-configuration/customize-lux-l1) virtual machines support Teleporter.

## Prerequisites

Before we begin, you will need to have:

- Created an AWS account and have an updated AWS `credentials` file in home directory with \[default\] profile

Note: the tutorial uses AWS hosts, but Devnets can also be created and operated in other supported cloud providers, such as GCP.

Create Lux L1s Configurations[​](#create-lux-l1s-configurations "Direct link to heading")
-----------------------------------------------------------------------------------------

For this section we will follow this [steps](/docs/tooling/lux-cli/cross-chain/teleporter-local-network#create-lux-l1s-configurations), to create two Teleporter-enabled Lux L1s, `<chain1>` and `<chain2>`.

Create a Devnet and Deploy an Lux L1 in It[​](#create-a-devnet-and-deploy-a-lux-l1-in-it "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------

Let's use the `devnet wiz` command to create a devnet `<devnetName>` and deploy `<chain1>` in it.

The devnet will be created in the `us-east-1` region of AWS, and will consist of 5 validators only.

```bash
lux node devnet wiz <devnetName> <chain1> --aws --node-type default --region us-east-1 --num-validators 5 --num-apis 0 --enable-monitoring=false --default-validator-params 

Creating the devnet...

Creating new EC2 instance(s) on AWS...
...

Deploying [chain1] to Cluster <devnetName>
...

configuring AWM RElayer on host i-0f1815c016b555fcc

Setting the nodes as subnet trackers
...

Setting up teleporter on subnet

Teleporter Messenger successfully deployed to chain1 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to chain1 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to c-chain (0x5DB9A7629912EBF95876228C24A848de0bfB43A9)

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay subnet chain1
updating configuration file ~/.lux-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is successfully created and is now validating subnet chain1!

Subnet <chain1> RPC URL: http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc
 
✓ Cluster information YAML file can be found at ~/.lux-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Notice some details here:

- Two smart contracts are deployed to the Lux L1: Teleporter Messenger and Teleporter Registry
- Both Teleporter smart contracts are also deployed to `LUExchange-Chain`
- [AWM Teleporter Relayer](https://github.com/luxfi/awm-relayer) is installed and configured as a service into one of the nodes (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Lux L1 and sends them to the destination Lux L1.)

CLI configures the Relayer to enable every Lux L1 to send messages to all other Lux L1s. If you add more Lux L1s to the Devnet, the Relayer will be automatically reconfigured.

Checking Devnet Configuration and Relayer Logs[​](#checking-devnet-configuration-and-relayer-logs "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------

Execute `node list` command to get a list of the devnet nodes:

```bash
lux node list

Cluster "<devnetName>" (Devnet)
  Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]
  Node i-026392a651571232c (NodeID-AkPyyTs9e9nPGShdSoxdvWYZ6X2zYoyrK) 52.203.183.68 [Validator]
  Node i-0d1b98d5d941d6002 (NodeID-ByEe7kuwtrPStmdMgY1JiD39pBAuFY2mS) 50.16.235.194 [Validator]
  Node i-0c291f54bb38c2984 (NodeID-8SE2CdZJExwcS14PYEqr3VkxFyfDHKxKq) 52.45.0.56 [Validator]
  Node i-049916e2f35231c29 (NodeID-PjQY7xhCGaB8rYbkXYddrr1mesYi29oFo) 3.214.163.110 [Validator]
```

Notice that, in this case, `i-0f1815c016b555fcc` was set as Relayer. This host contains a `systemd` service called `awm-relayer` that can be used to check the Relayer logs, and set the execution status.

To view the Relayer logs, the following command can be used:

```bash
lux node ssh i-0f1815c016b555fcc "journalctl -u awm-relayer --no-pager"

  [Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]]
Warning: Permanently added '67.202.23.231' (ED25519) to the list of known hosts.
-- Logs begin at Fri 2024-04-05 14:11:43 UTC, end at Fri 2024-04-05 14:30:24 UTC. --
Apr 05 14:15:06 ip-172-31-47-187 systemd[1]: Started AWM Relayer systemd service.
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:66","msg":"Initializing awm-relayer"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:71","msg":"Set config options."}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:78","msg":"Initializing destination clients"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.021Z","logger":"awm-relayer","caller":"main/main.go:97","msg":"Initializing app request network"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.159Z","logger":"awm-relayer","caller":"main/main.go:309","msg":"starting metrics server...","port":9090}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"11111111111111111111111111111111LpoYY","subnetIDHex":"0000000000000000000000000000000000000000000000000000000000000000","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6","blockchainIDHex":"a2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML","subnetIDHex":"5a2e2d87d74b4ec62fdd6626e7d36a44716484dfcc721aa4f2168e8a61af63af","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p","blockchainIDHex":"582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.172Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xea06381426934ec1800992f41615b9d362c727ad542f6351dbfa7ad2849a35bf","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x175e14327136d57fe22d4bdd295ff14bea8a7d7ab1884c06a4d9119b9574b9b3","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xe584ccc0df44506255811f6b54375e46abd5db40a4c84fd9235a68f7b69c6f06","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x70f14d33bde4716928c5c4723d3969942f9dfd1f282b64ffdf96f5ac65403814","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
```

Deploying the Second Lux L1[​](#deploying-the-second-lux-l1 "Direct link to heading")
-------------------------------------------------------------------------------------

Let's use the `devnet wiz` command again to deploy `<chain2>`.

When deploying Lux L1 `<chain2>`, the two Teleporter contracts will not be deployed to LUExchange-Chain in Local Network as they have already been deployed when we deployed the first Lux L1.

```bash
lux node devnet wiz <devnetName> <chain2> --default-validator-params 

Adding subnet into existing devnet <devnetName>...
...

Deploying [chain2] to Cluster <devnetName>
...

Stopping AWM Relayer Service

Setting the nodes as subnet trackers
...

Setting up teleporter on subnet

Teleporter Messenger successfully deployed to chain2 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to chain2 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger has already been deployed to c-chain

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay subnet chain2
updating configuration file ~/.lux-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is now validating subnet chain2

Subnet <chain2> RPC URL: http://67.202.23.231:9650/ext/bc/7gKt6evRnkA2uVHRfmk9WrH3dYZH9gEVVxDAknwtjvtaV3XuQ/rpc

✓ Cluster information YAML file can be found at ~/.lux-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Verify Teleporter Is Successfully Set Up[​](#verify-teleporter-is-successfully-set-up "Direct link to heading")
---------------------------------------------------------------------------------------------------------------

To verify that Teleporter is successfully, let's send a couple of cross messages:

```bash
lux teleporter msg LUExchange-Chain chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source subnet "LUExchange-Chain" (2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6)
Waiting for message to be received at destination subnet subnet "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

```bash
lux teleporter msg chain2 chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source subnet "chain2" (29WP91AG7MqPUFEW2YwtKnsnzVrRsqcWUpoaoSV1Q9DboXGf4q)
Waiting for message to be received at destination subnet subnet "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

You have Teleport-ed your first message in the Devnet!

Obtaining Information on Teleporter Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Lux L1 Information[​](#obtaining-lux-l1-information "Direct link to heading")

By executing `blockchain describe` on a Teleporter enabled Lux L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```bash
lux blockchain describe <chain1>

 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/

+--------------------------------+----------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                    |
+--------------------------------+----------------------------------------------------------------------------------------+
| Blockchain Name                    | chain1                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                           |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> SubnetID  | giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> RPC URL   | http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName>           | fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p                                      |
| BlockchainID                   |                                                                                        |
+                                +----------------------------------------------------------------------------------------+
|                                | 0x582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a                     |
|                                |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                             |
| Messenger Address              |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0xb623C4495220C603D0A939D32478F55891a61750                                             |
| Registry Address               |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
...
```

### Obtaining LUExchange-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for LUExchange-Chain by using `primary describe`:

```bash
lux primary describe --cluster <devnetName>

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://67.202.23.231:9650/ext/bc/C/rpc                             |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | LUX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.815751426                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6                 |
+                              +--------------------------------------------------------------------+
|                              | 0xa2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170 |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x5DB9A7629912EBF95876228C24A848de0bfB43A9                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

CLI provides two commands to remotely control Relayer execution:

```bash
lux interchain relayer stop --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully stopped
```

```bash
lux interchain relayer start --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully started
```


# Teleporter on Local Network (/docs/tooling/avalanche-cli/cross-chain/teleporter-local-network)

---
title: Teleporter on Local Network
description: This how-to guide focuses on deploying Teleporter-enabled Lux L1s to a local Lux network.
---

After this tutorial, you would have created and deployed two Lux L1s to the local network and have enabled them to cross-communicate with each other and with the local LUExchange-Chain (through Teleporter and the underlying Warp technology.)

For more information on cross chain messaging through Teleporter and Warp, check:

- [Cross Chain References](/docs/cross-chain)

Note that currently only [Subnet-EVM](https://github.com/luxfi/subnet-evm) and [Subnet-EVM-Based](/docs/lux-l1s/evm-configuration/customize-lux-l1) virtual machines support Teleporter.

## Prerequisites

- [Lux-CLI installed](/docs/tooling/lux-cli)

## Create Lux L1 Configurations

Let's create an Lux L1 called `<chain1>` with the latest Subnet-EVM version, a chain ID of 1, TOKEN1 as the token name, and with default Subnet-EVM parameters (more information regarding Lux L1 creation can be found [here](/docs/tooling/lux-cli#create-your-lux-l1-configuration)):

```bash
lux blockchain create <chain1> --evm --latest\
    --evm-chain-id 1 --evm-token TOKEN1 --evm-defaults

creating genesis for <blockchain chain1>
configuring airdrop to stored key "subnet_<chain1>_airdrop" with address 0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created subnet configuration
```

Notice that by default, Teleporter is enabled and a stored key is created to fund Teleporter related operations (that is deploy Teleporter smart contracts, fund Teleporter Relayer).

To disable Teleporter in your Lux L1, use the flag `--teleporter=false` when creating the Lux L1.

To disable Relayer in your Lux L1, use the flag `--relayer=false` when creating the Lux L1.

Now let's create a second Lux L1 called `<chain2>`, with similar settings:

```bash
lux blockchain create <chain2> --evm --latest\
    --evm-chain-id 2 --evm-token TOKEN2 --evm-defaults

creating genesis for <blockchain chain2>
configuring airdrop to stored key "subnet_<chain2>_airdrop" with address 0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created subnet configuration
```

Deploy the Lux L1s to Local Network[​](#deploy-the-lux-l1s-to-local-network "Direct link to heading")
-----------------------------------------------------------------------------------------------------

Let's deploy `<chain1>`:

```bash
lux blockchain deploy <chain1> --local

Deploying [<chain1>] to Local Network
Backend controller started, pid: 149427, output at: ~/.lux-cli/runs/server_20240229_165923/lux-cli-backend.log

Booting Network. Wait until healthy...
Node logs directory: ~/.lux-cli/runs/network_20240229_165923/node<i>/logs
Network ready to use.

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)

Teleporter Messenger successfully deployed to <chain1> (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to <chain1> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                        URL                                         |                  ALIAS URL                 |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc
Funded address:   0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1 with 1000000 (10^18) - private key: 16289399c9466912ffffffdc093c9b51124f0dc54ac7a766b2bc5ccf558d8eee
Network name:     <chain1>
Chain ID:         1
Currency Symbol:  TOKEN1
```

Notice some details here:

- Two smart contracts are deployed to each Lux L1: Teleporter Messenger and Teleporter Registry
- Both Teleporter smart contracts are also deployed to `LUExchange-Chain` in the Local Network
- [AWM Teleporter Relayer](https://github.com/luxfi/awm-relayer) is installed, configured and executed in background (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Lux L1 and sends them to the destination Lux L1.)

CLI configures the Relayer to enable every Lux L1 to send messages to all other Lux L1s. If you add more Lux L1s, the Relayer will be automatically reconfigured.

When deploying Lux L1 `<chain2>`, the two Teleporter contracts will not be deployed to LUExchange-Chain in Local Network as they have already been deployed when we deployed the first Lux L1.

```bash
lux blockchain deploy <chain2> --local

Deploying [<chain2>] to Local Network

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger has already been deployed to c-chain

Teleporter Messenger successfully deployed to <chain2> (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to <chain2> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                         URL                                         |                  ALIAS URL                 |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain2> | http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9650/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain2> | http://127.0.0.1:9652/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9652/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain2> | http://127.0.0.1:9654/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9654/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain2> | http://127.0.0.1:9656/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9656/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain2> | http://127.0.0.1:9658/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9658/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc
Funded address:   0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB with 1000000 (10^18) - private key: 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
Network name:     <chain2>
Chain ID:         2
Currency Symbol:  TOKEN2
```

Verify Teleporter Is Successfully Set Up[​](#verify-teleporter-is-successfully-set-up "Direct link to heading")
---------------------------------------------------------------------------------------------------------------

To verify that Teleporter is successfully, let's send a couple of cross messages (from LUExchange-Chain to chain1): 

```bash
lux teleporter sendMsg LUExchange-Chain chain1 "Hello World" --local
```

Results:
```bash
Delivering message "this is a message" to source subnet "LUExchange-Chain"
Waiting for message to be received at destination subnet subnet "chain1"
Message successfully Teleported!
```

To verify that Teleporter is successfully deployed, let's send a couple of cross-chain messages (from chain2 to chain1): 
```bash
lux teleporter sendMsg chain2 chain1 "Hello World" --local
```

Results:
```bash
Delivering message "this is a message" to source subnet "chain2"
Waiting for message to be received at destination subnet subnet "chain1"
Message successfully Teleported!
```

You have Teleport-ed your first message in the Local Network!

Relayer related logs can be found at `~/.lux-cli/runs/awm-relayer.log`, and Relayer configuration can be found at `~/.lux-cli/runs/awm-relayer-config.json`

Obtaining Information on Teleporter Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Lux L1 Information[​](#obtaining-lux-l1-information "Direct link to heading")

By executing `blockchain describe` on a Teleporter enabled Lux L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```bash
lux blockchain describe <chain1>


 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/
+--------------------------------+-------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                 |
+--------------------------------+-------------------------------------------------------------------------------------+
| Blockchain Name                    | chain1                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                        |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network SubnetID         | 2CZP2ndbQnZxTzGuZjPrJAm5b4s2K2Bcjh8NqWoymi8NZMLYQk                                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network RPC URL          | http://127.0.0.1:9650/ext/bc/2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8/rpc |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network BlockchainID     | 2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8                                  |
+                                +-------------------------------------------------------------------------------------+
|                                | 0xd3bc5f71e6946d17c488d320cd1f6f5337d9dce75b3fac5023433c4634b6e91e                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network ICM              | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                          |
| Messenger Address              |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network ICM              | 0xbD9e8eC38E43d34CAB4194881B9BF39d639D7Bd3                                          |
| Registry Address               |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+

...
```

### Obtaining LUExchange-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for LUExchange-Chain by using `primary describe`:

```bash
lux primary describe --local

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://127.0.0.1:9650/ext/bc/C/rpc                                 |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | LUX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.829989485                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2JeJDKL9Bvn1vLuuPL1DpUccBCVUh7iRnkv3a5pV9kJW5HbuQz                 |
+                              +--------------------------------------------------------------------+
|                              | 0xabc1bd35cb7313c8a2b62980172e6d7ef42aaa532c870499a148858b0b6a34fd |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

Besides having the option to not use a Relayer at Lux L1 creation time, the Relayer can be stopped and restarted on used request.

To stop the Relayer:

```bash
lux interchain relayer stop --local

✓ Local AWM Relayer successfully stopped
```

To start it again:

```bash
lux interchain relayer start --local

using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...
✓ Local AWM Relayer successfully started
Logs can be found at ~/.lux-cli/runs/awm-relayer.log
```


# Teleporter Token Bridge (/docs/tooling/avalanche-cli/cross-chain/teleporter-token-bridge)

---
title: Teleporter Token Bridge
description: Deploy an example Teleporter Token Bridge on the local network.
---

Teleporter Token Bridge enables users to transfer tokens between Lux L1s. The bridge is a set of 
smart contracts that are deployed across multiple Lux L1s, and leverages Teleporter for cross-chain 
communication.

For more information on Teleporter Token Bridge, check:

- [Teleporter Token Bridge README](https://github.com/luxfi/teleporter-token-bridge)

## How to Deploy Teleporter Token Bridge on a Local Network

This how-to guide focuses on deploying Teleporter Token Bridge on a local Lux network.

After this tutorial, you would have learned how to transfer an ERC-20 token between two 
Teleporter-enabled Lux L1s and between LUExchange-Chain and a Teleporter-enabled Lux L1.

## Prerequisites

For our example, you will first need to create and deploy a Teleporter-enabled Lux L1 in Local
Network. We will name our Lux L1 `testblockchain`.

- To create a Teleporter-enabled Lux L1 configuration, [visit here](/docs/tooling/lux-cli/cross-chain/teleporter-local-network#create-subnet-configurations)
- To deploy a Teleporter-enabled Lux L1, [visit here](/docs/tooling/lux-cli/cross-chain/teleporter-local-network#deploy-the-subnets-to-local-network)

## Deploy ERC-20 Token in LUExchange-Chain

First, let's create an ERC-20 Token and deploy it to LUExchange-Chain. For our example, it will be called 
TOK. 

Sample script to deploy the ERC-20 Token can be found [here](https://github.com/luxfi/lux-cli/blob/main/cmd/contractcmd/deploy_erc20.go). 


To deploy the ERC-20 Token to LUExchange-Chain, we will call: 

```bash
lux contract deploy erc20
```

When the command is run, our EWOQ address `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` would have 
received 100000 TOK tokens in LUExchange-Chain. 

Note that `0x5DB9A7629912EBF95876228C24A848de0bfB43A9` is our ERC-20 Token address, which we will 
use in our next command.

## Deploy Teleporter Token Bridge 

Next, we will now deploy Teleporter Token Bridge to our Local Network, where we will deploy
the Home Contract to LUExchange-Chain and the Remote Contract to our Lux L1.

```bash
lux teleporter bridge deploy 
✔ Local Network
✔ LUExchange-Chain
✔ Deploy a new Home for the token
✔ An ERC-20 token
Enter the address of the ERC-20 Token: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9
✔ Subnet testblockchain
Downloading Bridge Contracts
Compiling Bridge

Home Deployed to http://127.0.0.1:9650/ext/bc/C/rpc
Home Address: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D

Remote Deployed to http://127.0.0.1:9650/ext/bc/2TnSWd7odhkDWKYFDZHqU7CvtY8G6m46gWxUnhJRNYu4bznrrc/rpc
Remote Address: 0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0
```

Before we transfer our ERC-20 token from LUExchange-Chain to our Lux L1, we will first call `lux key
list` command to check our initial balances in LUExchange-Chain and Lux L1. 

We will inquire the balances of our ERC-20 Token TOK both in LUExchange-Chain and our Lux L1, which has the 
address of `0x5DB9A7629912EBF95876228C24A848de0bfB43A9` in the LUExchange-Chain and address of
`0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0` in our Lux L1 `testblockchain`.

```bash
`lux key list --local --keys ewoq,blockchain_airdrop --subnets c,testblockchain --tokens 0x5DB9A7629912EBF95876228C24A848de0bfB43A9,0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0`
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
|  KIND  |        NAME        | SUBNET     |                  ADDRESS                   |     TOKEN     |     BALANCE     |    NETWORK    |
+--------+--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
| stored | ewoq               | testblockchain | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x7DD1.) |               0 | Local Network |
+        +                    +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | LUExchange-Chain    | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x5DB9.) | 100000.000000000| Local Network |
+        +--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
|        | blockchain  | testblockchain | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x7DD1.) |               0 | Local Network |
+        + _airdrop           +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | LUExchange-Chain    | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x5DB9.) |               0 | Local Network |
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
```

## Transfer the Token from LUExchange-Chain to Our Lux L1

Now we will transfer 100 TOK tokens from our `ewoq` address in LUExchange-Chain to blockchain_airdrop
address in our Lux L1 `testblockchain`. Note that we will be using the Home contract address `0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D`
and Remote contract address `0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0`.

```bash
lux key transfer
✔ Local Network
✔ LUExchange-Chain
✔ Subnet testblockchain
Enter the address of the Bridge on c-chain: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D
Enter the address of the Bridge on testblockchain: 0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0
✔ ewoq
✔ Key
✔ blockchain_airdrop
Amount to send (TOKEN units): 100
```

## Verify That Transfer Is Successful

We will call `lux key list` command again to verify that the transfer is successful.

`blockchain_airdrop` should now have 100 TOK tokens in our Lux L1 `testblockchain` and our EWOQ
account now has 99900 TOK tokens in LUExchange-Chain.

```bash
lux key list --local --keys ewoq,blockchain_airdrop --subnets c,testblockchain --tokens 0x5DB9A7629912EBF95876228C24A848de0bfB43A9,0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
|  KIND  |        NAME        | SUBNET     |                  ADDRESS                   |     TOKEN     |     BALANCE     |    NETWORK    |
+--------+--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
| stored | ewoq               | testblockchain | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x7DD1.) |               0 | Local Network |
+        +                    +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | LUExchange-Chain    | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x5DB9.) | 99900.000000000 | Local Network |
+        +--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
|        | blockchain  | testblockchain | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x7DD1.) |   100.000000000 | Local Network |
+        + _airdrop           +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | LUExchange-Chain    | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x5DB9.) |               0 | Local Network |
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
```

And that's it! You have now successfully completed your first transfer from LUExchange-Chain to Lux L1 
using Teleporter Token Bridge!


# Import an Lux L1 (/docs/tooling/avalanche-cli/guides/import-avalanche-l1)

---
title: Import an Lux L1
description: Learn how to import an Lux-l1 into Lux-CLI.
---
Context[​](#context "Direct link to heading")
---------------------------------------------

In previous instances, Lux L1s might have been manually created through transaction issuance to node APIs, whether it was done using a local node or public API nodes. However, the current focus is on integrating Lux-CLI.

To achieve this integration, this guide demonstrates the process of importing an Lux L1 to the Lux-CLI to enable better management of the Lux L1's configuration. This how-to uses the BEAM Lux L1 deployed on Testnet Testnet as the example Lux L1.

Requirements[​](#requirements "Direct link to heading")
-------------------------------------------------------

For the import to work properly, you need:

- The Lux L1's genesis file, stored on disk
    
- The Lux L1's SubnetID
    

Import the Lux L1[​](#import-the-lux-l1 "Direct link to heading")
-----------------------------------------------------------------

For these use cases, Lux-CLI now supports the `import public` command.

Start the import by issuing

```
lux blockchain import public
```

The tool prompts for the network from which to import. The invariant assumption here is that the network is a public network, either the Testnet testnet or Mainnet. In other words, importing from a local network isn't supported.

```
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to import from:
  ▸ Testnet
    Mainnet
```

As stated earlier, this is from Testnet, so select it. As a next step, Lux-CLI asks for the path of the genesis file on disk:

```
✗ Provide the path to the genesis file: /tmp/subnet_evm.genesis.json
```

The wizard checks if the file at the provided path exists, refer to the checkmark at the beginning of the line:

```
✔ Provide the path to the genesis file: /tmp/subnetevm_genesis.json
```

Subsequently, the wizard asks if nodes have already been deployed for this Lux L1.

```
Use the arrow keys to navigate: ↓ ↑ → ←
? Have nodes already been deployed to this subnet?:
    Yes
  ▸ No
```

### Nodes are Already Validating This Lux L1[​](#nodes-are-already-validating-this-lux-l1 "Direct link to heading")

If nodes already have been deployed, the wizard attempts to query such a node for detailed data like the VM version. This allows the tool to skip querying GitHub (or wherever the VM's repository is hosted) for the VM's version, but rather we'll get the exact version which is actually running on the node.

For this to work, a node API URL is requested from the user, which is used for the query. This requires that the node's API IP and port are accessible from the machine running Lux-CLI, or the node is obviously not reachable, and thus the query times out and fails, and the tool exits. The node should also be validating the given Lux L1 for the import to be meaningful, otherwise, the import fails with missing information.

If the query succeeded, the wizard jumps to prompt for the Lux L1 ID (SubnetID).

```
Please provide an API URL of such a node so we can query its VM version (e.g. http://111.22.33.44:5555): http://154.42.240.119:9650
What is the ID of the subnet?: ie1wUBR2bQDPkGCRf2CBVzmP55eSiyJsFYqeGXnTYt2r33aKW
```

The rest of the wizard is identical to the next section, except that there is no prompt for the VM version anymore.

### Nodes Aren't Yet Validating this Lux L1, the Nodes API URL are Unknown, or Inaccessible (Firewalls)[​](#nodes-arent-yet-validating-this-lux-l1-the-nodes-api-url-are-unknown-or-inaccessible-firewalls "Direct link to heading")

If you don't have a node's API URL at hand, or it's not reachable from the machine running Lux-CLI, or maybe no nodes have even been deployed yet because only the `CreateSubnet` transaction has been issued, for example, you can query the public APIs.

You can't know for sure what Lux L1 VM versions the validators are running though, therefore the tool has to prompt later. So, select `No` when the tool asks for deployed nodes:

Thus, at this point the wizard requests the Lux L1's ID, without which it can't know what to import. Remember the ID is different on different networks.

From the [Testnet Lux L1 Explorer](https://subnets-test.lux.network/beam) you can see that BEAM's Lux L1 ID (SubnetID) is `ie1wUBR2bQDPkGCRf2CBVzmP55eSiyJsFYqeGXnTYt2r33aKW`:

```
✔ What is the ID of the subnet?: ie1wUBR2bQDPkGCRf2CBVzmP55eSiyJsFYqeGXnTYt2r33aKW
```

Notice the checkmark at line start, it signals that there is ID format validation.

If you hit `enter` now, the tool queries the public APIs for the given network, and if successful, it prints some information about the Lux L1, and proceeds to ask about the Lux L1's type:

```
Getting information from the Testnet network...
Retrieved information. BlockchainID: y97omoP2cSyEVfdSztQHXD9EnfnVP9YKjZwAxhUfGbLAPYT9t, Name: BEAM, VMID: kLPs8zGsTVZ28DhP1VefPCFbCgS7o5bDNez8JUxPVw9E6Ubbz
Use the arrow keys to navigate: ↓ ↑ → ←
? What's this VM's type?:
  ▸ Subnet-EVM
    Custom
```

Lux-CLI needs to know the VM type, to hit its repository and select what VM versions are available. This works automatically for Lux Network VMs (like Subnet-EVM).

Custom VMs aren't supported yet at this point, but are next on the agenda.

As the import is for BEAM, and you know that it's a Subnet-EVM type, select that.

The tool then queries the (GitHub) repository for available releases, and prompts the user to pick the version she wants to use:

```
✔ Subnet-EVM
Use the arrow keys to navigate: ↓ ↑ → ←
? Pick the version for this VM:
  ▸ v0.4.5
    v0.4.5-rc.1
    v0.4.4
    v0.4.4-rc.0
↓   v0.4.3
```

There is only so much the tool can help here, the Lux L1 manager/administrator should know what they want to use Lux-CLI for, how, and why they're importing the Lux L1.

It's crucial to understand that the correct versions are only known to the user. The latest might be usually fine, but the tool can't make assumptions about it easily. This is why it's indispensable that the wizard prompts the user, and the tool requires her to choose.

If you selected to query an actual Lux L1 validator, not the public APIs, in the preceding step. In such a scenario, the tool skips this picking.

```
✔ v0.4.5
Subnet BEAM imported successfully
```

The choice finalizes the wizard, which hopefully signals that the import succeeded. If something went wrong, the error messages provide cause information. This means you can now use Lux-CLI to handle the imported Lux L1 in the accustomed way. For example, you could deploy the BEAM Lux L1 locally.

For a complete description of options, flags, and the command, visit the [command reference](/docs/tooling/cli-commands#lux-l1-import).

# Run with Docker (/docs/tooling/avalanche-cli/guides/run-with-docker)

---
title: Run with Docker
description: Instructions for running Lux-CLI in a Docker container.
---

To run Lux-CLI in a docker container, you need to enable ipv6.

Edit `/etc/docker/daemon.json`. Add this snippet then restart the docker service.

```json
{
  "ipv6": true,
  "fixed-cidr-v6": "fd00::/80"
}
```


# Add Validator (/docs/tooling/avalanche-cli/maintain/add-validator-l1)

---
title: Add Validator
description:  Learn how to add a validator to an Lux L1.
---


### Add a Validator to an Lux L1

```bash
lux blockchain addValidator <blockchainName>
```

#### Choose Network
Choose the network where the operation will be

```bash
? Choose a network for the operation: 
  ▸ Local Network
    Devnet
    Testnet Testnet
    Mainnet
```

#### Choose Platform-Chain Fee Payer

Choose the key that will be used to pay for the transaction fees on the Platform-Chain.

```bash
? Which key should be used to pay for transaction fees on Platform-Chain?: 
  ▸ Use stored key
    Use ledger
```

#### Enter Node ID

Enter the NodeID of the node you want to add as a blockchain validator.

```bash
✗ What is the NodeID of the node you want to add as a blockchain validator?:  
```

<Callout>
You can find the NodeID in the node's configuration file or the console when first started with luxgo.
An example of a NodeID is `NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg`
</Callout>

#### Enter the BLS Public Key

Enter the public key of the node's BLS

```bash
Next, we need the public key and proof of possession of the node's BLS
Check https://build.lux.network/docs/rpcs/other/info-rpc#infogetnodeid for instructions on calling info.getNodeID API
✗ What is the node's BLS public key?:
```

<Callout>
You can find the BLS public key in the node's configuration file or the console when first started with luxgo.
</Callout>

#### Enter BLS Proof of Possession

Enter the proof of possession of the node's BLS

```bash
✗ What is the node's BLS proof of possession?:
```

<Callout>
You can find the BLS proof of possession in the node's configuration file or the console when first started with luxgo.
</Callout>

#### Enter LUX Balance

This balance will be used to pay the Platform-Chain continuous staking fee.

```bash
✗ What balance would you like to assign to the validator (in LUX)?: 
```

#### Enter Leftover LUX Address

This address will receive any leftover LUX when the node is removed from the validator set.

```bash
? Which key would you like to set as change owner for leftover LUX if the node is removed from validator set?: 
 ▸ Get address from an existing stored key (created from lux key create or lux key import)
    Custom
```

#### Enter Disable Validator Address

This address will be able to disable the validator using Platform-Chain transactions.

```bash
 Which address do you want to be able to disable the validator using Platform-Chain transactions?: 
  ▸ Get address from an existing stored key (created from lux key create or lux key import)
    Custom
```

### Proof of Stake specific parameters

If your network was created with Proof of Stake validator manager, you will be asked for the following additional parameters. You can also pass these parameters as flags to the command.

```bash
--delegation-fee uint16                delegation fee (in bips)
--stake-amount uint                    amount of native tokens to stake
--staking-period duration              how long this validator will be staking
```


# Delete an Lux L1 (/docs/tooling/avalanche-cli/maintain/delete-avalanche-l1)

---
title: Delete an Lux L1
description:  Learn how to delete an Lux L1.
---

Deleting an Lux L1 Configuration[​](#deleting-a-lux-l1-configuration "Direct link to heading")
---------------------------------------------------------------------------------------------

To delete a created Lux L1 configuration, run:

```bash
lux blockchain delete <blockchainName>
```

Deleting a Deployed Lux L1[​](#deleting-a-deployed-lux-l1 "Direct link to heading")
-----------------------------------------------------------------------------------

You can't delete Lux L1s deployed to Mainnet or the Testnet Testnet.

However, you may delete Lux L1s deployed to a local network by cleaning the network state with below command:

```bash
lux network clean
```



# Remove Validator (/docs/tooling/avalanche-cli/maintain/remove-validator-l1)

---
title: Remove Validator
description:  Learn how to remove a validator from an Lux L1.
---

### Remove a Validator from an Lux L1

```bash
lux blockchain removeValidator <blockchainName>
```

#### Choose the Network
Choose the network where the validator is registered.
```bash
? Choose a network for the operation: 
  ▸ Local Network
    Devnet
    Testnet Testnet
    Mainnet
```

#### Choose Platform-Chain fee payer
Choose the key to pay for the transaction fees on the Platform-Chain.
```bash
? Which key should be used to pay for transaction fees on Platform-Chain?: 
  ▸ Use stored key
    Use ledger
```

#### Enter Node-ID of the Validator to Remove
Enter the Node-ID of the validator you want to remove.
```bash
✗ What is the NodeID of the node you want to remove as a blockchain validator?: 
```
<Callout>
You can find the NodeID in the node's configuration file or the console when first started with luxgo.
An example of a NodeID is `NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg`
</Callout>

#### Confirm the removal
```bash
Validator manager owner 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC pays for the initialization of the validator's removal (Blockchain gas token)
RPC Endpoint: http://127.0.0.1:9652/ext/bc/2qmU6w47Mp7D7fGhbRuZm6Z1Nn6FZXZAxKpaeTMFiRQW9CBErh/rpc
Forcing removal of NodeID-7cQrriPWGXa5yuJGZUgsxxwH9j4T8pPkY as it is a PoS bootstrap validator
Using validationID: 228zzCgDmAmuaJDGnFkFgnVqbbJPRF7qF1Xpd3dhtqGDhMjJK2 for nodeID: NodeID-7cQrriPWGXa5yuJGZUgsxxwH9j4T8pPkY
ValidationID: 228zzCgDmAmuaJDGnFkFgnVqbbJPRF7qF1Xpd3dhtqGDhMjJK2
SetSubnetValidatorWeightTX fee: 0.000078836 LUX
SetSubnetValidatorWeightTx ID: 2FUimPZ37DscPJiQDLrtKtumER3LNr48MJi6VR2jGXkYEKpCaq
✓ Validator successfully removed from the Subnet
```


### Proof of Authority Networks
<Callout>
If the network is a Proof of Authority network, the validator must be removed from the network by the Validator Manager owner.
</Callout>

### Proof of Stake Networks
<Callout>
If the network is a Proof of Stake network, the validator must be removed by the initial staker. Rewards will be distributed to the validator after the removal.
It is important to note that the initial PoS Validator set are treated as bootstrap validators and are not elgible for rewards.
</Callout>

# Troubleshooting (/docs/tooling/avalanche-cli/maintain/troubleshooting)

---
title: Troubleshooting
description: If you run into trouble deploying your Lux L1, use this document for tips to resolve common issues.
---

Deployment Times Out[​](#deployment-times-out "Direct link to heading")
-----------------------------------------------------------------------

During a local deployment, your network may fail to start. Your error may look something like this:

```bash
[~]$ lux blockchain deploy myblockchain

✔ Local Network
Deploying [myblockchain] to Local Network
Backend controller started, pid: 26388, output at: /Users/user/.lux-cli/runs/server_20221231_111605/lux-cli-backend
VMs ready.
Starting network...
..................................................................................
..................................................................................
......Error: failed to query network health: rpc error: code = DeadlineExceeded desc = context deadline exceeded
```

Lux-CLI only supports running one local Lux network at a time. If other instances of LuxGo are running concurrently, your Lux-CLI network fails to start.

To test for this error, start by shutting down any Lux nodes started by Lux-CLI.

```bash
lux network clean --hard
```

Next, look for any lingering LuxGo processes with:

```bash
ps aux | grep luxgo
```

If any processes are running, you need to stop them before you can launch your VM with Lux-CLI.

<Callout type="warn">
If you're running a validator node on the same box you're using Lux-CLI, **don't** end any of these lingering LuxGo processes. This may shut down your validator and could affect your validation uptime.
</Callout>


Incompatible RPC Version for Custom VM[​](#incompatible-rpc-version-for-custom-vm "Direct link to heading")
-----------------------------------------------------------------------------------------------------------

If you're locally deploying a custom VM, you may run into this error message.

```bash
[~]$ lux blockchain deploy myblockchain

✔ Local Network
Deploying [myblockchain] to Local Network
Backend controller started, pid: 26388, output at: /Users/user/.lux-cli/runs/server_20221231_111605/lux-cli-backend
VMs ready.
Starting network...
.........
Blockchain has been deployed. Wait until network acknowledges...
..................................................................................
..................................................................................
......Error: failed to query network health: rpc error: code = DeadlineExceeded desc = context deadline exceeded
```

This error has many possible causes, but a common cause is usually due to **an RPC protocol version mismatch.**

LuxGo communicates with custom VMs over RPC using [gRPC](https://grpc.io/). gRPC defines a protocol specification shared by both LuxGo and the VM. **Both components must be running the same RPC version for VM deployment to work.**

Your custom VM's RPC version is set by the version of LuxGo that you import. By default, Lux-CLI creates local Avalalanche networks that run the latest LuxGo release.

### Example[​](#example "Direct link to heading")

Here's an example with real numbers from the LuxGo compatibility page:

- If the latest LuxGo release is version v1.10.11, then Lux-CLI deploys a network with RPC version 28.
- For your deploy to be successful, your VM must also have RPC version 28. Because only LuxGo versions v1.10.9, v1.10.10 and v1.10.11 supports RPC version 28, your VM **must** import one of those versions.

### Solution[​](#solution "Direct link to heading")

Error: `RPCChainVM protocol version mismatch between LuxGo and Virtual Machine plugin`

This error occurs when the RPCChainVM protocol version used by VMs like Subnet-EVM are incompatible with the protocol version of LuxGo.

If your VM has an RPC version mismatch, you have two options:

1.  Update the version of LuxGo you use in your VM. This is the correct long-term approach.
2.  Use Lux-CLI to deploy an older version of LuxGo by using the `--luxgo-version` flag. Both the [`blockchain deploy`](/docs/tooling/cli-commands#deploy) and [`network start`](/docs/tooling/cli-commands#start) commands support setting the LuxGo version explicitly.

Although it's very important to keep your version of LuxGo up-to-date, this workaround helps you avoid broken builds in the short term.

<Callout type="warn">
You must upgrade to the latest LuxGo version when deploying publicly to Testnet Testnet or Lux Mainnet.
</Callout>


### More Information[​](#more-information "Direct link to heading")

Similar version matching is required in different tools on the ecosystem. Here is a compatibility table showing which RPCChainVM Version implements the more recent releases of LuxGo, Subnet-EVM, Precompile-EVM and HyperSDK.

|RPCChainVM|LuxGo       |Subnet-EVM     |Precompile-EVM |HyperSDK        |
|----------|------------------|---------------|---------------|----------------|
|26        |v1.10.1-v1.10.4   |v0.5.1-v0.5.2  |v0.1.0-v0.1.1  |v0.0.6-v0.0.9   |
|27        |v1.10.5-v1.10.8   |v0.5.3         |v0.1.2         |v0.0.10-v0.0.12 |
|28        |v1.10.9-v1.10.12  |v0.5.4-v0.5.6  |v0.1.3-v0.1.4  |v0.0.13-v0.0.15 |
|30        |v1.10.15-v1.10.17 |v0.5.9-v0.5.10 |v0.1.6-v0.1.7  |-               |
|29        |v1.10.13-v1.10.14 |v0.5.7-v0.5.8  |v0.1.5         |-               |
|31        |v1.10.18- v1.10.19|v0.5.11        |v0.1.8         |v0.0.16 (latest)|
|33        |v1.11.0           |v0.6.0-v0.6.1  |v0.2.0         |-               |
|34        |v1.11.1- v1.11.2  |v0.6.2         |-              |-               |
|35        |v1.11.3 (latest)  |v0.6.3 (latest)|v0.2.1 (latest)|-               |


You can view the full RPC compatibility broken down by release version for each tool here:

[LuxGo](https://github.com/luxfi/luxgo/blob/master/version/compatibility.json).

[Subnet-EVM](https://github.com/luxfi/subnet-evm/blob/master/compatibility.json).

[Precompile-EVM](https://github.com/luxfi/precompile-evm/blob/main/compatibility.json).

<Callout title="Note">
Updates to LuxGo's RPC version are **not** tied to its semantic version scheme. Minor LuxGo version bumps may include a breaking RPC version bump.
</Callout>

Fix for MacBook Air M1/M2: ‘Bad CPU type in executable' Error[​](#fix-for-macbook-air-m1m2-bad-cpu-type-in-executable-error "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------------------------------------------

When running `lux blockchain deploy` via the Lux-CLI, the terminal may throw an error that contains the following:

```bash
zsh: bad CPU type in executable:
/Users/user.name/Downloads/build/luxgo
```

This is because some Macs lack support for x86 binaries. Running the following command should fix this issue:

```bash
/usr/sbin/softwareupdate --install-rosetta
```


# View Lux L1s (/docs/tooling/avalanche-cli/maintain/view-avalanche-l1s)

---
title: View Lux L1s
description: CLI commands for viewing lux-l1s.
---

## List Lux L1 Configurations

You can list the Lux L1s you've created with: `lux blockchain list`

Example:

```bash
> lux blockchain list
+--------------+--------------+----------+---------------------------------------------------+------------+------------+-----------+
|    SUBNET    |    CHAIN     | CHAINID  |                       VMID                        |    TYPE    | VM VERSION | FROM REPO |
+--------------+--------------+----------+---------------------------------------------------+------------+------------+-----------+
| myblockchain | myblockchain |      111 | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV | Subnet-EVM | v0.7.0     | false     |
+--------------+--------------+----------+---------------------------------------------------+------------+------------+-----------+
```

To see detailed information about your deployed Lux L1s, add the `--deployed` flag:

```bash
> lux blockchain list --deployed
+--------------+--------------+---------------------------------------------------+---------------+----------------+---------+
|    SUBNET    |    CHAIN     |                       VM ID                       | LOCAL NETWORK | FUJI (TESTNET) | MAINNET |
+--------------+--------------+---------------------------------------------------+---------------+----------------+---------+
| myblockchain | myblockchain | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV | Yes           | No             | No      |
+--------------+--------------+---------------------------------------------------+---------------+----------------+---------+

```bash

## Describe Lux L1 Configurations

To see the details of a specific configuration, run: `lux blockchain describe <blockchainName>`

Example:

```bash
> lux blockchain describe myblockchain

+---------------------------------------------------------------------------------------------------------------------------------+
|                                                           MYBLOCKCHAIN                                                          |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| Name          | myblockchain                                                                                                    |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV                                                               |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| VM Version    | v0.7.0                                                                                                          |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| Validation    | Proof Of Authority                                                                                              |
+---------------+--------------------------+--------------------------------------------------------------------------------------+
| Local Network | ChainID                  | 12345                                                                                |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | SubnetID                 | fvx83jt2BWyibBRL4SRMa6WzjWp7GSFUeUUeoeBe1AqJ5Ey5w                                    |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | BlockchainID (CB58)      | 2QGB9GbEhsFJLSRVii2mKs8dxugHzmK98G5391P2bvXSCb4sED                                   |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | BlockchainID (HEX)       | 0xb883b54815c84a3f0903dbccd289ed5563395dd61c189db626e2d2680546b990                   |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | RPC Endpoint             | http://127.0.0.1:60538/ext/bc/2QGB9GbEhsFJLSRVii2mKs8dxugHzmK98G5391P2bvXSCb4sED/rpc |
+---------------+--------------------------+--------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------+
|                                         ICM                                        |
+---------------+-----------------------+--------------------------------------------+
| Local Network | ICM Messenger Address | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf |
|               +-----------------------+--------------------------------------------+
|               | ICM Registry Address  | 0x695Ea5FbeBBdc99cA679F5fD7768f179d2281d74 |
+---------------+-----------------------+--------------------------------------------+

+-------------------------------+
|           TOKEN               |
+--------------+----------------+
| Token Name   | TUTORIAL Token |
+--------------+----------------+
| Token Symbol | TUTORIAL       |
+--------------+----------------+

+----------------------------------------------------------------------------------------------------------------------------------------+
|                                                        INITIAL TOKEN ALLOCATION                                                        |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+
| DESCRIPTION             | ADDRESS AND PRIVATE KEY                                          | AMOUNT (OWEN) | AMOUNT (WEI)              |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+
| Main funded account     | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000       | 1000000000000000000000000 |
| ewoq                    | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |               |                           |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+
| Used by ICM             | 0x001CBe3650FAD190d9ccBd57b289124F5131AA57                       | 600           | 600000000000000000000     |
| cli-teleporter-deployer | d00b93e1526d05a30b681911a3e0f5e5528add205880c1cafa4f84cdb2746b00 |               |                           |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+

+-----------------------------------------------------------------------------------------------------------------+
|                                                 SMART CONTRACTS                                                 |
+-----------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION           | ADDRESS                                    | DEPLOYER                                   |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin           | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+-----------------------+--------------------------------------------+--------------------------------------------+
| PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy     | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

+--------------------------------------------------------------------------+
|                                   NODES                                  |
+-------+------------------------------------------+-----------------------+
| NAME  | NODE ID                                  | LOCALHOST ENDPOINT    |
+-------+------------------------------------------+-----------------------+
| node1 | NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg | http://127.0.0.1:9650 |
+-------+------------------------------------------+-----------------------+
| node2 | NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ | http://127.0.0.1:9652 |
+-------+------------------------------------------+-----------------------+

+--------------------------------------------------------------------------------------------------------+
|                                            WALLET CONNECTION                                           |
+-----------------+--------------------------------------------------------------------------------------+
| Network RPC URL | http://127.0.0.1:60538/ext/bc/2QGB9GbEhsFJLSRVii2mKs8dxugHzmK98G5391P2bvXSCb4sED/rpc |
+-----------------+--------------------------------------------------------------------------------------+
| Network Name    | myblockchain                                                                         |
+-----------------+--------------------------------------------------------------------------------------+
| Chain ID        | 12345                                                                                |
+-----------------+--------------------------------------------------------------------------------------+
| Token Symbol    | TUTORIAL                                                                             |
+-----------------+--------------------------------------------------------------------------------------+
| Token Name      | TUTORIAL Token                                                                       |
+-----------------+--------------------------------------------------------------------------------------+

```

## Viewing a Genesis File

If you'd like to see the raw genesis file, supply the `--genesis` flag to the describe command: `lux blockchain describe <blockchainName> --genesis`

Example:

```bash
> lux blockchain describe myblockchain --genesis

{
    "config": {
        "berlinBlock": 0,
        "byzantiumBlock": 0,
        "chainId": 111,
        "constantinopleBlock": 0,
        "eip150Block": 0,
        "eip155Block": 0,
        "eip158Block": 0,
        "feeConfig": {
            "gasLimit": 12000000,
            "targetBlockRate": 2,
            "minBaseFee": 25000000000,
            "targetGas": 60000000,
            "baseFeeChangeDenominator": 36,
            "minBlockGasCost": 0,
            "maxBlockGasCost": 1000000,
            "blockGasCostStep": 200000
        },
        "homesteadBlock": 0,
        "istanbulBlock": 0,
        "londonBlock": 0,
        "muirGlacierBlock": 0,
        "petersburgBlock": 0,
        "warpConfig": {
            "blockTimestamp": 1734549536,
            "quorumNumerator": 67,
            "requirePrimaryNetworkSigners": true
        }
    },
    "nonce": "0x0",
    "timestamp": "0x67632020",
    "extraData": "0x",
    "gasLimit": "0xb71b00",
    "difficulty": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x0000000000000000000000000000000000000000",
    "alloc": {
        "001cbe3650fad190d9ccbd57b289124f5131aa57": {
            "balance": "0x2086ac351052600000"
        },
        "0c0deba5e0000000000000000000000000000000": {
            "code": "<PoA validator manager deployed bytecode>",
            "balance": "0x0",
            "nonce": "0x1"
        },
        "0feedc0de0000000000000000000000000000000": {
            "code": "<transparent proxy deployed bytecode>",
            "storage": {
                "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc": "0x0000000000000000000000000c0deba5e0000000000000000000000000000000", //sslot for proxy implementation
                "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103": "0x000000000000000000000000c0ffee1234567890abcdef1234567890abcdef34"  //sslot for proxy admin
            },
            "balance": "0x0",
            "nonce": "0x1"
        },
        "8db97c7cece249c2b98bdc0226cc4c2a57bf52fc": {
            "balance": "0xd3c21bcecceda1000000"
        },
        "c0ffee1234567890abcdef1234567890abcdef34": {
            "code": "<proxy admin deployed bytecode>",
            "storage": {
                "0x0000000000000000000000000000000000000000000000000000000000000000": "0x0000000000000000000000008db97c7cece249c2b98bdc0226cc4c2a57bf52fc" //sslot for owner
            },
            "balance": "0x0",
            "nonce": "0x1"
        }
    },
    "airdropHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "airdropAmount": null,
    "number": "0x0",
    "gasUsed": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "baseFeePerGas": null,
    "excessBlobGas": null,
    "blobGasUsed": null
}
```

# Ledger Platform-Chain Transfer (/docs/tooling/avalanche-cli/transactions/ledger-p-chain-transfer)

---
title: Ledger Platform-Chain Transfer
description: Transferring funds between Platform-Chain using Lux CLI.
---

Transferring funds between Platform-Chain wallets becomes necessary in certain situations:

1.  Funds need to be sent to the Lux L1 control key, which might have a zero balance due to fee payments. The Lux L1 control key requires funding to ensure proper support for Lux L1 operations.
2.  Funds need to be moved from one Ledger address index to another. A Ledger manages an infinite sequence of addresses all derived from a master private key and can sign for any of those addresses. Each one is referred to by an index, or the associated address. Lux-CLI usually expects to use index 0, but sometimes, the funds are in a different index. Occasionally, a transfer made to a ledger can be made to an address different from the default one used by the CLI.

To enable direct transfers between Platform-Chain addresses, use the command `lux key transfer`. This operation involves a series of import/export actions with the Platform-Chain and Exchange-Chain. The fee for this operation is four times the typical import operation fee, which comes out to 0.004 LUX. You can find more information about fees [here](/docs/rpcs/other/guides/txn-fees).

<Callout title="Note">
The `key transfer` command can also be applied to the stored keys managed by the CLI. It enables moving funds from one stored key to another, and from a ledger to a stored key or the other way.
</Callout>

This how-to guide focuses on transferring funds between ledger accounts.

## Prerequisites

- [`Lux-CLI`](/docs/tooling/lux-cli) installed
- Multiple Ledger devices [configured for Lux](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-on-mainnet#setting-up-your-ledger)

Example: Sending All Funds From One Ledger to Another[​](#example-sending-all-funds-from-one-ledger-to-another "Direct link to heading")
----------------------------------------------------------------------------------------------------------------------------------------

- Source address: ledger A, index 2 (the web wallet shows 4.5 LUX for this ledger)
- Target address: ledger B, index 0 (the web wallet shows 0 LUX for this ledger)

### Determine Sender Address Index[​](#determine-sender-address-index "Direct link to heading")

A ledger can manage an infinite amount of addresses derived from a main private key. Because of this, many operations require the user to specify an address index.

After confirming with a web wallet that 4.5 LUX is available on p-chain address `P-lux10an3cucdfqru984pnvv6y0rspvvclz63e523m0`, connect ledger A.

With the lux app running, execute:

```bash
lux key list --mainnet --ledger 0,1,2,3,4,5
```

To see p-chain addresses and balances for the first 6 indices in the ledger derived owner addresses.

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | Platform-Chain (Bech32 format) | P-lux1g8yucm7j0cnwwru4rp5lkzw6dpdxjmc2rfkqs9 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 1 |                         | P-lux1drppshkst2ccygyq37m2z9e3ex2jhkd2txcm5r |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 2 |                         | P-lux10an3cucdfqru984pnvv6y0rspvvclz63e523m0 |     4.5 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 3 |                         | P-lux1yfpm7v5y5rej2nu7t2r0ffgrlpfq36je0rc5k6 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 4 |                         | P-lux17nqvwcqsa8ddgeww8gzmfe932pz2syaj2vyd89 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 5 |                         | P-lux1jzvnd05vsfksrtatm2e3rzu6eux9a287493yf8 |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

The address `P-lux10an3cucdfqru984pnvv6y0rspvvclz63e523m0` has 4.5 LUX and is associated with index 2 of ledger A.

### Determine Receiver Address Index[​](#determine-receiver-address-index "Direct link to heading")

In this case the user wants to use index 0, the one CLI by default expects to contain funds.

For the transfer command, it is also needed to know the target p-chain address. Do the following to obtain it:

With the ledger B connected and the avalache app running, execute:

```bash
lux key list --mainnet --ledger 0
```

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | Platform-Chain (Bech32 format) | P-lux1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

Target address to be used is `P-lux1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm`, containing 0 funds.

### Send the Transfer[​](#send-the-transfer "Direct link to heading")

A Platform-Chain to P-chain transfer is a two-part operation. There is no need for the two parts to be executed on the same machine, only for them to have some common params. For each part, the appropriate ledger (either source or target) must be connected to the machine executing it.

The first step moves the money out of the source account into a Exchange-Chain account owner by the receiver. It needs to be signed by the sending ledger.

Enter the amount of LUX to send to the recipient. This amount does not include fees.

Note that the sending ledger pays all the fees.

Then start the command:

```bash
lux key transfer
```

First step is to specify the network. `Mainnet` in this case:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Network to use:
  ▸ Mainnet
    Testnet
    Local Network
```

Next, the step of the transfer must be specified. Send in this case:

```bash
? Step of the transfer:
  ▸ Send
    Receive
```

Next, the key source for the sender address. That is, the key that is going to sign the sending transactions. Select `Use ledger`:

```bash
? Which key source should be used to  for the sender address?:
    Use stored key
  ▸ Use ledger
```

Next, the ledger index is asked for. Input `2`:

```bash
✗ Ledger index to use: 2
```

Next, the amount to be sent is asked for:

```bash
✗ Amount to send (LUX units): 4.496
```

The, the target address is required:

```bash
✗ Receiver address: P-lux1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm
```

After that, a confirmation message is printed. Read carefully and choose `Yes`:

```bash
this operation is going to:
- send 4.496000000 LUX from P-lux10an3cucdfqru984pnvv6y0rspvvclz63e523m0 to target address P-lux1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm
- take a fee of 0.004000000 LUX from source address P-lux10an3cucdfqru984pnvv6y0rspvvclz63e523m0

Use the arrow keys to navigate: ↓ ↑ → ←
? Confirm transfer:
    No
  ▸ Yes
```

After this, the first part is completed:

### Receive the Transfer[​](#receive-the-transfer "Direct link to heading")

In this step, Ledger B signs the transaction to receive the funds. It imports the funds on the Exchange-Chain before exporting them back to the desired Platform-Chain address.

Connect ledger B and execute lux app.

Then start the command:

```bash
lux key transfer
```

Specify the `Mainnet` network:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Network to use:
  ▸ Mainnet
    Testnet
    Local Network
```

Next, the step of the transfer must be specified. Receive in this case:

```bash
? Step of the transfer:
    Send
  ▸ Receive
```

Then, select Ledger as the key source that is going to sign the receiver operations.

```bash
? Which key source should be used to  for the receiver address?:
    Use stored key
  ▸ Use ledger
```

Next, the ledger index is asked for. Input `0`:

```bash
✗ Ledger index to use: 0
```

Next, the amount to receive is asked for:

```bash
✗ Amount to send (LUX units): 4.496
```

After that, a confirmation message is printed. Select `Yes`:

```bash
this operation is going to:
- receive 4.496000000 LUX at target address P-lux1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm:

Use the arrow keys to navigate: ↓ ↑ → ←
? Confirm transfer:
    No
  ▸ Yes
```

Finally, the second part of the operation is executed and the transfer is completed.

```bash
Issuing ImportTx P -> X
Issuing ExportTx X -> P
Issuing ImportTx X -> P
```

### Verifying Results of the Transfer Operation using `key list`[​](#verifying-results-of-the-transfer-operation-using-key-list "Direct link to heading")

First verify ledger A accounts. Connect ledger A and open the lux app:

```bash
lux key list --mainnet --ledger 0,1,2,3,4,5
```

With result:

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | Platform-Chain (Bech32 format) | P-lux1g8yucm7j0cnwwru4rp5lkzw6dpdxjmc2rfkqs9 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 1 |                         | P-lux1drppshkst2ccygyq37m2z9e3ex2jhkd2txcm5r |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 2 |                         | P-lux10an3cucdfqru984pnvv6y0rspvvclz63e523m0 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 3 |                         | P-lux1yfpm7v5y5rej2nu7t2r0ffgrlpfq36je0rc5k6 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 4 |                         | P-lux17nqvwcqsa8ddgeww8gzmfe932pz2syaj2vyd89 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 5 |                         | P-lux1jzvnd05vsfksrtatm2e3rzu6eux9a287493yf8 |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

Next, verify ledger B accounts. Connect ledger B and open the lux app:

```bash
lux key list --mainnet --ledger 0,1,2,3,4,5
```

With result:

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | Platform-Chain (Bech32 format) | P-lux1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm |   4.496 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 1 |                         | P-lux18e9qsm30du590lhkwydhmkfwhcc9999gvxcaez |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 2 |                         | P-lux1unkkjstggvdty5gtnfhc0mgnl7qxa52z2d4c9y |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 3 |                         | P-lux1ek7n0zky3py7prxcrgnmh44y3wm6lc7r7x5r8e |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 4 |                         | P-lux1rsz6nt6qht5ep37qjk7ht0u9h30mgfhehsmqea |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 5 |                         | P-lux17u5wm4tfex7xr27xlwejm28pyk84tj0jzp42zz |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

### Recovery Steps[​](#recovery-steps "Direct link to heading")

As a multi step operation, the receiving part of the transfer can have intermediate errors, due for example to temporal network connections on the client side.

The CLI is going to capture errors and provide the user with a recovery message of the kind:

```bash
ERROR: restart from this step by using the same command with extra arguments: --receive-recovery-step 1
```

If this happen, the receiving operation should be started the same way, choosing the same options, but adding the extra suggested parameter:

```bash
lux key transfer --receive-recovery-step 1
```

Then, the CLI is going to resume where it left off.

# Send LUX on C/Platform-Chain (/docs/tooling/avalanche-cli/transactions/native-send)

---
title: Send LUX on C/Platform-Chain
description: Learn how to execute a native transfer on the C or Platform-Chain using the Lux CLI.
---

# Prerequisites

- Install the [Lux CLI](/docs/tooling/lux-cli).
- Use the CLI to [create a key](/docs/tooling/cli-commands#key-create).
- Fund the key with LUX. You can use the [faucet](https://test.core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `devrel-lux-0112` to get testnet LUX. 
- *Optionally*, you can [export](/docs/tooling/cli-commands#key-export) your private key for use in scripting or other tools. 

## Initiate the `transfer` Command and Walk Through the Prompts

In your terminal, run the following command:

```zsh
lux key transfer
```

<Callout title="Note">

This command and all of its flags are documented [here](/docs/tooling/cli-commands#key-transfer).

</Callout>

You will be prompted to answer the following questions:

```zsh
? On what Network do you want to execute the transfer?:
  ▸ Mainnet
    Testnet Testnet
    Devnet
    Local Network
```
<Accordions>
<Accordion title="Note: Devnet">
If you select "Devnet", you must input the RPC URL. If your devnet's LUExchange-Chain RPC is `https://demo.lux-dev.network/ext/bc/C/rpc`, you should input the URL as: 

```zsh
✔ Devnet Endpoint: https://demo.lux-dev.network
```

</Accordion>
</Accordions>

Select the chain you want to transfer funds from:

```zsh
? Where are the funds to transfer?:
  ▸ Platform-Chain
    LUExchange-Chain
    My blockchain isn't listed
```

Select the chain you want to transfer funds to:

```zsh
? Destination Chain:
  ▸ Platform-Chain
    Exchange-Chain
```

Select the step of the transfer process you want to execute:

```zsh
? Step of the transfer:
  ▸ Send
    Receive
```

<Callout title="Note">

If you are performing a native transfer where the sender and receiver address are on the same chain, you only need to complete a "send" transaction. 

If you wish to perform a cross-chain transfer (i.e. from C to Platform-Chain), you should abort this flow and reinitiate the command as `lux key transfer --fund-p-chain` or `lux key transfer --fund-x-chain`, completing both the "send" and "receive" flows with keys stored in the CLI.
You can fund your CLI-stored key with LUX on the LUExchange-Chain using the [faucet](https://test.core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `devrel-lux-0112`.

</Callout>

Select the sender address:

```zsh
? Which key should be used as the sender?:
  ▸ Use stored key
    Use ledger
? Which stored key should be used as the sender address?:
  ▸ DemoKey
    MyKey
    ewoq
```

Specify the amount to send, input the destination address: 
  
```zsh
✗ Amount to send (LUX units): 100
✗ Destination address: P-lux1zgjx8zj7z7zj7z7zj7z7zj7z7zj7zj7zj7zj7e
```

Review the transaction details and confirm/abort:

```zsh
this operation is going to:
- send 100.000000000 LUX from P-lux1gmuqt8xg9j4h88kj3hyprt23nf50azlfg8txn2 to destination address P-lux1f630gvct4ht35ragcheapnn2n5cv2tkmq73ec0
- take a fee of 0.001000000 LUX from source address P-lux1gmuqt8xg9j4h88kj3hyprt23nf50azlfg8txn2
? Confirm transfer:
    No
  ▸ Yes
```

After a successful transfer, you can check your CLI keys' balances with the [command](/docs/tooling/cli-commands#key-list): `lux key list`.


# Precompile Configs (/docs/tooling/avalanche-cli/upgrade/avalanche-l1-precompile-config)

---
title: Precompile Configs
description: Learn how to upgrade your Subnet-EVM precompile configurations.
---

You can customize Subnet-EVM based Lux L1s after deployment by enabling and disabling precompiles. To do this, create a `upgrade.json` file and place it in the appropriate directory.

This document describes how to perform such network upgrades. It's specific for Subnet-EVM upgrades.

The document [Upgrade an Lux L1](/docs/lux-l1s/upgrade/considerations) describes all the background information required regarding Lux L1 upgrades.

<Callout type="warn">
It's very important that you have read and understood the previously linked document. Failing to do so can potentially grind your network to a halt.
</Callout>

This tutorial assumes that you have already [installed](/docs/tooling/lux-cli) Lux-CLI. It assumes you have already created and deployed an Lux L1 called `testblockchain`.

Generate the Upgrade File[​](#generate-the-upgrade-file "Direct link to heading")
---------------------------------------------------------------------------------

The [Precompiles](/docs/lux-l1s/evm-configuration/customize-lux-l1#network-upgrades-enabledisable-precompiles) documentation describes what files the network upgrade requires, and where to place them.

To generate a valid `upgrade.json` file, run:

```bash
lux blockchain upgrade generate testblockchain
```

If you didn't create `testblockchain` yet, you would see this result:

```bash
lux blockchain upgrade generate testblockchain
The provided Lux L1 name "testblockchain" does not exist
```

Again, it makes no sense to try the upgrade command if the Lux L1 doesn't exist. If that's the case, please go ahead and [create](/docs/tooling/lux-cli) the Lux L1 first.

If the Lux L1 definition exists, the tool launches a wizard. It may feel a bit redundant, but you first see some warnings, to draw focus to the dangers involved:

```bash
lux blockchain upgrade generate testblockchain
Performing a network upgrade requires coordinating the upgrade network-wide.
A network upgrade changes the rule set used to process and verify blocks, such that any node that
upgrades incorrectly or fails to upgrade by the time that upgrade goes into effect may become
out of sync with the rest of the network.

Any mistakes in configuring network upgrades or coordinating them on validators may cause the
network to halt and recovering may be difficult.
Please consult
https://build.lux.network/docs/subnets/customize-a-subnet#network-upgrades-enabledisable-precompiles
for more information
Use the arrow keys to navigate: ↓ ↑ → ←
? Press [Enter] to continue, or abort by choosing 'no':
  ▸ Yes
    No
```

Go ahead and select `Yes` if you understand everything and you agree.

You see a last note, before the actual configuration wizard starts:

```bash
Luxgo and this tool support configuring multiple precompiles.
However, we suggest to only configure one per upgrade.

Use the arrow keys to navigate: ↓ ↑ → ←
? Select the precompile to configure:
  ▸ Contract Deployment Allow List
    Manage Fee Settings
    Native Minting
    Transaction Allow List
```

Refer to [Precompiles](/docs/lux-l1s/evm-configuration/customize-lux-l1#precompiles) for a description of available precompiles and how to configure them.

Make sure you understand precompiles thoroughly and how to configure them before attempting to continue.

For every precompile in the list, the wizard guides you to provide correct information by prompting relevant questions. For the sake of this tutorial, select `Transaction Allow List`. The document [Restricting Who Can Submit Transactions](/docs/lux-l1s/evm-configuration/customize-lux-l1#restricting-who-can-submit-transactions) describes what this precompile is about.

```bash
✔ Transaction Allow List
Set parameters for the "Manage Fee Settings" precompile
Use the arrow keys to navigate: ↓ ↑ → ←
? When should the precompile be activated?:
  ▸ In 5 minutes
    In 1 day
    In 1 week
    In 2 weeks
    Custom
```

This is actually common to all precompiles: they require an activation timestamp. If you think about it, it makes sense: you want a synchronized activation of your precompile. So think for a moment about when you want to set the activation timestamp to. You can select one of the suggested times in the future, or you can pick a custom one. After picking `Custom`, it shows the following prompt:

```bash
✔ Custom
✗ Enter the block activation UTC datetime in 'YYYY-MM-DD HH:MM:SS' format:
```

The format is `YYYY-MM-DD HH:MM:SS`, therefore `2023-03-31 14:00:00` would be a valid timestamp. Notice that the timestamp is in UTC. Please make sure you have converted the time from your timezone to UTC. Also notice the `✗` at the beginning of the line. The CLI tool does input validation, so if you provide a valid timestamp, the `x` disappears:

```bash
✔ Enter the block activation UTC datetime in 'YYYY-MM-DD HH:MM:SS' format: 2023-03-31 14:00:00
```

The timestamp must be in the **future**, so make sure you use such a timestamp should you be running this tutorial after `2023-03-31 14:00:00`.

After you provided the valid timestamp, proceed with the precompile specific configurations:

```bash
The chosen block activation time is 2023-03-31 14:00:00
Use the arrow keys to navigate: ↓ ↑ → ←
? Add 'adminAddresses'?:
  ▸ Yes
    No
```

This will enable the addresses added in this section to add other admins and/or add enabled addresses for transaction issuance. The addresses provided in this tutorial are fake.

<Callout type="warn">
However, make sure you or someone you trust have full control over the addresses. Otherwise, you might bring your Lux L1 to a halt.
</Callout>

```bash
✔ Yes
Use the arrow keys to navigate: ↓ ↑ → ←
? Provide 'adminAddresses':
  ▸ Add
    Delete
    Preview
    More Info
↓   Done
```

The prompting runs with a pattern used throughout the tool:

1. Select an operation:
    - `Add`: adds a new address to the current list
    - `Delete`: removes an address from the current list
    - `Preview`: prints the current list
2. `More info` prints additional information for better guidance, if available
3. Select `Done` when you completed the list

Go ahead and add your first address:

```bash
✔ Add
✔ Add an address: 0xaaaabbbbccccddddeeeeffff1111222233334444
```

Add another one:

```bash
✔ Add
Add an address: 0xaaaabbbbccccddddeeeeffff1111222233334444
✔ Add
✔ Add an address: 0x1111222233334444aaaabbbbccccddddeeeeffff
```

Select `Preview` this time to confirm the list is correct:

```bash
✔ Preview
0. 0xaaaAbbBBCccCDDddEeEEFFfF1111222233334444
1. 0x1111222233334444aAaAbbBBCCCCDdDDeEeEffff
Use the arrow keys to navigate: ↓ ↑ → ←
? Provide 'adminAddresses':
  ▸ Add
    Delete
    Preview
    More Info
↓   Done
```

If it looks good, select `Done` to continue:

```bash
✔ Done
Use the arrow keys to navigate: ↓ ↑ → ←
? Add 'enabledAddresses'?:
  ▸ Yes
    No
```

Add one such enabled address, these are addresses which can issue transactions:

```bash
✔ Add
✔ Add an address: 0x55554444333322221111eeeeaaaabbbbccccdddd█
```

After you added this address, and selected `Done`, the tool asks if you want to add another precompile:

```bash
✔ Done
Use the arrow keys to navigate: ↓ ↑ → ←
? Should we configure another precompile?:
  ▸ No
    Yes
```

If you needed to add another one, you would select `Yes` here. The wizard would guide you through the other available precompiles, excluding already configured ones.

To avoid making this tutorial too long, the assumption is you're done here. Select `No`, which ends the wizard.

This means you have successfully terminated the generation of the upgrade file, often called upgrade bytes. The tool stores them internally.

<Callout type="warn">
You shouldn't move files around manually. Use the `export` and `import` commands to get access to the files.
</Callout>

So at this point you can either:

- Deploy your upgrade bytes locally
- Export your upgrade bytes to a file, for installation on a validator running on another machine
- Import a file into a different machine running Lux-CLI

How To Upgrade a Local Network[​](#how-to-upgrade-a-local-network "Direct link to heading")
-------------------------------------------------------------------------------------------

The normal use case for this operation is that:

- You already created an Lux L1
- You already deployed the Lux L1 locally
- You already generated the upgrade file with the preceding command or imported into the tool
- This tool already started the network

If the preceding requirements aren't met, the network upgrade command fails.

Therefore, to apply your generated or imported upgrade configuration:

```bash
lux blockchain upgrade apply testblockchain
```

A number of checks run. For example, if you created the Lux L1 but didn't deploy it locally:

```bash
lux blockchain upgrade apply testblockchain
Error: no deployment target available
Usage:
  lux blockchain upgrade apply [blockchainName] [flags]

Flags:
      --luxgo-chain-config-dir string   luxgo's chain config file directory (default "/home/fabio/.luxgo/chains")
      --config                                create upgrade config for future Lux L1 deployments (same as generate)
      --testnet testnet                             apply upgrade existing testnet deployment (alias for `testnet`)
  -h, --help                                  help for apply
      --local local                           apply upgrade existing local deployment
      --mainnet mainnet                       apply upgrade existing mainnet deployment
      --print                                 if true, print the manual config without prompting (for public networks only)
      --testnet testnet                       apply upgrade existing testnet deployment (alias for `testnet`)

Global Flags:
      --log-level string   log level for the application (default "ERROR")
```

Go ahead and [deploy](/docs/tooling/lux-cli/create-deploy-lux-l1s/deploy-locally) first your Lux L1 if that's your case.

If you already had deployed the Lux L1 instead, you see something like this:

```bash
lux blockchain upgrade apply testblockchain
Use the arrow keys to navigate: ↓ ↑ → ←
? What deployment would you like to upgrade:
  ▸ Existing local deployment
```

Select `Existing local deployment`. This installs the upgrade file on all nodes of your local network running in the background.

Et voilà. This is the output shown if all went well:

```bash
✔ Existing local deployment
.......
Network restarted and ready to use. Upgrade bytes have been applied to running nodes at these endpoints.
The next upgrade will go into effect 2023-03-31 09:00:00
+-------+------------+-----------------------------------------------------------------------------------+
| NODE  |     VM     |                                        URL                                        |
+-------+------------+-----------------------------------------------------------------------------------+
| node1 | testblockchain | http://0.0.0.0:9650/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node2 | testblockchain | http://0.0.0.0:9652/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node3 | testblockchain | http://0.0.0.0:9654/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node4 | testblockchain | http://0.0.0.0:9656/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node5 | testblockchain | http://0.0.0.0:9658/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
```

There is only so much the tool can do here for you. It installed the upgrade bytes _as-is_ as you configured respectively provided them to the tool. You should verify yourself that the upgrades were actually installed correctly, for example issuing some transactions - mind the timestamp!.

Apply the Upgrade to a Public Node (Testnet or Mainnet)[​](#apply-the-upgrade-to-a-public-node-testnet-or-mainnet "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------------------------

For this scenario to work, you should also have deployed the Lux L1 to the public network (Testnet or Mainnet) with this tool. Otherwise, the tool won't know the details of the Lux L1, and won't be able to guide you.

Assuming the Lux L1 has been already deployed to Testnet, when running the `apply` command, the tool notices the deployment:

```bash
lux blockchain upgrade apply testblockchain
Use the arrow keys to navigate: ↓ ↑ → ←
? What deployment would you like to upgrade:
    Existing local deployment
  ▸ Testnet
```

If not, you would not find the `Testnet` entry here.

<Callout title="Note">
This scenario assumes that you are running the `testnet` validator on the same machine which is running Lux-CLI.
</Callout>

If this is the case, the tool tries to install the upgrade file at the expected destination. If you use default paths, it tries to install at `$HOME/.luxgo/chains/`, creating the chain id directory, so that the file finally ends up at `$HOME/.luxgo/chains/<chain-id>/upgrade.json`.

If you are _not_ using default paths, you can configure the path by providing the flag `--luxgo-chain-config-dir` to the tool. For example:

```bash
lux blockchain upgrade apply testblockchain --luxgo-chain-config-dir /path/to/your/chains
```

Make sure to identify correctly where your chain config dir is, or the node might fail to find it.

If all is correct, the file gets installed:

```bash
lux blockchain upgrade apply testblockchain
✔ Testnet
The chain config dir luxgo uses is set at /home/fabio/.luxgo/chains
Trying to install the upgrade files at the provided /home/fabio/.luxgo/chains path
Successfully installed upgrade file
```

If however the node is _not_ running on this same machine where you are executing Lux-CLI, there is no point in running this command for a Testnet node. In this case, you might rather export the file and install it at the right location.

To see the instructions about how to go about this, add the `--print` flag:

```bash
lux blockchain upgrade apply testblockchain --print
✔ Testnet
To install the upgrade file on your validator:

1. Identify where your validator has the luxgo chain config dir configured.
   The default is at $HOME/.luxgo/chains (/home/user/.luxgo/chains on this machine).
   If you are using a different chain config dir for your node, use that one.
2. Create a directory with the blockchainID in the configured chain-config-dir (e.g. $HOME/.luxgo/chains/ExDKhjXqiVg7s35p8YJ56CJpcw6nJgcGCCE7DbQ4oBknZ1qXi) if doesn't already exist.
3. Create an `upgrade.json` file in the blockchain directory with the content of your upgrade file.
   This is the content of your upgrade file as configured in this tool:
{
    "precompileUpgrades": [
        {
            "txAllowListConfig": {
                "adminAddresses": [
                    "0xb3d82b1367d362de99ab59a658165aff520cbd4d"
                ],
                "enabledAddresses": null,
                "blockTimestamp": 1677550447
            }
        }
    ]
}

   ******************************************************************************************************************
   * Upgrades are tricky. The syntactic correctness of the upgrade file is important.                               *
   * The sequence of upgrades must be strictly observed.                                                            *
   * Make sure you understand https://build.lux.network/docs/nodes/configure/configs-flags#subnet-chain-configs  *
   * before applying upgrades manually.                                                                             *
   ******************************************************************************************************************
```

The instructions also show the content of your current upgrade file, so you can just select that if you wish. Or actually export the file.

Export the Upgrade File[​](#export-the-upgrade-file "Direct link to heading")
-----------------------------------------------------------------------------

If you have generated the upgrade file, you can export it:

```bash
lux blockchain upgrade export testblockchain
✔ Provide a path where we should export the file to: /tmp/testblockchain-upgrade.json
```

Just provide a valid path to the prompt, and the tool exports the file there.

```bash
lux blockchain upgrade export testblockchain
Provide a path where we should export the file to: /tmp/testblockchain-upgrade.json
Writing the upgrade bytes file to "/tmp/testblockchain-upgrade.json"...
File written successfully.
```

You can now take that file and copy it to validator nodes, see preceding instructions.

Import the Upgrade File[​](#import-the-upgrade-file "Direct link to heading")
-----------------------------------------------------------------------------

You or someone else might have generated the file elsewhere, or on another machine. And now you want to install it on the validator machine, using Lux-CLI.

You can import the file:

```bash
lux blockchain upgrade import testblockchain
Provide the path to the upgrade file to import: /tmp/testblockchain-upgrade.json
```

An existing file with the same path and filename would be overwritten.

After you have imported the file, you can `apply` it either to a local network or to a locally running validator. Follow the instructions for the appropriate use case.


# Virtual Machine (/docs/tooling/avalanche-cli/upgrade/avalanche-l1-virtual-machine)

---
title: Virtual Machine
description: This how-to guide explains how to upgrade the VM of an already-deployed Lux L1.
---

To upgrade a local Lux L1, you first need to pause the local network. To do so, run:

```bash
lux network stop
```

Next, you need to select the new VM to run your Lux L1 on. If you're running a Subnet-EVM Lux L1, you likely want to bump to the latest released version. If you're running a Custom VM, you'll want to choose another custom binary.

Start the upgrade wizard with:

```bash
lux blockchain upgrade vm <blockchainName>
```

where you replace `<blockchainName>` with the name of the Lux L1 you would like to upgrade.

## Selecting a VM Deployment to Upgrade

After starting the Lux L1 Upgrade Wizard, you should see something like this:

```bash
? What deployment would you like to upgrade:
  ▸ Update config for future deployments
    Existing local deployment
```

If you select the first option, Lux-CLI updates your Lux L1's config and any future calls to `lux blockchain deploy` use the new version you select. However, any existing local deployments continue to use the old version.

If you select the second option, the opposite occurs. The existing local deployment switches to the new VM but subsequent deploys use the original.

## Select a VM to Upgrade To

The next option asks you to select your new virtual machine.

```bash
? How would you like to update your Lux L1's virtual machine:
  ▸ Update to latest version
    Update to a specific version
    Update to a custom binary
```

If you're using the Subnet-EVM, you'll have the option to upgrade to the latest released version. You can also select a specific version or supply a custom binary. If your Lux L1 already uses a custom VM, you need to select another custom binary.

Once you select your VM, you should see something like:

```bash
Upgrade complete. Ready to restart the network.
```

## Restart the Network

<Callout title="Note">
If you are running multiple Lux L1s concurrently, you may need to update multiple Lux L1s to restart the network. All of your deployed must be using the same RPC Protocol version. You can see more details about this [here](/docs/nodes/maintain/upgrade#incompatible-rpc-version-for-custom-vm).
</Callout>

Finally, restart the network with:

```bash
lux network start
```

If the network starts correctly, your Lux L1 is now running the upgraded VM.


# Authentication (/docs/tooling/avalanche-sdk/chainkit/authentication)

---
title: Authentication
description: Authentication for the ChainKit SDK
icon: Lock
---
### Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name     | Type   | Scheme  |
| -------- | ------ | ------- |
| `apiKey` | apiKey | API key |

The ChainKit SDK can be used without an API key, but rate limits will be lower. Adding an API key allows for higher rate limits. To get an API key, create one via [Builder Console](/console/utilities/data-api-keys) and securely store it. Whether or not you use an API key, you can still interact with the SDK effectively, but the API key provides performance benefits for higher request volumes.

```javascript
import { Lux } from "@lux-sdk/chainkit";

const luxSDK = new Lux({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await luxSDK.metrics.healthCheck();

  // Handle the result
  console.log(result);
}

run();
```

<Callout type="warning">
  Never hardcode your API key directly into your code. Instead, securely store
  it and retrieve it from an environment variable, a secrets manager, or a
  dedicated configuration storage mechanism. This ensures that sensitive
  information remains protected and is not exposed in version control or
  publicly accessible code.
</Callout>

# Custom HTTP Client (/docs/tooling/avalanche-sdk/chainkit/custom-http)

---
title: Custom HTTP Client
description: Custom HTTP Client for the ChainKit SDK
icon: Server
---

The TypeScript SDK makes API calls using an HTTPClient that wraps the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This client is a thin wrapper around `fetch` and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The `HTTPClient` constructor takes an optional `fetcher` argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the `beforeRequest` hook to to add a custom header and a timeout to requests and how to use the `requestError` hook to log errors:

```javascript
import { Lux } from "@lux-sdk/chainkit";
import { HTTPClient } from "@lux-sdk/chainkit/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  },
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000),
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Lux({ httpClient });
```

# Error Handling (/docs/tooling/avalanche-sdk/chainkit/errors)

---
title: Error Handling
description: Error Handling for the ChainKit SDK
icon: Bug
---
All SDK methods return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.

| Error Object               | Status Code | Content Type     |
| :------------------------- | :---------- | :--------------- |
| errors.BadRequest          | 400         | application/json |
| errors.Unauthorized        | 401         | application/json |
| errors.Forbidden           | 403         | application/json |
| errors.NotFound            | 404         | application/json |
| errors.TooManyRequests     | 429         | application/json |
| errors.InternalServerError | 500         | application/json |
| errors.BadGateway          | 502         | application/json |
| errors.ServiceUnavailable  | 503         | application/json |
| errors.SDKError            | 4xx-5xx     | /                |

Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The SDKValidationError that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.

```javascript
import { Lux } from "@lux-sdk/chainkit";
import {
  BadGateway,
  BadRequest,
  Forbidden,
  InternalServerError,
  NotFound,
  SDKValidationError,
  ServiceUnavailable,
  TooManyRequests,
  Unauthorized,
} from "@lux-sdk/chainkit/models/errors";

const luxSDK = new Lux({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  try {
    await luxSDK.data.nfts.reindex({
      address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      tokenId: "145",
    });
  } catch (err) {
    switch (true) {
      case err instanceof SDKValidationError: {
        // Validation errors can be pretty-printed
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      case err instanceof BadRequest: {
        // Handle err.data$: BadRequestData
        console.error(err);
        return;
      }
      case err instanceof Unauthorized: {
        // Handle err.data$: UnauthorizedData
        console.error(err);
        return;
      }
      case err instanceof Forbidden: {
        // Handle err.data$: ForbiddenData
        console.error(err);
        return;
      }
      case err instanceof NotFound: {
        // Handle err.data$: NotFoundData
        console.error(err);
        return;
      }
      case err instanceof TooManyRequests: {
        // Handle err.data$: TooManyRequestsData
        console.error(err);
        return;
      }
      case err instanceof InternalServerError: {
        // Handle err.data$: InternalServerErrorData
        console.error(err);
        return;
      }
      case err instanceof BadGateway: {
        // Handle err.data$: BadGatewayData
        console.error(err);
        return;
      }
      case err instanceof ServiceUnavailable: {
        // Handle err.data$: ServiceUnavailableData
        console.error(err);
        return;
      }
      default: {
        throw err;
      }
    }
  }
}

run();
```

# Getting Started (/docs/tooling/avalanche-sdk/chainkit/getting-started)

---
title: Getting Started
description: Get started with the ChainKit SDK
icon: Rocket
---

### ChainKit SDK

The ChainKit SDK provides web3 application developers with multi-chain data related to Lux's primary network, Lux L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

<Callout>
  **Migration Notice**: This SDK was previously known as the AvaCloud SDK. We
  have made namespace changes and will discontinue the AvaCloud SDK in favor of
  the ChainKit SDK. For migration guidance and specific method updates, please
  refer to the individual method documentation.
</Callout>

<img
  src="https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=5ef81daf70200912ac6c1b505021c921"
  data-og-width="3968"
  width="3968"
  data-og-height="2452"
  height="2452"
  data-path="images/chainkit-SDK.jpg"
  data-optimize="true"
  data-opv="3"
  srcSet="https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=280&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=17f99881ded8ce13a0df4784eb730562 280w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=560&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=b64c64345a3586c1d73a1acdad757bb0 560w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=840&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=606d74291aa14a9c98a169450b00ec9e 840w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=1100&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=8cb8cb94c1851512eae03c1deaa71985 1100w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=1650&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=855ca27fa8e66c64006f3d4623a7d8f6 1650w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=2500&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=97d501a7bedbfc7c909e4b6b706bafe8 2500w"
/>

The SDK is currently available in TypeScript, with more languages coming soon. If you are interested in a language that is not listed, please reach out to us in the [#lux-sdk](https://discord.com/channels/578992315641626624/1416238478915665961) channel in the [Lux Discord](https://discord.gg/lux).

<Cards>
  <Card title="NPM Package">
    [https://www.npmjs.com/package/@lux-sdk/chainkit](https://www.npmjs.com/package/@lux-sdk/chainkit)
  </Card>
  <Card title="GitHub Repository">
    [https://github.com/luxfi/lux-sdk-typescript](https://github.com/luxfi/lux-sdk-typescript)
  </Card>
</Cards>

### SDK Installation

<InstallTabs items={['npm', 'yarn', 'bun']}>
<Tab value="npm">

```bash
npm install @lux-sdk/client
```

</Tab>
<Tab value="yarn">

```bash
yarn add @lux-sdk/client
```

</Tab>
<Tab value="bun">

```bash
bun add @lux-sdk/client
```

</Tab>
</InstallTabs>

### SDK Example Usage

```javascript
import { Lux } from "@lux-sdk/chainkit";

const luxSDK = new Lux({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await luxSDK.metrics.healthCheck();

  // Handle the result
  console.log(result);
}

run();
```

Refer to the code samples provided for each route to see examples of how to use them in the SDK. Explore routes here [Data API](/docs/api-reference/data-api/getting-started),
[Metrics API](/docs/api-reference/metrics-api/getting-started) & [Webhooks API](/docs/api-reference/webhook-api).


# Global Parameters (/docs/tooling/avalanche-sdk/chainkit/global-parameters)

---
title: Global Parameters
description: Global parameters for the ChainKit SDK
icon: Globe
---
Certain parameters are configured globally. These parameters may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, These global values will be used as defaults on the operations that use them. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set `chainId` to `43114` at SDK initialization and then you do not have to pass the same value on calls to operations like getBlock. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

### Available Globals

The following global parameters are available.

| Name      | Type                          | Required | Description                                              |
| :-------- | :---------------------------- | :------- | :------------------------------------------------------- |
| `chainId` | string                        | No       | A supported EVM chain id, chain alias, or blockchain id. |
| `network` | components.GlobalParamNetwork | No       | A supported network type, either mainnet or a testnet.   |

Example

```javascript
import { Lux } from "@lux-sdk/chainkit";

const luxSDK = new Lux({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114", // Sets chainId globally, will be used if not passed during method call.
  network: "mainnet",
});

async function run() {
  const result = await luxSDK.data.evm.blocks.get({
    blockId:
      "0x17533aeb5193378b9ff441d61728e7a2ebaf10f61fd5310759451627dfca2e7c",
    chainId: "<YOUR_CHAIN_ID>", // Override the globally set chain id.
  });

  // Handle the result
  console.log(result);
}

run();
```

# Pagination (/docs/tooling/avalanche-sdk/chainkit/pagination)

---
title: Pagination
description: Pagination for the ChainKit SDK
icon: StickyNote
---
Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned response object will also be an async iterable that can be consumed using the `for await...of` syntax.

Here's an example of one such pagination call:

```javascript
import { Lux } from "@lux-sdk/chainkit";

const luxSDK = new Lux({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await luxSDK.metrics.chains.list({
    network: "mainnet",
  });

  for await (const page of result) {
    // Handle the page
    console.log(page);
  }
}

run();
```

# Retries (/docs/tooling/avalanche-sdk/chainkit/retries)

---
title: Retries
description: Retries for the ChainKit SDK
icon: RotateCcw
---
Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

```javascript
import { Lux } from "@lux-sdk/chainkit";

const luxSDK = new Lux({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await luxSDK.metrics.healthCheck({
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  // Handle the result
  console.log(result);
}

run();
```

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

```javascript
import { Lux } from "@lux-sdk/chainkit";

const luxSDK = new Lux({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await luxSDK.metrics.healthCheck();

  // Handle the result
  console.log(result);
}

run();
```

# Client & Transports (/docs/tooling/avalanche-sdk/client/clients-transports)

---
title: Client & Transports
icon: Plug
---

## Overview

Clients provide type-safe interfaces for interacting with Lux. Transports handle the communication layer. This separation lets you switch between HTTP, WebSocket, or custom providers without changing your code.

The SDK is built on [viem](https://viem.sh), so you get full Ethereum compatibility plus native support for Platform-Chain, Exchange-Chain, and LUExchange-Chain operations.

## Clients

Clients are TypeScript interfaces that abstract RPC calls and provide type-safe APIs.

### Lux Client (Public Client)

The read-only client for querying blockchain data across all Lux chains.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: {
    type: "http",
  },
});

// Access different chains
const pChainHeight = await client.pChain.getHeight();
const cChainBalance = await client.getBalance({
  address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
});
```

### Lux Wallet Client

Extends the public client with transaction signing and sending capabilities.

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToWei } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: {
    type: "http",
  },
});

// Send LUX
const hash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
});
```

### Chain-Specific Clients

Access chain-specific operations through sub-clients:

- `client.pChain` - Validator operations, staking, subnet management
- `client.xChain` - Asset transfers, UTXO operations
- `client.cChain` - Atomic transactions
- API clients - Admin, Info, Health, Index API, Proposervm operations

## Transports

Transports handle data transmission between your application and Lux nodes. They abstract RPC protocol implementation.

### HTTP Transport

Uses standard HTTP/HTTPS connections. Most common choice for production applications.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: {
    type: "http",
    // Optional: specify custom URL
    // url: "https://api.lux.network/ext/bc/C/rpc",
  },
});
```

### WebSocket Transport

Maintains a persistent connection for real-time subscriptions and event streaming.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: {
    type: "ws",
    // Optional: specify custom WebSocket URL
    // url: "wss://api.lux.network/ext/bc/C/ws",
  },
});
```

### Custom Transport (EIP-1193)

Supports custom transport implementations, including EIP-1193 providers (MetaMask, WalletConnect, etc.).

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import "@lux-sdk/client/window";
// Using window.ethereum (Core, MetaMask, etc.)
const walletClient = createLuxWalletClient({
  account: account,
  chain: lux,
  transport: {
    type: "custom",
    provider: window.ethereum,
    // Or
    // provider: window.lux,
  },
});
```

## Transport Configuration

### Mainnet/Testnet

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux, luxTestnet } from "@lux-sdk/client/chains";

// Mainnet
const mainnetClient = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

// Testnet (Testnet)
const testnetClient = createLuxClient({
  chain: luxTestnet,
  transport: { type: "http" },
});
```

### Custom Endpoints

```typescript
const client = createLuxClient({
  chain: lux,
  transport: {
    type: "http",
    url: "https://your-custom-rpc-endpoint.com/ext/bc/C/rpc",
    // Optional: Add headers for authentication
    // fetchOptions: {
    //   headers: {
    //     Authorization: `Bearer ${apiKey}`,
    //   },
    // },
  },
});
```

### Switching Transports

Switch between transports without changing your application logic:

```typescript
// HTTP client
const httpClient = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

// WebSocket client
const wsClient = createLuxClient({
  chain: lux,
  transport: { type: "ws" },
});

// Both have the same API
const height1 = await httpClient.pChain.getHeight();
const height2 = await wsClient.pChain.getHeight();
```

## Client Selection

### Public Client vs Wallet Client

| Feature                 | Public Client | Wallet Client         |
| ----------------------- | ------------- | --------------------- |
| **Read Operations**     | ✅ Yes        | ✅ Yes (inherits all) |
| **Transaction Signing** | ❌ No         | ✅ Yes                |
| **Transaction Sending** | ❌ No         | ✅ Yes                |
| **Account Required**    | ❌ No         | ✅ Yes                |

**Use Public Client for:** Reading blockchain data, querying balances, fetching validator info, reading smart contract state.

**Use Wallet Client for:** Sending transactions, signing messages, transferring assets, interacting with smart contracts.

### Chain-Specific Clients

The main client provides access to all chains. You can also create standalone chain-specific clients:

```typescript
// Main client - access all chains
const client = createLuxClient({ ... });
await client.pChain.getHeight();
await client.xChain.getBalance({ ... });

// Chain-specific client
import { createPChainClient } from "@lux-sdk/client";
const pChainOnly = createPChainClient({ ... });
await pChainOnly.getHeight();
```

**Use chain-specific clients when:** Your app only interacts with one chain, you want smaller bundle size, or need specialized configuration.

**Use main client when:** Your app uses multiple chains or you want unified configuration.

## Next Steps

- **[Lux Client](clients/lux-client)** - Read-only operations
- **[Lux Wallet Client](clients/wallet-client)** - Transaction operations
- **[Chain-Specific Clients](clients/p-chain-client)** - Platform-Chain, Exchange-Chain, and LUExchange-Chain clients
- **[Public Actions](methods/public-methods/p-chain)** - Read operations reference
- **[Wallet Actions](methods/wallet-methods/wallet)** - Write operations reference

The SDK follows the same transport patterns as [viem](https://viem.sh/docs/clients/public.html#transport) for compatibility.


# Getting Started (/docs/tooling/avalanche-sdk/client/getting-started)

---
title: Getting Started
icon: Rocket
description: Get started with the Lux Client SDK - your gateway to building on Lux with TypeScript.
---

## Overview

The Lux Client SDK provides a TypeScript interface for interacting with Lux. Built on [viem](https://viem.sh), it offers full Ethereum compatibility plus native support for Platform-Chain, Exchange-Chain, and LUExchange-Chain operations.

<Cards>
  <Card title="NPM Package">
    [https://www.npmjs.com/package/@lux-sdk/client](https://www.npmjs.com/package/@lux-sdk/client)
  </Card>
  <Card title="GitHub Repository">
    [https://github.com/luxfi/lux-sdk-typescript](https://github.com/luxfi/lux-sdk-typescript)
  </Card>
</Cards>

## Installation

Install the Lux Client SDK using your preferred package manager:

<InstallTabs items={['npm', 'yarn', 'bun']}>
<Tab value="npm">

```bash
npm install @lux-sdk/client
```

</Tab>
<Tab value="yarn">

```bash
yarn add @lux-sdk/client
```

</Tab>
<Tab value="bun">

```bash
bun add @lux-sdk/client
```

</Tab>
</InstallTabs>

### Requirements

- Node.js >= 20.0.0
- TypeScript >= 5.0.0 (recommended)
- Modern browsers: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+

## Quick Start

### Public Client

Create a read-only client:

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

// Read operations
const pChainHeight = await client.pChain.getHeight();
const balance = await client.getBalance({
  address: "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e",
});
```

### Wallet Client

Create a wallet client for transactions:

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToWei } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Send LUX
const hash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
});
```

## Account Creation

### Private Key

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");
```

### Mnemonic

```typescript
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";

const account = mnemonicsToLuxAccount("test test test...");
```

### HD Key

```typescript
import { hdKeyToLuxAccount, HDKey } from "@lux-sdk/client/accounts";

const hdKey = HDKey.fromMasterSeed(seed);
const account = hdKeyToLuxAccount(hdKey);
```

[Learn more about accounts →](accounts)

## Transport Configuration

### HTTP

```typescript
const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});
```

### WebSocket

```typescript
const client = createLuxClient({
  chain: lux,
  transport: { type: "ws" },
});
```

### Custom Endpoint

```typescript
const client = createLuxClient({
  chain: lux,
  transport: {
    type: "http",
    url: "https://your-custom-rpc-endpoint.com/ext/bc/C/rpc",
  },
});
```

[Learn more about transports →](clients-transports)

## Lux Chains

Lux has three primary chains:

- **Platform-Chain (Platform Chain)**: Validators, staking, subnets
- **Exchange-Chain (Exchange Chain)**: Asset transfers (UTXO model)
- **LUExchange-Chain (Contract Chain)**: Smart contracts (Ethereum-compatible)

```typescript
// Platform-Chain
const validators = await client.pChain.getCurrentValidators({});

// Exchange-Chain
const balance = await client.xChain.getBalance({
  address: "X-lux1example...",
  assetID: "LUX",
});

// LUExchange-Chain
const balance = await client.getBalance({ address: "0x..." });
```

## Using viem Features

The SDK is built on viem, so you have access to all viem functionality:

```typescript
import { formatEther, parseEther } from "@lux-sdk/client/utils";

const valueInWei = parseEther("1.0");
const valueInLux = formatEther(1000000000000000000n);
const receipt = await walletClient.waitForTransactionReceipt({ hash });
```

See the [viem documentation](https://viem.sh/docs/getting-started) for more utilities.

## Next Steps

- **[Clients & Transports](clients-transports)** - Understanding clients and transports
- **[Account Management](accounts)** - Creating and managing accounts
- **[Wallet Operations](methods/wallet-methods/wallet)** - Sending transactions
- **[Platform-Chain Operations](methods/public-methods/p-chain)** - Validator and staking
- **[Exchange-Chain Operations](methods/public-methods/x-chain)** - Asset transfers
- **[LUExchange-Chain Operations](methods/public-methods/c-chain)** - EVM operations

## Need Help?

- [Discord community](https://discord.gg/lux)
- [GitHub examples](https://github.com/luxfi/lux-sdk-typescript/tree/main/client/examples)
- [Open an issue](https://github.com/luxfi/lux-sdk-typescript/issues)


# Getting Started (/docs/tooling/avalanche-sdk/interchain/getting-started)

---
title: Getting Started
description: Install and configure the Interchain SDK
icon: rocket
---

## Installation

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    npm install @lux-sdk/interchain @lux-sdk/client
  </Tab>
  <Tab value="pnpm">
    pnpm add @lux-sdk/interchain @lux-sdk/client
  </Tab>
  <Tab value="yarn">
    yarn add @lux-sdk/interchain @lux-sdk/client
  </Tab>
  <Tab value="bun">bun add @lux-sdk/interchain @lux-sdk/client</Tab>
</Tabs>

## Setup

### 1. Create Wallet Client

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { luxTestnet } from "@lux-sdk/client/chains";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");
const wallet = createLuxWalletClient({
  account,
  chain: luxTestnet,
  transport: { type: "http" },
});
```

### 2. Initialize ICM Client

```typescript
import { createICMClient } from "@lux-sdk/interchain";
import { luxTestnet, dispatch } from "@lux-sdk/interchain/chains";

const icm = createICMClient(wallet, luxTestnet, dispatch);
```

## Send Your First Message

```typescript
async function sendMessage() {
  const hash = await icm.sendMsg({
    sourceChain: luxTestnet,
    destinationChain: dispatch,
    message: "Hello from Lux!",
  });

  console.log("Message sent:", hash);
}
```

## Send Your First Token Transfer

```typescript
import { createICTTClient } from "@lux-sdk/interchain";

const ictt = createICTTClient(luxTestnet, dispatch);

// Deploy token and contracts (one-time setup)
const { contractAddress: tokenAddress } = await ictt.deployERC20Token({
  walletClient: wallet,
  sourceChain: luxTestnet,
  name: "My Token",
  symbol: "MTK",
  initialSupply: 1000000,
});

// Send tokens
const { txHash } = await ictt.sendToken({
  walletClient: wallet,
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  tokenHomeContract: "0x...",
  tokenRemoteContract: "0x...",
  recipient: "0x...",
  amountInBaseUnit: 100,
});
```

## Next Steps

- Learn about [Interchain Messaging](/lux-sdk/interchain/icm)
- Explore [Token Transfers](/lux-sdk/interchain/ictt)
- Understand [Warp Messages](/lux-sdk/interchain/warp)


# Interchain SDK (/docs/tooling/avalanche-sdk/interchain)

---
title: Interchain SDK
icon: network
description: Send cross-chain messages and transfer tokens between Lux chains and subnets
---

## Overview

The Interchain SDK enables cross-chain communication on Lux. Send messages and transfer ERC20 tokens between Lux LUExchange-Chain and subnets using the Teleporter protocol.

**Key Features:**

- **Interchain Messaging (ICM)** - Send arbitrary messages across chains
- **Interchain Token Transfers (ICTT)** - Transfer ERC20 tokens between chains
- **Warp Messages** - Parse and build Warp protocol messages
- **Type-safe** - Full TypeScript support with IntelliSense

## Quick Start

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { createICMClient } from "@lux-sdk/interchain";
import { luxTestnet, dispatch } from "@lux-sdk/interchain/chains";

// Setup wallet
const account = privateKeyToLuxAccount("0x...");
const wallet = createLuxWalletClient({
  account,
  chain: luxTestnet,
  transport: { type: "http" },
});

// Create ICM client
const icm = createICMClient(wallet);

// Send message
const hash = await icm.sendMsg({
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  message: "Hello from Lux!",
});
```

## What's Next

<Cards>
  <Card
    title="Getting Started"
    description="Install and configure the SDK"
    href="/lux-sdk/interchain/getting-started"
  />
  <Card
    title="Interchain Messaging"
    description="Send messages across chains"
    href="/lux-sdk/interchain/icm"
  />
  <Card
    title="Token Transfers"
    description="Transfer ERC20 tokens cross-chain"
    href="/lux-sdk/interchain/ictt"
  />
  <Card
    title="Warp Messages"
    description="Parse and build Warp protocol messages"
    href="/lux-sdk/interchain/warp"
  />
</Cards>


# Testing Cross-Chain Messaging (/docs/tooling/tmpnet/guides/cross-chain-messaging)

---
title: Testing Cross-Chain Messaging
description: Test Teleporter cross-chain messaging between Lux L1s
---

This guide shows how to test cross-chain messaging using Teleporter, Lux's native cross-chain communication protocol. Learn the complete flow from sending messages to relaying and verifying delivery.

## Overview

Teleporter enables L1s to communicate by:

1. **Sending** a message on the source chain
2. **Aggregating** signatures from validators via Warp
3. **Relaying** the signed message to the destination chain
4. **Verifying** delivery and execution

## Prerequisites

- Complete [Getting Started](/docs/tooling/tmpnet/guides/getting-started)
- Have a network with two L1s configured
- Understand Warp message basics

## Basic Send and Receive Flow

### Complete Test Example

```go title="teleporter_test.go"
package teleporter_test

import (
    "context"
    "flag"
    "math/big"
    "os"
    "testing"
    "time"

    "github.com/luxfi/luxgo/tests/fixture/e2e"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    teleportermessenger "github.com/luxfi/teleporter/abi-bindings/go/teleporter/TeleporterMessenger"
    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/crypto"
    "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var (
    network            *tmpnet.Network
    e2eFlags           *e2e.FlagVars
    l1A, l1B           L1TestInfo
    teleporterAddress  common.Address
    fundedKey          *ecdsa.PrivateKey
)

func TestMain(m *testing.M) {
    e2eFlags = e2e.RegisterFlags()
    flag.Parse()
    os.Exit(m.Run())
}

func TestTeleporter(t *testing.T) {
    if os.Getenv("RUN_E2E") == "" {
        t.Skip("RUN_E2E not set")
    }

    RegisterFailHandler(ginkgo.Fail)
    ginkgo.RunSpecs(t, "Teleporter Test Suite")
}

var _ = ginkgo.BeforeSuite(func() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
    defer cancel()

    // Create network with two L1s and Teleporter pre-deployed
    network, l1A, l1B, teleporterAddress = createNetworkWithTeleporter(ctx)

    fundedKey = network.PreFundedKeys[0]
})

var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        network.Stop(context.Background())
    }
})

var _ = ginkgo.Describe("[Teleporter Messaging]", func() {
    ginkgo.It("should send and receive message",
        ginkgo.Label("teleporter", "basic"),
        func() {
            ctx := context.Background()
            fundedAddress := crypto.PubkeyToAddress(fundedKey.PublicKey)

            // Create signature aggregator
            aggregator := NewSignatureAggregator(
                l1A.NodeURIs[0],
                []ids.ID{l1A.SubnetID, l1B.SubnetID},
            )
            defer aggregator.Shutdown()

            // 1. Send cross-chain message
            messageID, receipt := sendCrossChainMessage(
                ctx,
                l1A,
                l1B,
                teleporterAddress,
                fundedAddress,
                []byte("Hello from Chain A!"),
                fundedKey,
            )

            Expect(receipt.Status).To(Equal(uint64(1)))

            // 2. Relay message to destination
            deliveryReceipt := relayMessage(
                ctx,
                receipt,
                l1A,
                l1B,
                teleporterAddress,
                aggregator,
                fundedKey,
            )

            Expect(deliveryReceipt.Status).To(Equal(uint64(1)))

            // 3. Verify message was received
            teleporter := getTeleporterContract(l1B, teleporterAddress)
            delivered, err := teleporter.MessageReceived(
                &bind.CallOpts{},
                messageID,
            )
            Expect(err).NotTo(HaveOccurred())
            Expect(delivered).To(BeTrue())
        })
})
```

## Step-by-Step Implementation

### 1. Sending a Message

```go
func sendCrossChainMessage(
    ctx context.Context,
    source L1TestInfo,
    destination L1TestInfo,
    teleporterAddress common.Address,
    recipientAddress common.Address,
    message []byte,
    senderKey *ecdsa.PrivateKey,
) (common.Hash, *types.Receipt) {

    // Get Teleporter contract
    teleporter := getTeleporterContract(source, teleporterAddress)

    // Prepare message input
    input := teleportermessenger.TeleporterMessageInput{
        DestinationBlockchainID: destination.BlockchainID,
        DestinationAddress:      recipientAddress,
        FeeInfo: teleportermessenger.TeleporterFeeInfo{
            FeeTokenAddress: common.Address{}, // No fee for this example
            Amount:          big.NewInt(0),
        },
        RequiredGasLimit:        big.NewInt(100000),
        AllowedRelayerAddresses: []common.Address{}, // Any relayer allowed
        Message:                 message,
    }

    // Send transaction
    opts, err := bind.NewKeyedTransactorWithChainID(senderKey, source.EVMChainID)
    Expect(err).NotTo(HaveOccurred())

    tx, err := teleporter.SendCrossChainMessage(opts, input)
    Expect(err).NotTo(HaveOccurred())

    // Wait for transaction success
    receipt := waitForSuccess(ctx, source, tx.Hash())

    // Extract message ID from logs
    messageID := extractMessageIDFromReceipt(receipt, teleporter)

    return messageID, receipt
}
```

### 2. Constructing Warp Message

```go
func constructWarpMessage(
    ctx context.Context,
    source L1TestInfo,
    destination L1TestInfo,
    receipt *types.Receipt,
    aggregator *SignatureAggregator,
) *luxWarp.Message {

    // Extract unsigned Warp message from logs
    unsignedMessage := extractWarpMessageFromLogs(ctx, receipt, source)

    // Wait for all validators to accept the block
    waitForAllValidatorsToAcceptBlock(
        ctx,
        source.NodeURIs,
        source.BlockchainID,
        receipt.BlockNumber.Uint64(),
    )

    // Get signed message from aggregator
    signedMessage, err := aggregator.CreateSignedMessage(
        unsignedMessage,
        nil, // No justification needed for Teleporter
        source.SubnetID,
        67, // 67% quorum (warp.WarpDefaultQuorumNumerator)
    )
    Expect(err).NotTo(HaveOccurred())

    return signedMessage
}
```

### 3. Relaying the Message

```go
func relayMessage(
    ctx context.Context,
    sourceReceipt *types.Receipt,
    source L1TestInfo,
    destination L1TestInfo,
    teleporterAddress common.Address,
    aggregator *SignatureAggregator,
    relayerKey *ecdsa.PrivateKey,
) *types.Receipt {

    // Construct signed Warp message
    signedMessage := constructWarpMessage(
        ctx,
        source,
        destination,
        sourceReceipt,
        aggregator,
    )

    // Get Teleporter contract on destination
    teleporter := getTeleporterContract(destination, teleporterAddress)

    // Create predicate transaction (includes Warp message in access list)
    tx := createPredicateTx(
        ctx,
        destination,
        teleporterAddress,
        signedMessage,
        relayerKey,
        func(opts *bind.TransactOpts) (*types.Transaction, error) {
            return teleporter.ReceiveCrossChainMessage(opts, 0, relayerKey.Address)
        },
    )

    // Send and wait for success
    err := destination.RPCClient.SendTransaction(ctx, tx)
    Expect(err).NotTo(HaveOccurred())

    receipt := waitForSuccess(ctx, destination, tx.Hash())

    return receipt
}
```

## Message Fees and Relayer Rewards

### Sending with Fees

```go
ginkgo.It("should handle message fees",
    ginkgo.Label("teleporter", "fees"),
    func() {
        ctx := context.Background()

        // Deploy ERC20 token for fees
        feeTokenAddress, feeToken := deployERC20Token(
            ctx,
            l1A,
            fundedKey,
            "FeeToken",
            "FEE",
        )

        // Approve Teleporter to spend tokens
        approveERC20(
            ctx,
            l1A,
            feeToken,
            teleporterAddress,
            big.NewInt(1e18),
            fundedKey,
        )

        // Send message with fee
        feeAmount := big.NewInt(1000)
        input := teleportermessenger.TeleporterMessageInput{
            DestinationBlockchainID: l1B.BlockchainID,
            DestinationAddress:      recipientAddress,
            FeeInfo: teleportermessenger.TeleporterFeeInfo{
                FeeTokenAddress: feeTokenAddress,
                Amount:          feeAmount,
            },
            RequiredGasLimit: big.NewInt(100000),
            Message:          []byte("paid message"),
        }

        messageID, receipt := sendMessage(ctx, l1A, teleporterAddress, input, fundedKey)

        // Relay and collect fee
        relayReceipt := relayMessage(ctx, receipt, l1A, l1B, teleporterAddress, aggregator, relayerKey)

        // Verify relayer received fee
        verifyRelayerReward(ctx, l1B, teleporterAddress, relayerAddress, feeTokenAddress, feeAmount)
    })
```

### Redeeming Relayer Rewards

```go
func redeemRelayerRewards(
    ctx context.Context,
    l1 L1TestInfo,
    teleporterAddress common.Address,
    feeTokenAddress common.Address,
    relayerKey *ecdsa.PrivateKey,
) {

    teleporter := getTeleporterContract(l1, teleporterAddress)
    relayerAddress := crypto.PubkeyToAddress(relayerKey.PublicKey)

    // Check pending rewards
    pendingReward, err := teleporter.CheckRelayerRewardAmount(
        &bind.CallOpts{},
        relayerAddress,
        feeTokenAddress,
    )
    Expect(err).NotTo(HaveOccurred())
    Expect(pendingReward.Uint64()).To(BeNumerically(">", 0))

    // Redeem rewards
    opts, _ := bind.NewKeyedTransactorWithChainID(relayerKey, l1.EVMChainID)
    tx, err := teleporter.RedeemRelayerRewards(opts, feeTokenAddress)
    Expect(err).NotTo(HaveOccurred())

    receipt := waitForSuccess(ctx, l1, tx.Hash())

    // Verify rewards received
    feeToken := getERC20Contract(l1, feeTokenAddress)
    balance, err := feeToken.BalanceOf(&bind.CallOpts{}, relayerAddress)
    Expect(err).NotTo(HaveOccurred())
    Expect(balance).To(Equal(pendingReward))
}
```

## Advanced Patterns

### Adding Fees to Existing Messages

```go
ginkgo.It("should add fee to message",
    ginkgo.Label("teleporter", "add-fee"),
    func() {
        ctx := context.Background()

        // Send message with low initial fee
        messageID, _ := sendMessage(ctx, l1A, teleporterAddress, input, fundedKey)

        // Add additional fee
        additionalFee := big.NewInt(500)

        approveERC20(ctx, l1A, feeToken, teleporterAddress, additionalFee, fundedKey)

        teleporter := getTeleporterContract(l1A, teleporterAddress)
        opts, _ := bind.NewKeyedTransactorWithChainID(fundedKey, l1A.EVMChainID)

        tx, err := teleporter.AddFeeAmount(
            opts,
            messageID,
            teleportermessenger.TeleporterFeeInfo{
                FeeTokenAddress: feeTokenAddress,
                Amount:          additionalFee,
            },
        )
        Expect(err).NotTo(HaveOccurred())

        waitForSuccess(ctx, l1A, tx.Hash())
    })
```

### Sending Specific Receipts

```go
ginkgo.It("should send specific receipts",
    ginkgo.Label("teleporter", "receipts"),
    func() {
        ctx := context.Background()

        // Send messages A->B
        messageIDs := []common.Hash{
            sendSimpleMessage(ctx, l1A, l1B, "msg1"),
            sendSimpleMessage(ctx, l1A, l1B, "msg2"),
            sendSimpleMessage(ctx, l1A, l1B, "msg3"),
        }

        // Relay all messages
        for _, msgID := range messageIDs {
            relayMessageByID(ctx, l1A, l1B, msgID, aggregator, fundedKey)
        }

        // Send receipts back B->A
        teleporter := getTeleporterContract(l1B, teleporterAddress)
        opts, _ := bind.NewKeyedTransactorWithChainID(fundedKey, l1B.EVMChainID)

        tx, err := teleporter.SendSpecifiedReceipts(
            opts,
            l1A.BlockchainID,
            messageIDs,
            teleportermessenger.TeleporterFeeInfo{
                FeeTokenAddress: common.Address{},
                Amount:          big.NewInt(0),
            },
            []common.Address{},
        )
        Expect(err).NotTo(HaveOccurred())

        receiptTx := waitForSuccess(ctx, l1B, tx.Hash())

        // Relay receipt message to A
        relayMessage(ctx, receiptTx, l1B, l1A, teleporterAddress, aggregator, fundedKey)
    })
```

### Retrying Failed Execution

```go
ginkgo.It("should retry failed message execution",
    ginkgo.Label("teleporter", "retry"),
    func() {
        ctx := context.Background()

        // Send message that will fail (insufficient gas)
        input := teleportermessenger.TeleporterMessageInput{
            DestinationBlockchainID: l1B.BlockchainID,
            DestinationAddress:      contractAddress,
            RequiredGasLimit:        big.NewInt(10), // Too low
            Message:                 callData,
        }

        messageID, receipt := sendMessage(ctx, l1A, teleporterAddress, input, fundedKey)

        // Relay - will fail but message is delivered
        relayMessage(ctx, receipt, l1A, l1B, teleporterAddress, aggregator, fundedKey)

        // Verify message not executed
        teleporter := getTeleporterContract(l1B, teleporterAddress)
        executed, _ := teleporter.MessageReceived(&bind.CallOpts{}, messageID)
        Expect(executed).To(BeFalse())

        // Retry with more gas
        opts, _ := bind.NewKeyedTransactorWithChainID(fundedKey, l1B.EVMChainID)
        opts.GasLimit = 500000

        tx, err := teleporter.RetryMessageExecution(
            opts,
            l1A.BlockchainID,
            teleportermessenger.TeleporterMessage{
                MessageID:               messageID,
                DestinationBlockchainID: l1B.BlockchainID,
                DestinationAddress:      contractAddress,
                RequiredGasLimit:        big.NewInt(10),
                Message:                 callData,
            },
        )
        Expect(err).NotTo(HaveOccurred())

        waitForSuccess(ctx, l1B, tx.Hash())

        // Verify now executed
        executed, _ = teleporter.MessageReceived(&bind.CallOpts{}, messageID)
        Expect(executed).To(BeTrue())
    })
```

## Signature Aggregation

### Setting Up Aggregator

```go
type SignatureAggregator struct {
    client     *aggregator.Client
    subnetIDs  []ids.ID
}

func NewSignatureAggregator(
    nodeURI string,
    subnetIDs []ids.ID,
) *SignatureAggregator {

    client, err := aggregator.NewSignatureAggregatorClient(nodeURI)
    Expect(err).NotTo(HaveOccurred())

    return &SignatureAggregator{
        client:    client,
        subnetIDs: subnetIDs,
    }
}

func (a *SignatureAggregator) CreateSignedMessage(
    unsignedMessage *luxWarp.UnsignedMessage,
    justification []byte,
    subnetID ids.ID,
    quorumNum uint64,
) (*luxWarp.Message, error) {

    signedMessage, err := a.client.CreateSignedMessage(
        unsignedMessage,
        justification,
        subnetID,
        quorumNum,
    )

    return signedMessage, err
}

func (a *SignatureAggregator) Shutdown() {
    // Clean up aggregator resources
}
```

## Testing Error Scenarios

### Deliver to Wrong Chain

```go
ginkgo.It("should reject wrong chain delivery",
    ginkgo.Label("teleporter", "error"),
    func() {
        ctx := context.Background()

        // Send message A -> B
        messageID, receipt := sendMessage(ctx, l1A, l1B, message, fundedKey)

        // Try to deliver on wrong chain (A instead of B)
        signedMessage := constructWarpMessage(ctx, l1A, l1A, receipt, aggregator)

        // This should fail
        tx := createPredicateTx(ctx, l1A, teleporterAddress, signedMessage, fundedKey, /*...*/)

        err := l1A.RPCClient.SendTransaction(ctx, tx)

        // Expect transaction to fail
        receipt := waitForFailure(ctx, l1A, tx.Hash())
        Expect(receipt.Status).To(Equal(uint64(0)))
    })
```

### Insufficient Gas

```go
ginkgo.It("should handle insufficient gas",
    ginkgo.Label("teleporter", "error"),
    func() {
        // Message with required gas of 100k
        input := teleportermessenger.TeleporterMessageInput{
            RequiredGasLimit: big.NewInt(100000),
            // ... other fields
        }

        messageID, receipt := sendMessage(ctx, l1A, teleporterAddress, input, fundedKey)

        // Relay with insufficient gas (50k)
        tx := createPredicateTxWithGasLimit(
            ctx,
            l1B,
            teleporterAddress,
            signedMessage,
            50000,
            relayerKey,
        )

        // Transaction succeeds but message execution fails
        receipt := waitForSuccess(ctx, l1B, tx.Hash())

        // Message not marked as received
        teleporter := getTeleporterContract(l1B, teleporterAddress)
        received, _ := teleporter.MessageReceived(&bind.CallOpts{}, messageID)
        Expect(received).To(BeFalse())
    })
```

## Best Practices

1. **Always use signature aggregator**: Don't manually collect signatures
2. **Wait for block acceptance**: Ensure validators have seen the block before aggregating
3. **Handle async operations**: Use `Eventually` for checking message delivery
4. **Test error cases**: Verify wrong chain, insufficient gas, etc.
5. **Clean up aggregator**: Always defer `aggregator.Shutdown()`
6. **Use appropriate timeouts**: Cross-chain operations can be slow

## Common Patterns

### Wait for Message Delivery

```go
Eventually(func() bool {
    delivered, _ := teleporter.MessageReceived(&bind.CallOpts{}, messageID)
    return delivered
}, 30*time.Second, 500*time.Millisecond).Should(BeTrue())
```

### Verify Receipt Received

```go
func verifyReceiptReceived(
    ctx context.Context,
    l1 L1TestInfo,
    teleporterAddress common.Address,
    messageID common.Hash,
) {
    teleporter := getTeleporterContract(l1, teleporterAddress)

    received, err := teleporter.ReceiptReceived(&bind.CallOpts{}, messageID)
    Expect(err).NotTo(HaveOccurred())
    Expect(received).To(BeTrue())
}
```

## Next Steps

<Cards>
  <Card title="L1 Conversion" href="/docs/tooling/tmpnet/guides/l1-conversion">
    Convert subnets to L1s with validator managers
  </Card>
  <Card title="Warp Messages" href="/docs/tooling/tmpnet/guides/warp-messages">
    Deep dive into Warp message construction
  </Card>
  <Card title="Transaction Utilities" href="/docs/tooling/tmpnet/guides/transaction-utilities">
    Helper functions for transactions and events
  </Card>
</Cards>

## Additional Resources

- [Teleporter Documentation](https://github.com/luxfi/teleporter)
- [ICM Services Tests](https://github.com/luxfi/icm-services/tree/main/tests)
- [Warp Messaging](https://docs.lux.network/cross-chain)


# Getting Started with tmpnet Testing (/docs/tooling/tmpnet/guides/getting-started)

---
title: Getting Started with tmpnet Testing
description: Set up your first Ginkgo test suite with tmpnet for testing Lux L1s
---

This guide shows you how to set up a Ginkgo test suite with tmpnet for testing Lux L1s. All testing with tmpnet should use Ginkgo for consistency and best practices.

## Prerequisites

Install required packages:

```bash
go get github.com/onsi/ginkgo/v2
go get github.com/onsi/gomega
go get github.com/luxfi/luxgo/tests/fixture/tmpnet
go get github.com/luxfi/luxgo/tests/fixture/e2e
```

## Basic Test Suite Structure

### 1. Create Test Suite File

Create a test file with the standard Ginkgo setup:

```go title="my_test.go"
package mypackage_test

import (
    "context"
    "flag"
    "os"
    "testing"
    "time"

    "github.com/luxfi/luxgo/tests/fixture/e2e"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/utils/logging"
    "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var (
    network  *tmpnet.Network
    e2eFlags *e2e.FlagVars
)

// TestMain registers flags and runs tests
func TestMain(m *testing.M) {
    e2eFlags = e2e.RegisterFlags()
    flag.Parse()
    os.Exit(m.Run())
}

// Test entry point
func TestE2E(t *testing.T) {
    if os.Getenv("RUN_E2E") == "" {
        t.Skip("Environment variable RUN_E2E not set; skipping E2E tests")
    }

    RegisterFailHandler(ginkgo.Fail)
    ginkgo.RunSpecs(t, "My E2E Test Suite")
}
```

**Key Components:**

- `TestMain`: Registers e2e flags for network reuse
- `RUN_E2E` check: Gates tests so they only run when explicitly requested
- `RegisterFailHandler`: Integrates Gomega assertions with Ginkgo
- `RunSpecs`: Ginkgo test entry point

### 2. Network Lifecycle with BeforeSuite/AfterSuite

Create a network once for all tests:

```go
var _ = ginkgo.BeforeSuite(func() {
    // Create network context with timeout
    ctx, cancel := context.WithTimeout(
        context.Background(),
        5*time.Minute,
    )
    defer cancel()

    runtimeCfg, err := e2eFlags.NodeRuntimeConfig() // validates LUXGO_PATH/AVAGO_PLUGIN_DIR or CLI flags
    Expect(err).NotTo(HaveOccurred())

    // Create network configuration
    network = &tmpnet.Network{
        Owner: "my-test-network",
        Nodes: tmpnet.NewNodesOrPanic(5),
        DefaultRuntimeConfig: *runtimeCfg,
        DefaultFlags: tmpnet.FlagsMap{
            "log-level": "info",
            "network-max-reconnect-delay": "1s",
        },
    }

    // Bootstrap network
    err = tmpnet.BootstrapNewNetwork(
        ctx,
        logging.NoLog{},
        network,
        e2eFlags.RootNetworkDir(), // empty string uses default ~/.tmpnet/networks
    )
    Expect(err).NotTo(HaveOccurred())
})

var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        Expect(network.Stop(context.Background())).To(Succeed())
    }
})
```

**Important Notes:**

- `BeforeSuite` runs once before all tests in the suite
- `AfterSuite` ensures cleanup even if tests fail
- Use generous timeouts for network bootstrap (5+ minutes)
- `e2eFlags` enables network reuse (explained below)

### 3. Write Your First Test

```go
var _ = ginkgo.Describe("[Basic Tests]", func() {
    ginkgo.It("should have healthy nodes",
        ginkgo.Label("smoke"),
        func() {
            Expect(network).NotTo(BeNil())
            Expect(network.Nodes).To(HaveLen(5))

            for _, node := range network.Nodes {
                Expect(node.IsHealthy()).To(BeTrue())
            }
        })

    ginkgo.It("should have valid URIs",
        ginkgo.Label("smoke"),
        func() {
            for _, node := range network.Nodes {
                Expect(node.URI).NotTo(BeEmpty())
            }
        })
})
```

## Running Tests

### Basic Execution

```bash
# Run E2E tests
RUN_E2E=1 go test -v

# Run with Ginkgo directly
RUN_E2E=1 ginkgo -v

# Run specific test suite
RUN_E2E=1 ginkgo -v ./tests/my-suite/
```

### Filter by Label

```bash
# Run only smoke tests
RUN_E2E=1 ginkgo --label-filter="smoke" ./...

# Run all except slow tests
RUN_E2E=1 ginkgo --label-filter="!slow" ./...
```

### Filter by Name

```bash
# Run specific test
RUN_E2E=1 ginkgo --focus="should have healthy nodes" ./...

# Skip specific test
RUN_E2E=1 ginkgo --skip="flaky test" ./...
```

## Network Reuse for Faster Iteration

Network bootstrap is slow (2-5 minutes). Reuse networks across test runs:

### First Run: Create Network

```bash
RUN_E2E=1 ginkgo -v
# Creates network in ~/.tmpnet/networks/[timestamp]
```

The network directory will be printed:

```
Network created at: /home/user/.tmpnet/networks/20250312-143052.123456
```

### Subsequent Runs: Reuse Network

```bash
# Reuse existing network (skips bootstrap)
RUN_E2E=1 ginkgo -v -- --reuse-network --network-dir=/home/user/.tmpnet/networks/20250312-143052.123456

# Or export TMPNET_NETWORK_DIR and pass --reuse-network
export TMPNET_NETWORK_DIR=/home/user/.tmpnet/networks/20250312-143052.123456
RUN_E2E=1 ginkgo -v -- --reuse-network
```

### Stop Existing Networks

```bash
tmpnetctl stop-network --network-dir=/home/user/.tmpnet/networks/20250312-143052.123456
```

## Testing with Multiple L1s

Most tests need multiple L1s (chains) for cross-chain scenarios. Here's the standard two-L1 setup:

### Complete Example

```go title="two_l1s_test.go"
package mypackage_test

import (
    "context"
    "flag"
    "math/big"
    "os"
    "testing"
    "time"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/e2e"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/utils/logging"
    "github.com/ethereum/go-ethereum/crypto"
    "github.com/ethereum/go-ethereum/ethclient"
    "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

// L1TestInfo holds information about an L1
type L1TestInfo struct {
    SubnetID     ids.ID
    BlockchainID ids.ID
    NodeURIs     []string
    RPCClient    *ethclient.Client
    EVMChainID   *big.Int
    Name         string
}

var (
    network  *tmpnet.Network
    e2eFlags *e2e.FlagVars
    l1A      L1TestInfo
    l1B      L1TestInfo
)

func TestMain(m *testing.M) {
    e2eFlags = e2e.RegisterFlags()
    flag.Parse()
    os.Exit(m.Run())
}

func TestTwoL1s(t *testing.T) {
    if os.Getenv("RUN_E2E") == "" {
        t.Skip("RUN_E2E not set")
    }

    RegisterFailHandler(ginkgo.Fail)
    ginkgo.RunSpecs(t, "Two L1s Test Suite")
}

var _ = ginkgo.BeforeSuite(func() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
    defer cancel()

    runtimeCfg, err := e2eFlags.NodeRuntimeConfig()
    Expect(err).NotTo(HaveOccurred())

    nodes := tmpnet.NewNodesOrPanic(4)

    // Create network with 2 subnets (helpers like utils.NewTmpnetSubnet set genesis/config)
    network = &tmpnet.Network{
        Owner: "two-l1s-test",
        Nodes: nodes,
        Subnets: []*tmpnet.Subnet{
            {
                Name: "L1-A",
                ValidatorIDs: tmpnet.NodesToIDs(nodes[:2]),
                Chains: []*tmpnet.Chain{{
                    VMID:   constants.EVMID,
                    Config: `{"log-level": "info"}`,
                }},
            },
            {
                Name: "L1-B",
                ValidatorIDs: tmpnet.NodesToIDs(nodes[2:]),
                Chains: []*tmpnet.Chain{{
                    VMID:   constants.EVMID,
                    Config: `{"log-level": "info"}`,
                }},
            },
        },
        DefaultRuntimeConfig: *runtimeCfg,
    }

    err = tmpnet.BootstrapNewNetwork(
        ctx,
        logging.NoLog{},
        network,
        e2eFlags.RootNetworkDir(),
    )
    Expect(err).NotTo(HaveOccurred())

    // Set up L1 info
    l1A = getL1Info(network.Subnets[0], "L1-A")
    l1B = getL1Info(network.Subnets[1], "L1-B")
})

var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        network.Stop(context.Background())
    }
})

> For runnable code, supply real genesis bytes/config for each chain (see `tests/contracts/lib/icm-contracts/lib/subnet-evm/tests/utils/tmpnet.go` in icm-services for a working helper).

// Helper to extract L1 info
func getL1Info(subnet *tmpnet.Subnet, name string) L1TestInfo {
    chain := subnet.Chains[0]

    rpcClient, err := ethclient.Dial(chain.Nodes[0].URI + "/ext/bc/" + chain.ChainID.String() + "/rpc")
    Expect(err).NotTo(HaveOccurred())

    evmChainID, err := rpcClient.ChainID(context.Background())
    Expect(err).NotTo(HaveOccurred())

    var nodeURIs []string
    for _, node := range chain.Nodes {
        nodeURIs = append(nodeURIs, node.URI)
    }

    return L1TestInfo{
        SubnetID:     subnet.SubnetID,
        BlockchainID: chain.ChainID,
        NodeURIs:     nodeURIs,
        RPCClient:    rpcClient,
        EVMChainID:   evmChainID,
        Name:         name,
    }
}

var _ = ginkgo.Describe("[Two L1 Tests]", func() {
    ginkgo.It("should have two L1s configured", func() {
        Expect(l1A.Name).To(Equal("L1-A"))
        Expect(l1B.Name).To(Equal("L1-B"))
        Expect(l1A.EVMChainID.Uint64()).To(Equal(uint64(12345)))
        Expect(l1B.EVMChainID.Uint64()).To(Equal(uint64(54321)))
    })
})
```

## Using Pre-funded Keys

Every tmpnet network has pre-funded keys for transactions:

```go
var _ = ginkgo.Describe("[Funded Keys]", func() {
    ginkgo.It("should have pre-funded key", func() {
        // Get first pre-funded key
        key := network.PreFundedKeys[0]
        ecdsaKey := key.ToECDSA()

        // Get address
        address := crypto.PubkeyToAddress(ecdsaKey.PublicKey)

        // Check balance on LUExchange-Chain
        balance, err := l1A.RPCClient.BalanceAt(
            context.Background(),
            address,
            nil,
        )
        Expect(err).NotTo(HaveOccurred())
        Expect(balance.Uint64()).To(BeNumerically(">", 0))
    })
})
```

## Best Practices

### 1. Use BeforeSuite for Expensive Setup

```go
// Good: Share network across tests
var _ = ginkgo.BeforeSuite(func() {
    network = createNetwork()
})

// Avoid: Creating network per test (very slow)
var _ = ginkgo.BeforeEach(func() {
    network = createNetwork() // Don't do this!
})
```

### 2. Use Appropriate Timeouts

```go
// Network bootstrap: 5-10 minutes
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)

// Individual operations: 30-60 seconds
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
```

### 3. Always Clean Up

```go
var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        Expect(network.Stop(context.Background())).To(Succeed())
    }
})
```

### 4. Use Labels for Organization

```go
ginkgo.It("test name",
    ginkgo.Label("smoke", "fast"),
    func() {
        // Test code
    })
```

### 5. Use Eventually for Async Operations

```go
// Good: Poll with Eventually
Eventually(func() bool {
    return node.IsHealthy()
}, 30*time.Second, 500*time.Millisecond).Should(BeTrue())

// Avoid: Fixed sleep
time.Sleep(10 * time.Second) // Don't do this!
```

## Debugging Tests

### Enable Verbose Logging

```bash
RUN_E2E=1 ginkgo -v -trace ./...
```

### Print Network Directory

Add to your BeforeSuite:

```go
var _ = ginkgo.BeforeSuite(func() {
    // ... create network ...

    ginkgo.GinkgoWriter.Printf("Network directory: %s\n", network.Dir)
})
```

### Keep Network After Failure

Manually stop the network if a test fails to inspect logs:

```bash
# Run test
RUN_E2E=1 ginkgo -v

# If test fails, network stays running
# Inspect logs in network directory

# Stop when done debugging
tmpnet stop --dir=/path/to/network
```

## Common Patterns

### Get Node URIs

```go
uris := network.GetNodeURIs()
for _, uri := range uris {
    ginkgo.GinkgoWriter.Printf("Node: %s\n", uri)
}
```

### Check All Nodes Healthy

```go
for _, node := range network.Nodes {
    Expect(node.IsHealthy()).To(BeTrue())
}
```

### Wait for Node Health

```go
err := node.WaitForHealthy(context.Background())
Expect(err).NotTo(HaveOccurred())
```

## Next Steps

<Cards>
  <Card title="L1 Conversion" href="/docs/tooling/tmpnet/guides/l1-conversion">
    Convert subnets to L1s with validator managers
  </Card>
  <Card title="Cross-Chain Messaging" href="/docs/tooling/tmpnet/guides/cross-chain-messaging">
    Test Teleporter message flows between L1s
  </Card>
  <Card title="Validator Management" href="/docs/tooling/tmpnet/guides/validator-management-native-staking">
    Test validator registration and delegation
  </Card>
  <Card title="Warp Messages" href="/docs/tooling/tmpnet/guides/warp-messages">
    Test Warp message construction and verification
  </Card>
</Cards>

## Additional Resources

- [Ginkgo Documentation](https://onsi.github.io/ginkgo/)
- [Gomega Matchers](https://onsi.github.io/gomega/)
- [ICM Services Tests](https://github.com/luxfi/icm-services/tree/main/tests)
- [tmpnet Package Docs](https://pkg.go.dev/github.com/luxfi/luxgo/tests/fixture/tmpnet)


# Testing L1 Conversion (/docs/tooling/tmpnet/guides/l1-conversion)

---
title: Testing L1 Conversion
description: Learn how to convert subnets to L1s with validator managers in your tests
---

This guide shows how to test converting a subnet to an L1 (Layer 1) blockchain with a validator manager. L1 conversion is the process of upgrading a subnet to use Proof of Stake consensus with custom validator management.

> Pattern guide only. These snippets mirror helpers in `icm-services` (for example `icm-contracts/tests/network`) and rely on shared utilities for genesis creation, contract bindings, and Warp signing. Copy from those source files for runnable code.

## Overview

Converting a subnet to an L1 involves:

1. Deploying a validator manager contract
2. Issuing a `ConvertSubnetToL1Tx` on the Platform-Chain
3. Initializing the validator set with a Warp message
4. Managing validator registration and removal

## Prerequisites

- Complete the [Getting Started](/docs/tooling/tmpnet/guides/getting-started) guide
- Understand basic Ginkgo test setup
- Have a network with at least one L1 created

## Validator Manager Types

Choose one of three validator manager types:

| Type | Description | Use Case |
|------|-------------|----------|
| **PoA** | Proof of Authority | Permissioned networks with owner-controlled validators |
| **Native Token Staking** | Stake native chain tokens | Public networks using chain's native currency |
| **ERC20 Token Staking** | Stake ERC20 tokens | Networks with custom governance tokens |

## Basic L1 Conversion Flow

### Complete Test Example

```go title="l1_conversion_test.go"
package conversion_test

import (
    "context"
    "flag"
    "math/big"
    "os"
    "testing"
    "time"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/e2e"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/units"
    "github.com/luxfi/luxgo/utils/crypto/secp256k1"
    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/crypto"
    "github.com/ethereum/go-ethereum/ethclient"
    "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var (
    network      *tmpnet.Network
    e2eFlags     *e2e.FlagVars
    fundedKey    *secp256k1.PrivateKey
    l1Info       L1TestInfo
)

func TestMain(m *testing.M) {
    e2eFlags = e2e.RegisterFlags()
    flag.Parse()
    os.Exit(m.Run())
}

func TestL1Conversion(t *testing.T) {
    if os.Getenv("RUN_E2E") == "" {
        t.Skip("RUN_E2E not set")
    }

    RegisterFailHandler(ginkgo.Fail)
    ginkgo.RunSpecs(t, "L1 Conversion Test Suite")
}

var _ = ginkgo.BeforeSuite(func() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
    defer cancel()

    // Create network with one L1
    network = createNetworkWithL1(ctx)

    // Get funded key
    fundedKey = network.PreFundedKeys[0]

    // Get L1 info
    l1Info = getL1Info(network.Subnets[0])
})

var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        network.Stop(context.Background())
    }
})

var _ = ginkgo.Describe("[L1 Conversion]", func() {
    ginkgo.It("should convert subnet to L1 with native staking",
        ginkgo.Label("conversion", "native-staking"),
        func() {
            ctx := context.Background()

            // Convert subnet to L1
            nodes, validationIDs := convertSubnetToL1(
                ctx,
                network,
                l1Info,
                NativeTokenStakingManager,
                fundedKey,
            )

            Expect(nodes).To(HaveLen(2))
            Expect(validationIDs).To(HaveLen(2))

            // Verify validators are active
            for _, validationID := range validationIDs {
                status := getValidatorStatus(ctx, l1Info, validationID)
                Expect(status).To(Equal(ValidatorStatusActive))
            }
        })
})
```

## ConvertSubnet Implementation

### The ConvertSubnet Function

Here's the core conversion logic based on ICM Services:

```go title="conversion.go"
package conversion

import (
    "context"
    "math/big"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/vms/platformvm/warp"
    "github.com/ethereum/go-ethereum/common"
)

type ValidatorManagerType int

const (
    PoAValidatorManager ValidatorManagerType = iota
    NativeTokenStakingManager
    ERC20TokenStakingManager
)

// ConvertSubnet converts a subnet to an L1 with validator manager
func ConvertSubnet(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    managerType ValidatorManagerType,
    weights []uint64,
    fundedKey *ecdsa.PrivateKey,
) ([]*tmpnet.Node, []ids.ID) {

    // Step 1: Deploy validator manager
    validatorManagerAddress := deployValidatorManager(
        ctx,
        l1,
        managerType,
        fundedKey,
    )

    // Step 2: Initialize validator manager settings
    initializeValidatorManager(
        ctx,
        l1,
        validatorManagerAddress,
        managerType,
        fundedKey,
    )

    // Step 3: Add new nodes to network
    numValidators := len(weights)
    newNodes := make([]*tmpnet.Node, numValidators)

    for i := 0; i < numValidators; i++ {
        node := tmpnet.NewEphemeralNode(tmpnet.FlagsMap{})
        err := network.StartNode(ctx, node)
        Expect(err).NotTo(HaveOccurred())

        err = node.WaitForHealthy(ctx)
        Expect(err).NotTo(HaveOccurred())

        newNodes[i] = node
    }

    // Step 4: Issue ConvertSubnetToL1Tx on Platform-Chain
    convertSubnetTxID := issueConvertSubnetToL1Tx(
        ctx,
        network,
        l1.SubnetID,
        validatorManagerAddress,
        fundedKey,
    )

    // Step 5: Initialize validator set with Warp message
    initialValidationIDs := initializeValidatorSet(
        ctx,
        network,
        l1,
        validatorManagerAddress,
        newNodes,
        weights,
        convertSubnetTxID,
        fundedKey,
    )

    // Step 6: Add new nodes as L1 validators
    for i, node := range newNodes {
        addNodeToL1(ctx, network, l1, node)
    }

    return newNodes, initialValidationIDs
}

// deployValidatorManager deploys the appropriate validator manager contract
func deployValidatorManager(
    ctx context.Context,
    l1 L1TestInfo,
    managerType ValidatorManagerType,
    fundedKey *ecdsa.PrivateKey,
) common.Address {

    var address common.Address

    switch managerType {
    case PoAValidatorManager:
        address = deployPoAValidatorManager(ctx, l1, fundedKey)
    case NativeTokenStakingManager:
        address = deployNativeStakingManager(ctx, l1, fundedKey)
    case ERC20TokenStakingManager:
        address = deployERC20StakingManager(ctx, l1, fundedKey)
    }

    return address
}

// initializeValidatorManager sets up initial validator manager parameters
func initializeValidatorManager(
    ctx context.Context,
    l1 L1TestInfo,
    managerAddress common.Address,
    managerType ValidatorManagerType,
    fundedKey *ecdsa.PrivateKey,
) {

    switch managerType {
    case PoAValidatorManager:
        // PoA: Set owner address
        ownerAddress := crypto.PubkeyToAddress(fundedKey.PublicKey)
        initializePoA(ctx, l1, managerAddress, ownerAddress, fundedKey)

    case NativeTokenStakingManager:
        // Native Staking: Set staking parameters
        settings := NativeTokenStakingSettings{
            MinStakeDuration:      1,
            MinStakeAmount:        big.NewInt(1e16),
            MaxStakeAmount:        big.NewInt(10e18),
            MinDelegateFee:        1,
            MaxChurnPercentage:    20,
            ChurnPeriodSeconds:    1,
            WeightToValueFactor:   big.NewInt(1e12),
        }
        initializeNativeStaking(ctx, l1, managerAddress, settings, fundedKey)

    case ERC20TokenStakingManager:
        // ERC20 Staking: Set token and parameters
        tokenAddress := common.HexToAddress("0x...") // Your ERC20 token
        settings := ERC20TokenStakingSettings{
            MinStakeDuration:    1,
            MinStakeAmount:      big.NewInt(1e18),
            MaxStakeAmount:      big.NewInt(1000e18),
            MinDelegateFee:      1,
            MaxChurnPercentage:  20,
            ChurnPeriodSeconds:  1,
        }
        initializeERC20Staking(ctx, l1, managerAddress, tokenAddress, settings, fundedKey)
    }
}

// issueConvertSubnetToL1Tx issues the conversion transaction on Platform-Chain
func issueConvertSubnetToL1Tx(
    ctx context.Context,
    network *tmpnet.Network,
    subnetID ids.ID,
    validatorManagerAddress common.Address,
    fundedKey *ecdsa.PrivateKey,
) ids.ID {

    // Get Platform-Chain wallet
    pChainWallet := network.GetPChainWallet(fundedKey)

    // Convert address to proper format
    managerAddressBytes := validatorManagerAddress.Bytes()
    var chainAddress [20]byte
    copy(chainAddress[:], managerAddressBytes)

    // Issue ConvertSubnetToL1Tx
    txID, err := pChainWallet.IssueConvertSubnetToL1Tx(
        subnetID,
        chainAddress,
        fundedKey,
    )
    Expect(err).NotTo(HaveOccurred())

    return txID
}

// initializeValidatorSet creates initial validators with Warp message
func initializeValidatorSet(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    validatorManagerAddress common.Address,
    nodes []*tmpnet.Node,
    weights []uint64,
    convertTxID ids.ID,
    fundedKey *ecdsa.PrivateKey,
) []ids.ID {

    // Build initial validator set
    validatorSet := make([]InitialValidator, len(nodes))
    for i, node := range nodes {
        validationID := createValidationID(node.NodeID, l1.SubnetID)

        validatorSet[i] = InitialValidator{
            NodeID:       node.NodeID.Bytes(),
            Weight:       weights[i],
            BlsPublicKey: node.BlsPublicKey,
        }
    }

    // Create SubnetToL1ConversionMessage
    conversionData := SubnetToL1ConversionData{
        SubnetID:                  l1.SubnetID,
        ManagerBlockchainID:       l1.BlockchainID,
        ManagerAddress:            validatorManagerAddress.Bytes(),
        Validators:                validatorSet,
    }

    // Sign with Platform-Chain validators
    unsignedMessage := warp.NewUnsignedMessage(
        network.NetworkID,
        l1.BlockchainID,
        encodeConversionData(conversionData),
    )

    signedMessage := signWarpMessage(
        ctx,
        network,
        unsignedMessage,
        l1.SubnetID,
    )

    // Initialize validator set on contract
    validatorManager := getValidatorManagerContract(l1, validatorManagerAddress)

    tx := initializeValidatorSet(
        ctx,
        l1,
        validatorManager,
        conversionData,
        signedMessage.Bytes(),
        fundedKey,
    )

    receipt := waitForSuccess(ctx, l1, tx.Hash())

    // Extract validation IDs from events
    validationIDs := extractValidationIDsFromReceipt(receipt)

    return validationIDs
}
```

## Testing Different Validator Manager Types

### PoA (Proof of Authority)

```go
ginkgo.It("should convert to PoA",
    ginkgo.Label("poa"),
    func() {
        nodes, validationIDs := convertSubnetToL1(
            context.Background(),
            network,
            l1Info,
            PoAValidatorManager,
            fundedKey,
        )

        Expect(nodes).To(HaveLen(2))
        Expect(validationIDs).To(HaveLen(2))
    })
```

### Native Token Staking

```go
ginkgo.It("should convert to native staking",
    ginkgo.Label("native-staking"),
    func() {
        // Use different weights for validators
        weights := []uint64{
            1 * units.Schmeckle,      // Validator 1: 1 LUX
            1000 * units.Schmeckle,   // Validator 2: 1000 LUX
        }

        nodes, validationIDs := convertSubnetToL1WithWeights(
            context.Background(),
            network,
            l1Info,
            NativeTokenStakingManager,
            weights,
            fundedKey,
        )

        Expect(nodes).To(HaveLen(2))
        Expect(validationIDs).To(HaveLen(2))

        // Verify weights
        for i, validationID := range validationIDs {
            weight := getValidatorWeight(context.Background(), l1Info, validationID)
            Expect(weight).To(Equal(weights[i]))
        }
    })
```

### ERC20 Token Staking

```go
ginkgo.It("should convert to ERC20 staking",
    ginkgo.Label("erc20-staking"),
    func() {
        // Deploy ERC20 token first
        tokenAddress, token := deployERC20Token(
            context.Background(),
            l1Info,
            fundedKey,
            "Staking Token",
            "STK",
        )

        // Convert with ERC20 manager
        nodes, validationIDs := convertSubnetToL1WithERC20(
            context.Background(),
            network,
            l1Info,
            tokenAddress,
            fundedKey,
        )

        Expect(nodes).To(HaveLen(2))
        Expect(validationIDs).To(HaveLen(2))
    })
```

## Verifying Conversion Success

### Check Validator Status

```go
func verifyValidatorsActive(
    ctx context.Context,
    l1 L1TestInfo,
    validationIDs []ids.ID,
) {
    validatorManager := getValidatorManagerContract(l1)

    for _, validationID := range validationIDs {
        validator, err := validatorManager.GetValidator(
            &bind.CallOpts{},
            validationID,
        )
        Expect(err).NotTo(HaveOccurred())

        Expect(validator.Status).To(Equal(ValidatorStatusActive))
        Expect(validator.Weight).To(BeNumerically(">", 0))
    }
}
```

### Check Platform-Chain State

```go
func verifyPChainValidators(
    ctx context.Context,
    network *tmpnet.Network,
    subnetID ids.ID,
    expectedCount int,
) {
    pClient := network.GetPChainClient()

    validators, err := pClient.GetCurrentValidators(ctx, subnetID, nil)
    Expect(err).NotTo(HaveOccurred())

    Expect(validators).To(HaveLen(expectedCount))
}
```

## Common Patterns

### Conversion with Proxy

For upgradeable validator managers:

```go
nodes, validationIDs, proxyAdmin := convertSubnetToL1WithProxy(
    ctx,
    network,
    l1Info,
    NativeTokenStakingManager,
    fundedKey,
)

// Can upgrade later
newImplementation := deployNewImplementation(ctx, l1Info, fundedKey)
upgradeProxy(ctx, l1Info, proxyAdmin, newImplementation, fundedKey)
```

### Multiple Validators with Different Weights

```go
weights := []uint64{
    100,   // Light validator
    1000,  // Medium validator
    10000, // Heavy validator
}

nodes, validationIDs := convertSubnetToL1WithWeights(
    ctx, network, l1Info, NativeTokenStakingManager, weights, fundedKey,
)
```

## Best Practices

1. **Use generous timeouts**: Conversion involves Platform-Chain transactions which can be slow
2. **Verify all steps**: Check validator status after conversion
3. **Test different weights**: Ensure validator weighting works correctly
4. **Handle errors**: Platform-Chain operations can fail, plan for retries
5. **Clean up**: Stop extra nodes in AfterEach if creating new networks per test

## Troubleshooting

### Conversion Transaction Fails

```go
// Add retry logic
var txID ids.ID
err := retry.Do(func() error {
    var err error
    txID, err = issueConvertSubnetToL1Tx(ctx, network, subnetID, managerAddress, fundedKey)
    return err
}, retry.Attempts(3), retry.Delay(time.Second))
```

### Warp Message Not Signed

Ensure all validators have accepted the block:

```go
waitForAllValidatorsToAcceptBlock(
    ctx,
    l1.NodeURIs,
    l1.BlockchainID,
    receipt.BlockNumber.Uint64(),
)
```

## Next Steps

<Cards>
  <Card title="Native Token Staking" href="/docs/tooling/tmpnet/guides/validator-management-native-staking">
    Test complete validator lifecycle with native tokens
  </Card>
  <Card title="Staking and Delegation" href="/docs/tooling/tmpnet/guides/staking-and-delegation">
    Test staking and delegation workflows
  </Card>
  <Card title="Cross-Chain Messaging" href="/docs/tooling/tmpnet/guides/cross-chain-messaging">
    Test messaging between converted L1s
  </Card>
</Cards>


# Monitoring (/docs/tooling/tmpnet/guides/monitoring)

---
title: Monitoring
description: Monitor your temporary networks with metrics, logs, and dashboards
---

This guide shows you how to set up monitoring for your temporary networks using Prometheus for metrics and Promtail for logs.

## Overview

tmpnet provides built-in integration with:

- **Prometheus** - Collect and store metrics from all nodes
- **Promtail** - Aggregate logs from all nodes
- **Grafana** - Visualize metrics and logs in dashboards

Monitoring helps you:
- Debug network behavior
- Identify performance bottlenecks
- Analyze consensus patterns
- Track resource usage
- Troubleshoot issues

## Prerequisites

### Install Monitoring Tools

The easiest way to get the required tools is using Nix:

```bash
# Start a development shell with monitoring tools
nix develop
```

This provides both `prometheus` and `promtail` binaries.

### Alternative: Manual Installation

Install tools manually if you don't use Nix:

**Prometheus:**
```bash
# macOS
brew install prometheus

# Linux - download from prometheus.io/download
```

**Promtail:**
```bash
# Download from GitHub releases
# github.com/grafana/loki/releases
```

### Configure Monitoring Backend

You'll need access to a Prometheus and Loki backend. Set these environment variables:

```bash
export PROMETHEUS_URL="https://your-prometheus.example.com"
export PROMETHEUS_PUSH_URL="https://your-prometheus.example.com/api/v1/push"
export PROMETHEUS_USERNAME="your-username"
export PROMETHEUS_PASSWORD="your-password"

export LOKI_URL="https://your-loki.example.com"
export LOKI_PUSH_URL="https://your-loki.example.com/loki/api/v1/push"
export LOKI_USERNAME="your-username"
export LOKI_PASSWORD="your-password"
```

## Quick Start

### Start Collectors

Start Prometheus and Promtail collectors:

```bash
# Start metrics collection
tmpnetctl start-metrics-collector

# Start log collection
tmpnetctl start-logs-collector
```

### Start Your Network

Create a network - monitoring will be automatic:

```bash
tmpnetctl start-network
```

**Output includes a Grafana link:**
```
Started network /home/user/.tmpnet/networks/20240312-143052.123456
Network metrics: https://grafana.example.com/...
```

### View Metrics and Logs

Click the Grafana link or open the URL saved at:
```bash
cat ~/.tmpnet/networks/latest/metrics.txt
```

### Stop Collectors

When done, stop the collectors:

```bash
tmpnetctl stop-metrics-collector
tmpnetctl stop-logs-collector
```

## Monitoring Configuration

### Service Discovery

tmpnet uses file-based service discovery to automatically configure monitoring:

**Prometheus Configuration:**
```
~/.tmpnet/prometheus/file_sd_configs/
└── [network-uuid]-[node-id].json
```

**Promtail Configuration:**
```
~/.tmpnet/promtail/file_sd_configs/
└── [network-uuid]-[node-id].json
```

When a node starts, tmpnet automatically creates these configuration files. When a node stops, the files are removed.

### Metric Labels

All metrics include these labels for filtering:

- `network_uuid` - Unique identifier for the network
- `node_id` - Node ID
- `is_ephemeral_node` - Whether the node is ephemeral
- `network_owner` - User-defined network owner identifier

When running in GitHub Actions, additional labels are added:
- `gh_repo` - Repository name
- `gh_workflow` - Workflow name
- `gh_run_id` - Run ID
- `gh_job_id` - Job ID

### Custom Grafana Instance

Use a custom Grafana instance:

```bash
export GRAFANA_URI="https://your-grafana.example.com/d/your-dashboard-id"
```

The emitted links will use your custom Grafana instance.

## Monitoring in Code

### Enable Monitoring Programmatically

Start collectors from Go code:

```go
import "github.com/luxfi/luxgo/tests/fixture/tmpnet"

// Start Prometheus
err := tmpnet.StartPrometheus(
    prometheusURL,
    prometheusUsername,
    prometheusPassword,
    pushURL,
    os.Stdout, // Progress output
)
if err != nil {
    panic(err)
}

// Start Promtail
err = tmpnet.StartPromtail(
    lokiURL,
    lokiUsername,
    lokiPassword,
    pushURL,
    os.Stdout,
)
if err != nil {
    panic(err)
}
```

### Verify Collection

Check that metrics and logs are being collected:

```go
// Check metrics
err := tmpnet.CheckMetricsExist(context.Background(), prometheusURL, prometheusUsername, prometheusPassword, network.UUID)
if err != nil {
    fmt.Println("Metrics not found:", err)
}

// Check logs
err = tmpnet.CheckLogsExist(context.Background(), lokiURL, lokiUsername, lokiPassword, network.UUID)
if err != nil {
    fmt.Println("Logs not found:", err)
}
```

## Monitoring Patterns

### Development Workflow

For local development:

```bash
# Start collectors once
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector

# Create/destroy networks as needed
tmpnetctl start-network
# ... test ...
tmpnetctl stop-network

# Collectors keep running
# Stop when done with all testing
tmpnetctl stop-metrics-collector
tmpnetctl stop-logs-collector
```

### Test Isolation

Filter to specific networks using the network UUID:

```
# In Grafana, filter by:
network_uuid="abc-123-def-456"
```

Each network gets a unique UUID, making it easy to isolate results.

### Ephemeral Node Monitoring

Track ephemeral nodes separately:

```
# Filter to only ephemeral nodes:
is_ephemeral_node="true"

# Filter to only permanent nodes:
is_ephemeral_node="false"
```

## Common Metrics

tmpnet collects standard LuxGo metrics:

### Node Health
- `lux_network_peers` - Number of connected peers
- `lux_P_vm_blks_accepted` - Accepted blocks on Platform-Chain
- `lux_health_checks_failing` - Failing health checks

### Network Activity
- `lux_network_msgs_sent` - Messages sent
- `lux_network_msgs_received` - Messages received
- `lux_network_bandwidth_throttler_inbound_acquired_bytes` - Inbound bandwidth

### Consensus
- `lux_snowman_polls_successful` - Successful consensus polls
- `lux_snowman_polls_failed` - Failed consensus polls
- `lux_P_blks_processing` - Blocks currently processing

### Performance
- `lux_P_vm_blks_processing_time` - Block processing time
- `go_goroutines` - Number of goroutines
- `go_memstats_alloc_bytes` - Memory allocated

### Custom VM Metrics

If your custom VM exports Prometheus metrics, they'll be collected automatically.

## Log Collection

### Log Levels

Configure log verbosity per node:

```go
node.Flags = tmpnet.FlagsMap{
    "log-level": "debug", // trace, debug, info, warn, error, fatal
    "log-display-level": "info",
}
```

### Log Queries in Grafana

Example queries in Grafana Explore (Loki):

```text
# All logs for a network
{network_uuid="abc-123"}

# Error logs only
{network_uuid="abc-123"} |= "error" or "ERROR"

# Logs from a specific node
{network_uuid="abc-123", node_id="NodeID-7Xhw2..."}

# Search for specific patterns
{network_uuid="abc-123"} |= "consensus"

# Regex search
{network_uuid="abc-123"} |~ "block \\d+ accepted"
```

### Structured Logging

Enable JSON structured logging for easier parsing:

```go
network.DefaultFlags = tmpnet.FlagsMap{
    "log-format": "json",
}
```

## Troubleshooting

### Collectors Won't Start

**Check if already running:**
```bash
ps aux | grep prometheus
ps aux | grep promtail
```

**Stop existing processes:**
```bash
tmpnetctl stop-metrics-collector
tmpnetctl stop-logs-collector
```

### No Metrics Appear

**Verify collectors are running:**
```bash
ps aux | grep prometheus
```

**Check service discovery configs exist:**
```bash
ls ~/.tmpnet/prometheus/file_sd_configs/
```

**Verify network UUID:**
```bash
cat ~/.tmpnet/networks/latest/config.json | jq -r '.uuid'
```

**Check Prometheus is scraping:**
```bash
# Check Prometheus logs
tail -f ~/.tmpnet/prometheus/*.log
```

### No Logs Appear

**Check Promtail is running:**
```bash
ps aux | grep promtail
```

**Verify log files exist:**
```bash
ls ~/.tmpnet/networks/latest/NodeID-*/logs/
```

**Check Promtail configuration:**
```bash
ls ~/.tmpnet/promtail/file_sd_configs/
```

### Can't Access Grafana

**Check the metrics link:**
```bash
cat ~/.tmpnet/networks/latest/metrics.txt
```

**Verify GRAFANA_URI is set:**
```bash
echo $GRAFANA_URI
```

**Check network UUID is in the URL:**
The URL should contain `var-network_uuid=YOUR_UUID`

## CI/CD Integration

### GitHub Actions

Use the provided GitHub Action for automated monitoring:

```yaml
- name: Run tests with monitoring
  uses: ./.github/actions/run-monitored-tmpnet-cmd
  with:
    run: ./scripts/test.sh
    prometheus_url: ${{ secrets.PROMETHEUS_URL }}
    prometheus_push_url: ${{ secrets.PROMETHEUS_PUSH_URL }}
    prometheus_username: ${{ secrets.PROMETHEUS_USERNAME }}
    prometheus_password: ${{ secrets.PROMETHEUS_PASSWORD }}
    loki_url: ${{ secrets.LOKI_URL }}
    loki_push_url: ${{ secrets.LOKI_PUSH_URL }}
    loki_username: ${{ secrets.LOKI_USERNAME }}
    loki_password: ${{ secrets.LOKI_PASSWORD }}
```

The action automatically:
- Starts collectors
- Runs your tests
- Stops collectors
- Uploads network artifacts
- Emits Grafana links in logs

### Custom CI Systems

For other CI systems:

```bash
#!/bin/bash
set -e

# Start collectors
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector

# Ensure cleanup on exit
trap "tmpnetctl stop-metrics-collector; tmpnetctl stop-logs-collector" EXIT

# Run your tests
./run-tests.sh

# Metrics link is in the network directory
cat ~/.tmpnet/networks/latest/metrics.txt
```

## Advanced Monitoring

### Custom Metrics Dashboard

Create custom Grafana dashboards using tmpnet labels:

```
# Panel: Network Message Rate
rate(lux_network_msgs_sent{network_uuid="$network_uuid"}[1m])

# Panel: Block Processing Time (Platform-Chain)
histogram_quantile(0.99, rate(lux_P_vm_blks_processing_time_bucket[5m]))

# Panel: Active Validators
lux_P_vm_validators_count{network_uuid="$network_uuid"}
```

### Alerting

Set up alerts based on network behavior:

```
# Alert when nodes disconnect
lux_network_peers < 4

# Alert on high block processing time
histogram_quantile(0.99, rate(lux_P_vm_blks_processing_time_bucket[5m])) > 1000

# Alert on failed health checks
lux_health_checks_failing > 0
```

### Metric Retention

Metrics are retained according to your Prometheus backend configuration. For long-running tests, ensure sufficient retention.

## Next Steps

<Cards>
  <Card title="Configuration Reference" href="/docs/tooling/tmpnet/reference/configuration">
    Detailed configuration options
  </Card>
  <Card title="CLI Reference" href="/docs/tooling/tmpnet/reference/cli-commands">
    Complete tmpnetctl commands
  </Card>
</Cards>

## Additional Resources

- [Prometheus Documentation](https://prometheus.io/docs/)
- [Grafana Loki Documentation](https://grafana.com/docs/loki/)
- [LuxGo Metrics](/docs/nodes/metrics)
- [Full tmpnet README - Monitoring Section](https://github.com/luxfi/luxgo/blob/master/tests/fixture/tmpnet/README.md#monitoring)


# Runtime Environments (/docs/tooling/tmpnet/guides/runtimes)

---
title: Runtime Environments
description: Choose between local process and Kubernetes runtimes for tmpnet test networks
---

Runtimes in tmpnet provide the execution environment for your test network nodes. The `NodeRuntime` interface abstracts the complexity of managing node processes, allowing you to focus on testing your blockchain application rather than infrastructure details.

At its core, tmpnet's runtime system defines how and where nodes run. The `NodeRuntime` interface provides a consistent API for starting nodes, managing their lifecycle, and interacting with their endpoints—regardless of whether nodes run as local processes or Kubernetes pods. This abstraction means you write your test setup once and can switch runtimes based on your testing needs.

```go
// The NodeRuntime interface abstracts execution environment
type NodeRuntime interface {
    Start(ctx context.Context) error
    InitiateStop(ctx context.Context) error
    WaitForStopped(ctx context.Context) error
    Restart(ctx context.Context) error
    IsHealthy(ctx context.Context) (bool, error)
    // ...
}
```

### When to Use Each Runtime

| Scenario | Recommended Runtime |
|----------|-------------------|
| Local development and quick iteration | Local Process |
| CI/CD pipelines | Kubernetes |
| Networks with 1-10 nodes | Local Process |
| Networks with 10+ nodes | Kubernetes |
| Production environment testing | Kubernetes |
| Laptop/desktop testing | Local Process |

<Callout type="info">
The Local Process Runtime is ideal for development and small-scale testing. For production-like environments, multi-machine deployments, or CI/CD pipelines, use the Kubernetes Runtime.
</Callout>

---

## Local Process Runtime

The Local Process Runtime runs Lux nodes as operating system subprocesses on your local machine. Each node executes as an independent process with its own configuration, dynamically allocated ports, and isolated filesystem state.

### How It Works

When you create a network using the Local Process Runtime, tmpnet performs the following workflow:

1. **Binary Validation** - Verifies the LuxGo binary exists at the configured path
2. **Network Directory Creation** - Creates `~/.tmpnet/networks/[timestamp]/` with subdirectories for each node
3. **Node Configuration** - Generates node-specific config files with dynamic port allocation
4. **Process Spawning** - Launches each node via `exec.Command(luxGoPath, "--config-file", flagsPath)`
5. **Health Monitoring** - Polls `GET /ext/health/liveness` until all nodes are ready

Each node maintains its state in a dedicated directory structure:

```
~/.tmpnet/networks/[timestamp]/
├── config.json           # Network configuration
├── genesis.json          # Genesis file
├── network.env           # Shell environment
├── metrics.txt           # Grafana dashboard link
├── NodeID-7Xhw2.../
│   ├── config.json       # Node runtime config
│   ├── flags.json        # Node flags
│   ├── process.json      # PID, URI, staking address
│   ├── db/               # Node database
│   ├── logs/main.log     # Node logs
│   └── plugins/          # VM plugins
└── latest -> [timestamp] # Symlink to most recent
```

Dynamic port allocation is critical for running multiple networks simultaneously. When you set API ports to `"0"`, the operating system assigns available ports automatically, preventing conflicts.

### Configuration

The `ProcessRuntimeConfig` struct controls how the Local Process Runtime operates:

```go
type ProcessRuntimeConfig struct {
    // Path to luxgo binary (required)
    LuxGoPath string

    // Directory containing VM plugin binaries
    PluginDir string

    // Reuse the same API port when restarting nodes
    ReuseDynamicPorts bool
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `LuxGoPath` | Yes | Absolute path to the `luxgo` binary executable |
| `PluginDir` | No | Directory containing VM plugin binaries (defaults to `~/.luxgo/plugins`) |
| `ReuseDynamicPorts` | No | Reuse the same API port when restarting nodes (default: `false`) |

<Callout type="warning">
The `LuxGoPath` must point to a compiled LuxGo binary. If you're building from source, run `./scripts/build.sh` before using tmpnet.
</Callout>

### Quick Start

First, ensure you have LuxGo built:

```bash
# Clone and build LuxGo
git clone https://github.com/luxfi/luxgo.git
cd luxgo
./scripts/build.sh

# The binary is now at ./build/luxgo
```

Then create your network:

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
)

func main() {
    ctx := context.Background()

    // Create network with local process runtime
    network := &tmpnet.Network{
        DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
            Process: &tmpnet.ProcessRuntimeConfig{
                // Use absolute path to your luxgo binary
                LuxGoPath:   os.Getenv("HOME") + "/luxgo/build/luxgo",
                PluginDir:         os.Getenv("HOME") + "/.luxgo/plugins",
                ReuseDynamicPorts: true,
            },
        },
        Nodes: tmpnet.NewNodesOrPanic(5),
    }

    // Bootstrap the network
    if err := tmpnet.BootstrapNewNetwork(
        ctx,
        os.Stdout,
        network,
        "",  // Use default network directory
        "",  // Use LuxGoPath from config
    ); err != nil {
        log.Fatal(err)
    }
    defer network.Stop(ctx)

    // Get node URIs for interaction
    for _, node := range network.Nodes {
        fmt.Printf("Node %s: %s\n", node.NodeID, node.URI)
    }
}
```

### Advantages

| Advantage | Description |
|-----------|-------------|
| **Fast Startup** | ~30 seconds for a 5-node network |
| **No Container Overhead** | Nodes run as native processes without virtualization |
| **Easy Debugging** | Direct access to logs at `~/.tmpnet/networks/*/NodeID-*/logs/` |
| **Prometheus Integration** | Automatic file-based service discovery |
| **Process Control** | Standard OS signals (SIGTERM, SIGSTOP) for node control |

### Limitations

| Limitation | Details |
|------------|---------|
| **Platform Support** | macOS and Linux only (Windows users should use WSL2) |
| **Single-Machine Scaling** | All nodes share CPU, memory, and disk resources |
| **Port Exhaustion** | Large networks (20+ nodes) may exhaust available ports |
| **Ephemeral State** | Network state is lost when the directory is deleted |

---

## Kubernetes Runtime

The Kubernetes runtime deploys test networks on Kubernetes clusters, providing a production-like environment for testing at scale.

### How It Works

The Kubernetes runtime implements tmpnet's network abstraction using native Kubernetes resources:

<Mermaid chart={`flowchart TB
    subgraph K8s["Kubernetes Cluster"]
        subgraph SS["StatefulSet: tmpnet-network"]
            subgraph Pod0["Pod: node-0"]
                AVA0["luxgo"]
                PVC0[("PVC-0")]
            end
            subgraph Pod1["Pod: node-1"]
                AVA1["luxgo"]
                PVC1[("PVC-1")]
            end
        end
        SVC["Ingress/Service"]
    end
    EXT["External Access<br/>(localhost:30791 for KIND)"]

    AVA0 --> PVC0
    AVA1 --> PVC1
    Pod0 --> SVC
    Pod1 --> SVC
    SVC --> EXT
`} />

**Key Components:**

- **StatefulSet**: Provides stable network identity and ordered deployment
- **PersistentVolumeClaims**: Store blockchain data, surviving pod restarts
- **Services**: Enable pod-to-pod DNS resolution
- **Ingress**: Routes external traffic to node API endpoints

### Prerequisites

Before using the Kubernetes runtime:

1. **Kubernetes Cluster**: KIND (recommended for local), Minikube, or cloud provider (GKE, EKS, AKS)
2. **kubectl CLI**: Configured with cluster access
3. **Container Registry Access**: For pulling `avaplatform/luxgo` images
4. **RBAC Permissions**: Create/manage StatefulSets, Services, Ingress, PVCs

```bash
# Verify kubectl is configured
kubectl cluster-info
kubectl auth can-i create pods --namespace=default
```

### Configuration

```go
type KubeRuntimeConfig struct {
    ConfigPath             string  // kubeconfig path (default: ~/.kube/config)
    ConfigContext          string  // kubeconfig context to use
    Namespace              string  // target namespace
    Image                  string  // luxgo container image
    VolumeSizeGB           int     // PVC size in GB (minimum 2)
    UseExclusiveScheduling bool    // one pod per k8s node
    SchedulingLabelKey     string  // anti-affinity label key
    SchedulingLabelValue   string  // anti-affinity label value
    IngressHost            string  // e.g., "localhost:30791"
    IngressSecret          string  // TLS secret for HTTPS
}
```

| Field | Description | Example |
|-------|-------------|---------|
| `ConfigContext` | Kubeconfig context | `"kind-tmpnet"` |
| `Namespace` | Kubernetes namespace | `"tmpnet-test"` |
| `Image` | Container image with tag | `"avaplatform/luxgo:v1.11.0"` |
| `VolumeSizeGB` | PVC size per node | `10` |
| `UseExclusiveScheduling` | One pod per k8s node | `true` |
| `IngressHost` | External access hostname | `"localhost:30791"` |

<Callout type="warning">
Exclusive scheduling requires at least as many Kubernetes nodes as tmpnet nodes and doubles the startup timeout.
</Callout>

### Quick Start with KIND

**1. Start KIND Cluster**

```bash
# Use the provided script
./scripts/start_kind_cluster.sh

# Creates:
# - KIND cluster named "tmpnet"
# - Ingress controller with NodePort
# - Port forwarding on localhost:30791
```

**2. Create Network**

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
)

func main() {
    ctx := context.Background()

    // Configure Kubernetes runtime
    network := &tmpnet.Network{
        DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
            Kube: &tmpnet.KubeRuntimeConfig{
                ConfigContext: "kind-tmpnet",
                Namespace:     "tmpnet-demo",
                Image:         "avaplatform/luxgo:latest",
                VolumeSizeGB:  5,
                IngressHost:   "localhost:30791",
            },
        },
        Nodes: tmpnet.NewNodesOrPanic(5),
    }

    if err := tmpnet.BootstrapNewNetwork(ctx, os.Stdout, network, "", ""); err != nil {
        log.Fatal(err)
    }
    defer network.Stop(ctx)

    fmt.Println("Network created successfully!")
}
```

**3. Verify Deployment**

```bash
# Check pods
kubectl get pods -n tmpnet-demo

# Access node API
curl http://localhost:30791/ext/health
```

### Advantages

| Advantage | Description |
|-----------|-------------|
| **Production-Like** | Mirrors real deployment patterns |
| **Scalability** | Support 50+ node networks across cluster |
| **Network Isolation** | Namespace boundaries and NetworkPolicy |
| **CI/CD Ready** | Easy integration with GitHub Actions, Jenkins |
| **Persistent Storage** | Data survives pod restarts |

### Limitations

| Limitation | Details |
|------------|---------|
| **Slower Startup** | 3-5 minutes (image pull + scheduling) |
| **Complex Debugging** | Requires `kubectl logs` and Kubernetes knowledge |
| **Resource Overhead** | Kubernetes control plane adds ~2GB RAM |
| **Expertise Required** | Understanding of Pods, Services, PVCs, Ingress |

**Startup Timeout Calculation:**

```go
timeout := time.Duration(nodeCount) * time.Minute
if config.UseExclusiveScheduling {
    timeout *= 2  // Double for anti-affinity scheduling
}
```

---

## Runtime Comparison

| Feature | Local Runtime | Kubernetes Runtime |
|---------|--------------|-------------------|
| **Startup Time** | ~30 seconds | 1-5 minutes |
| **Max Nodes** | ~20 (resource-limited) | 100+ (cluster-limited) |
| **Debugging** | Direct log files | `kubectl logs` |
| **Persistence** | `~/.tmpnet/networks/` | PersistentVolumeClaims |
| **Port Access** | localhost:dynamic | Ingress or port-forward |
| **Best For** | Development, quick tests | CI/CD, scale testing |
| **Prerequisites** | LuxGo binary | Kubernetes cluster |
| **OS Support** | macOS, Linux | Any with kubectl |

<Callout type="tip">
**Quick Decision Guide:**
- Use **Local** for development and testing with fewer than 20 nodes
- Use **Kubernetes** for CI/CD pipelines, large networks (20+ nodes), or production-like testing
</Callout>

---

## Advanced Topics

### Writing Runtime-Agnostic Tests

The e2e framework provides a `TestEnvironment` abstraction that makes tests portable across runtimes:

```go
import (
    "github.com/luxfi/luxgo/tests/fixture/e2e"
)

var _ = ginkgo.Describe("[Cross-Runtime Tests]", func() {
    ginkgo.It("should work on any runtime", func() {
        // Get the test environment (local or Kubernetes)
        env := e2e.GetEnv(tc)

        // Get network - abstracted across runtimes
        network := env.GetNetwork()

        // Get node URIs - automatically handles port-forward vs direct
        nodeURI := env.GetRandomNodeURI()

        // All operations work identically regardless of runtime
        client := jsonrpc.NewClient(nodeURI)
        health, err := client.Health(context.Background())
        Expect(err).NotTo(HaveOccurred())
    })
})
```

Runtime selection is controlled by:
- CLI flags: `--use-kubernetes=true`
- Environment variables: `E2E_USE_KUBERNETES=true`
- Test configuration defaults

### Bootstrap Monitor for Continuous Testing

The **bootstrap monitor** is a Kubernetes-based tool for continuous bootstrap testing on persistent networks (mainnet, testnet). It validates that new LuxGo versions can successfully sync from genesis.

**Architecture:**

```
StatefulSet: bootstrap-monitor
├── Init Container: bootstrap-monitor init
│   └── Prepares configuration and data directory
├── Containers:
│   ├── luxgo (primary)
│   │   └── Runs node with sync monitoring
│   └── bootstrap-monitor wait-for-completion (sidecar)
│       └── Polls health and emits completion status
└── PersistentVolumeClaim: data
    └── Persistent storage for node database
```

**Three Sync Modes:**

| Mode | Chains Synced | Duration | Use Case |
|------|--------------|----------|----------|
| `full-sync` | P, X, C (full) | Hours-days | Complete validation |
| `c-chain-state-sync` | P, X (full), C (state) | 1-3 hours | Fast comprehensive test |
| `p-chain-full-sync-only` | P (full) | 30-60 min | Platform-Chain validation only |

### Monitoring Integration

Both runtimes integrate with Prometheus and Promtail using file-based service discovery:

```
~/.tmpnet/prometheus/file_sd_configs/
└── [network-uuid]-[node-id].json
```

**Environment Variables:**

```bash
# Prometheus
export PROMETHEUS_URL="https://prometheus.example.com"
export PROMETHEUS_USERNAME="user"
export PROMETHEUS_PASSWORD="pass"

# Loki (logs)
export LOKI_URL="https://loki.example.com"

# Grafana
export GRAFANA_URI="https://grafana.example.com/d/tmpnet"
```

After starting a network, tmpnet emits a Grafana dashboard link:

```bash
tmpnetctl start-network
# Output includes:
# Grafana: https://grafana.example.com/d/tmpnet?var-network_uuid=abc-123
```

---

## Troubleshooting

For detailed troubleshooting of runtime-specific issues, see the [Troubleshooting Runtime Issues](/docs/tooling/tmpnet/troubleshooting-runtime) guide.

### Quick Fixes

**Local Runtime - Port Conflicts:**
```bash
pkill -f luxgo
lsof -i :9650-9660
```

**Kubernetes - Pod Stuck Pending:**
```bash
kubectl describe pod <pod-name> -n tmpnet
kubectl get events -n tmpnet --sort-by='.lastTimestamp'
```

**Both - Health Check Failures:**
```bash
# Check if node is still bootstrapping (requires jq: brew install jq)
curl -s http://localhost:9650/ext/info | jq '.result.isBootstrapped'

# Alternative without jq:
curl -s http://localhost:9650/ext/health
```

---

## Next Steps

<Cards>
  <Card title="Quick Start" href="/docs/tooling/tmpnet/quick-start">
    Create your first network
  </Card>
  <Card title="Configuration Reference" href="/docs/tooling/tmpnet/reference/configuration">
    Complete configuration options
  </Card>
  <Card title="Monitoring Guide" href="/docs/tooling/tmpnet/guides/monitoring">
    Set up metrics and logging
  </Card>
  <Card title="Troubleshooting" href="/docs/tooling/tmpnet/troubleshooting-runtime">
    Diagnose and fix issues
  </Card>
</Cards>


# Testing Platform-Chain Staking and Delegation (/docs/tooling/tmpnet/guides/staking-and-delegation)

---
title: Testing Platform-Chain Staking and Delegation
description: Test Primary Network validator staking, delegation, and reward distribution
---

This guide covers testing Platform-Chain staking and delegation on the Primary Network, including validator registration, delegator management, reward distribution, and uptime tracking.

> This is a pattern guide. For a runnable example, see `tests/e2e/p/staking_rewards.go` in the luxgo repo. Adapt the code there for your suite rather than copying these snippets verbatim.

**Where to put your tests:** keep tmpnet-based staking tests alongside your application code or in an existing test suite (e.g., `tests/e2e` in your repo). Avoid creating a new repo just for these; reuse your project’s test harness and helpers so fixtures, CI, and dependencies stay in one place.

## Overview

Platform-Chain staking differs from L1 validator management:
- **Platform-Chain**: AddValidatorTx / AddDelegatorTx on Primary Network
- **L1s**: Contract-based validator managers (see [L1 Validator Management](/docs/tooling/tmpnet/guides/validator-management-native-staking))

This guide covers Platform-Chain patterns from luxgo tests including:
- Validator registration with stake
- Delegator addition and rewards
- Uptime-based reward distribution
- Cortina fork behavior (deferred delegatee rewards)
- Time-based state transitions

## Prerequisites

- Complete [Getting Started](/docs/tooling/tmpnet/guides/getting-started)
- Understand Ginkgo test structure
- Have a tmpnet network running

## Complete Test Example

```go title="p_chain_staking_test.go"
package staking_test

import (
    "context"
    "flag"
    "os"
    "testing"
    "time"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/e2e"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/units"
    "github.com/luxfi/luxgo/vms/platformvm/txs"
    "github.com/luxfi/luxgo/wallet/subnet/primary"
    "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var (
    network  *tmpnet.Network
    e2eFlags *e2e.FlagVars
)

func TestMain(m *testing.M) {
    e2eFlags = e2e.RegisterFlags()
    flag.Parse()
    os.Exit(m.Run())
}

func TestPChainStaking(t *testing.T) {
    if os.Getenv("RUN_E2E") == "" {
        t.Skip("RUN_E2E not set")
    }

    RegisterFailHandler(ginkgo.Fail)
    ginkgo.RunSpecs(t, "Platform-Chain Staking Test Suite")
}

var _ = ginkgo.BeforeSuite(func() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()

    network = createNetwork(ctx)
})

var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        network.Stop(context.Background())
    }
})

var _ = ginkgo.Describe("[Platform-Chain Staking]", func() {
    ginkgo.It("should add validator and delegate",
        ginkgo.Label("staking", "p-chain"),
        func() {
            ctx := context.Background()

            // Add validator to Primary Network
            nodeID, txID := addPrimaryNetworkValidator(
                ctx,
                network,
                2*units.Lux,  // stake
                24*time.Hour,  // duration
            )

            // Wait for validator to become active
            waitForValidatorActive(ctx, network, nodeID)

            // Add delegator
            delegationID := addDelegator(
                ctx,
                network,
                nodeID,
                1*units.Lux,
                12*time.Hour,
            )

            // Verify delegation
            verifyDelegation(ctx, network, delegationID)
        })
})
```

## Adding Primary Network Validators

### AddValidatorTx Pattern

```go
func addPrimaryNetworkValidator(
    ctx context.Context,
    network *tmpnet.Network,
    stakeAmount uint64,
    stakeDuration time.Duration,
) (ids.NodeID, ids.ID) {

    // Get pre-funded key
    fundedKey := network.PreFundedKeys[0]

    // Create Platform-Chain wallet
    pWallet := createPChainWallet(ctx, network, fundedKey)

    // Create new ephemeral node to validate
    node := tmpnet.NewEphemeralNode(tmpnet.FlagsMap{})
    err := network.StartNode(ctx, node)
    Expect(err).NotTo(HaveOccurred())

    err = node.WaitForHealthy(ctx)
    Expect(err).NotTo(HaveOccurred())

    // Calculate start and end times
    startTime := time.Now().Add(1 * time.Minute)
    endTime := startTime.Add(stakeDuration)

    // Issue AddValidatorTx
    txID, err := pWallet.IssueAddPermissionlessValidatorTx(
        &txs.SubnetValidator{
            Validator: txs.Validator{
                NodeID: node.NodeID,
                Start:  uint64(startTime.Unix()),
                End:    uint64(endTime.Unix()),
                Wght:   stakeAmount,
            },
            Subnet: ids.Empty, // Primary Network
        },
        &secp256k1fx.OutputOwners{
            Threshold: 1,
            Addrs:     []ids.ShortID{fundedKey.Address()},
        },
        &secp256k1fx.OutputOwners{
            Threshold: 1,
            Addrs:     []ids.ShortID{fundedKey.Address()},
        },
        10, // Delegation fee: 10%
    )
    Expect(err).NotTo(HaveOccurred())

    return node.NodeID, txID
}
```

### Waiting for Validator Activation

```go
func waitForValidatorActive(
    ctx context.Context,
    network *tmpnet.Network,
    nodeID ids.NodeID,
) {

    pClient := platform.NewClient(network.Nodes[0].URI)

    Eventually(func() bool {
        validators, err := pClient.GetCurrentValidators(
            ctx,
            ids.Empty, // Primary Network
            []ids.NodeID{nodeID},
        )

        if err != nil || len(validators) == 0 {
            return false
        }

        return validators[0].NodeID == nodeID
    }, 2*time.Minute, 1*time.Second).Should(BeTrue())
}
```

## Delegation

### AddDelegatorTx Pattern

```go
func addDelegator(
    ctx context.Context,
    network *tmpnet.Network,
    validatorNodeID ids.NodeID,
    delegationAmount uint64,
    delegationDuration time.Duration,
) ids.ID {

    delegatorKey := network.PreFundedKeys[1]
    pWallet := createPChainWallet(ctx, network, delegatorKey)

    startTime := time.Now().Add(1 * time.Minute)
    endTime := startTime.Add(delegationDuration)

    txID, err := pWallet.IssueAddPermissionlessDelegatorTx(
        &txs.SubnetValidator{
            Validator: txs.Validator{
                NodeID: validatorNodeID,
                Start:  uint64(startTime.Unix()),
                End:    uint64(endTime.Unix()),
                Wght:   delegationAmount,
            },
            Subnet: ids.Empty,
        },
        &secp256k1fx.OutputOwners{
            Threshold: 1,
            Addrs:     []ids.ShortID{delegatorKey.Address()},
        },
    )
    Expect(err).NotTo(HaveOccurred())

    return txID
}
```

## Reward Distribution

### Testing Validator Rewards

Based on luxgo `reward_validator_test.go`:

```go
ginkgo.It("should distribute validator rewards on completion",
    ginkgo.Label("rewards"),
    func() {
        ctx := context.Background()

        initialBalance := getBalance(ctx, network, validatorKey)

        // Add validator with min stake
        stakeAmount := 2000 * units.Lux
        nodeID, _ := addPrimaryNetworkValidator(
            ctx,
            network,
            stakeAmount,
            15*24*time.Hour, // 15 days
        )

        // Wait for validator period to end
        waitForValidatorRemoval(ctx, network, nodeID)

        // Check rewards received
        finalBalance := getBalance(ctx, network, validatorKey)

        // Expected: original stake + rewards
        // Reward calculation based on duration and stake
        expectedReward := calculateExpectedReward(stakeAmount, 15*24*time.Hour)

        Expect(finalBalance).To(BeNumerically(">=", initialBalance+stakeAmount+expectedReward))
    })
```

### Delegation Rewards with Cortina Fork

**Pre-Cortina**: Delegatee receives 25% immediately
**Post-Cortina**: Delegatee rewards deferred until validator exits

```go
ginkgo.It("should handle delegator rewards post-Cortina",
    ginkgo.Label("rewards", "delegation"),
    func() {
        ctx := context.Background()

        // Add validator
        nodeID, _ := addPrimaryNetworkValidator(ctx, network, 2*units.Lux, 24*time.Hour)

        // Add delegator
        delegatorInitial := getBalance(ctx, network, delegatorKey)

        delegationID := addDelegator(ctx, network, nodeID, 1*units.Lux, 12*time.Hour)

        // Wait for delegation period to end
        waitForDelegationEnd(ctx, network, delegationID)

        // Delegator receives 75% of rewards immediately (post-Cortina)
        delegatorFinal := getBalance(ctx, network, delegatorKey)
        delegatorReward := delegatorFinal - delegatorInitial - (1 * units.Lux)

        Expect(delegatorReward).To(BeNumerically(">", 0))

        // Validator (delegatee) receives 25% when their validation period ends
        // This is deferred until validator exits (post-Cortina behavior)
    })
```

## Uptime-Based Rewards

### E2E Uptime Test Pattern

From luxgo `staking_rewards.go`:

```go
ginkgo.It("should only reward validators with sufficient uptime",
    ginkgo.Label("uptime", "e2e"),
    func() {
        ctx := context.Background()

        // Add two validators
        alphaID, _ := addPrimaryNetworkValidator(ctx, network, 2*units.Lux, 48*time.Hour)
        betaID, _ := addPrimaryNetworkValidator(ctx, network, 2*units.Lux, 48*time.Hour)

        // Keep alpha online, stop beta
        betaNode := network.GetNode(betaID)
        err := betaNode.Stop(ctx)
        Expect(err).NotTo(HaveOccurred())

        // Wait for validation periods
        time.Sleep(48 * time.Hour) // In real tests, advance time

        // Alpha gets rewards (good uptime)
        alphaBalance := getBalance(ctx, network, alphaKey)
        Expect(alphaBalance).To(BeNumerically(">", 2*units.Lux))

        // Beta gets no rewards (insufficient uptime)
        betaBalance := getBalance(ctx, network, betaKey)
        Expect(betaBalance).To(Equal(2 * units.Lux)) // Only stake returned
    })
```

## Testing Edge Cases

### Insufficient Stake

```go
ginkgo.It("should reject validator with insufficient stake",
    ginkgo.Label("validation"),
    func() {
        ctx := context.Background()

        pWallet := createPChainWallet(ctx, network, fundedKey)

        // Try to add validator with less than minimum stake
        _, err := pWallet.IssueAddPermissionlessValidatorTx(
            &txs.SubnetValidator{
                Validator: txs.Validator{
                    NodeID: nodeID,
                    Start:  uint64(time.Now().Add(1 * time.Minute).Unix()),
                    End:    uint64(time.Now().Add(25 * time.Hour).Unix()),
                    Wght:   100, // Way below minimum
                },
                Subnet: ids.Empty,
            },
            /*...*/
        )

        Expect(err).To(HaveOccurred())
        Expect(err.Error()).To(ContainSubstring("insufficient stake"))
    })
```

### Over-Delegation

From `vm_regression_test.go`:

```go
ginkgo.It("should handle maximum delegation correctly",
    ginkgo.Label("validation", "delegation"),
    func() {
        ctx := context.Background()

        validatorStake := 2 * units.Lux
        nodeID, _ := addPrimaryNetworkValidator(ctx, network, validatorStake, 48*time.Hour)

        // First delegator: 5x validator stake (maximum)
        delegationID1 := addDelegator(ctx, network, nodeID, 5*validatorStake, 24*time.Hour)
        Expect(delegationID1).NotTo(BeEmpty())

        // Second delegator: Should fail (would exceed 5x limit)
        _, err := addDelegatorTx(ctx, network, nodeID, 1*units.Lux, 24*time.Hour)
        Expect(err).To(HaveOccurred())
    })
```

## Helper Functions

### Create Platform-Chain Wallet

```go
func createPChainWallet(
    ctx context.Context,
    network *tmpnet.Network,
    key *secp256k1.PrivateKey,
) primary.Wallet {

    nodeURI := network.Nodes[0].URI

    wallet, err := primary.MakeWallet(
        ctx,
        &primary.WalletConfig{
            URI:          nodeURI,
            LUXKeychain: secp256k1fx.NewKeychain(key),
            EthKeychain:  secp256k1fx.NewKeychain(),
        },
    )
    Expect(err).NotTo(HaveOccurred())

    return wallet
}
```

### Get Platform-Chain Balance

```go
func getBalance(
    ctx context.Context,
    network *tmpnet.Network,
    key *secp256k1.PrivateKey,
) uint64 {

    pClient := platform.NewClient(network.Nodes[0].URI)

    utxos, err := pClient.GetUTXOs(
        ctx,
        []ids.ShortID{key.Address()},
        ids.Empty,
        0,
        100,
    )
    Expect(err).NotTo(HaveOccurred())

    var balance uint64
    for _, utxo := range utxos {
        balance += utxo.Out.Amount()
    }

    return balance
}
```

## Best Practices

1. **Use generous timeouts**: Platform-Chain operations can be slow
2. **Test uptime requirements**: Validators need sufficient uptime for rewards
3. **Handle fork behavior**: Cortina fork changed delegation reward distribution
4. **Test edge cases**: Minimum stake, maximum delegation, invalid times
5. **Verify balances**: Check stake return and reward distribution
6. **Clean up validators**: Stop test nodes after validation periods

## Key Differences: Platform-Chain vs L1 Validators

| Aspect | Platform-Chain | L1 Validators |
|--------|---------|---------------|
| Transaction Type | AddValidatorTx | Contract calls |
| Staking | LUX on Platform-Chain | Native/ERC20 tokens on L1 |
| Rewards | Protocol-level | Contract-managed |
| Uptime | Tracked by Platform-Chain | Can use uptime proofs |
| Registration | Direct Platform-Chain tx | Three-phase with Warp |

## Next Steps

<Cards>
  <Card title="L1 Validator Management" href="/docs/tooling/tmpnet/guides/validator-management-native-staking">
    Test L1 contract-based validators
  </Card>
  <Card title="Getting Started" href="/docs/tooling/tmpnet/guides/getting-started">
    Back to testing fundamentals
  </Card>
</Cards>

## Additional Resources

- [luxgo Platform-Chain Tests](https://github.com/luxfi/luxgo/tree/master/vms/platformvm)
- [Reward Calculator Tests](https://github.com/luxfi/luxgo/blob/master/vms/platformvm/reward/calculator_test.go)
- [Staking Rewards E2E](https://github.com/luxfi/luxgo/blob/master/tests/e2e/p/staking_rewards.go)


# Subnet Testing (/docs/tooling/tmpnet/guides/subnet-testing)

---
title: Subnet Testing
description: Test subnet creation, validators, and cross-subnet interactions with tmpnet
---

This guide covers advanced subnet testing scenarios using tmpnet, including subnet creation, validator management, and testing cross-subnet functionality.

## Overview

tmpnet supports comprehensive subnet testing:

- Create subnets with specific validators
- Test validator operations (add/remove)
- Configure subnet parameters
- Test cross-subnet messaging with Warp
- Validate L1 conversions

## Creating a Subnet with Specific Validators

### Basic Example

Create a subnet validated by specific nodes:

```go
import (
    "context"
    "os"
    "time"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/utils/constants"
    "github.com/luxfi/luxgo/utils/logging"
)

// Create 5-node network
network := &tmpnet.Network{
    Nodes: tmpnet.NewNodesOrPanic(5),
    DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
        Process: &tmpnet.ProcessRuntimeConfig{
            LuxGoPath: os.Getenv("LUXGO_PATH"),
            PluginDir:       os.Getenv("AVAGO_PLUGIN_DIR"),
        },
    },
}

// Subnet validated by first 3 nodes only
subnet := &tmpnet.Subnet{
    Name: "my-subnet",
    ValidatorIDs: []ids.NodeID{
        network.Nodes[0].NodeID,
        network.Nodes[1].NodeID,
        network.Nodes[2].NodeID,
    },
    Chains: []*tmpnet.Chain{{
        VMID:    constants.XSVMID,
        Genesis: genesisBytes,
    }},
}

network.Subnets = []*tmpnet.Subnet{subnet}

// Bootstrap
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

err := tmpnet.BootstrapNewNetwork(ctx, logging.NoLog{}, network, "")
if err != nil {
    panic(err)
}

println("Subnet ID:", subnet.SubnetID.String())
```

### Subnet Configuration

Customize subnet parameters:

```go
subnet.Config = tmpnet.ConfigMap{
    "proposerMinBlockDelay": 0,        // Minimum block delay
    "proposerNumHistoricalBlocks": 50000,  // Historical blocks
}
```

## Testing Multiple Subnets

Create overlapping and isolated subnets:

```go
nodes := tmpnet.NewNodesOrPanic(7)

// Subnet A: nodes 0-2
subnetA := &tmpnet.Subnet{
    Name:         "subnet-a",
    ValidatorIDs: []ids.NodeID{nodes[0].NodeID, nodes[1].NodeID, nodes[2].NodeID},
    Chains:       []*tmpnet.Chain{chainA},
}

// Subnet B: nodes 2-4 (node 2 validates both A and B)
subnetB := &tmpnet.Subnet{
    Name:         "subnet-b",
    ValidatorIDs: []ids.NodeID{nodes[2].NodeID, nodes[3].NodeID, nodes[4].NodeID},
    Chains:       []*tmpnet.Chain{chainB},
}

// Subnet C: nodes 5-6 (isolated)
subnetC := &tmpnet.Subnet{
    Name:         "subnet-c",
    ValidatorIDs: []ids.NodeID{nodes[5].NodeID, nodes[6].NodeID},
    Chains:       []*tmpnet.Chain{chainC},
}

network := &tmpnet.Network{
    Nodes:   nodes,
    Subnets: []*tmpnet.Subnet{subnetA, subnetB, subnetC},
}
```

This lets you test:
- Shared validators (node 2 validates both A and B)
- Isolated subnets (subnet C)
- Cross-subnet messaging via shared validators

## Adding Validators to a Running Subnet

Test adding validators dynamically to an existing subnet:

```go
func addValidatorToSubnet(network *tmpnet.Network, subnet *tmpnet.Subnet) error {
    // Create a new ephemeral node
    newNode := tmpnet.NewEphemeralNode(tmpnet.FlagsMap{
        config.TrackSubnetsKey: subnet.SubnetID.String(),
    })

    // Start the node
    err := network.StartNode(context.Background(), newNode)
    if err != nil {
        return err
    }

    // Add as subnet validator using the subnet wallet
    // (Implementation details depend on your wallet setup)
    err = addSubnetValidator(subnet, newNode.NodeID)
    if err != nil {
        return err
    }

    // Wait for validator to become active
    return subnet.WaitForActiveValidators(context.Background(), newNode.NodeID)
}
```

## Testing Subnet-to-L1 Conversion

Test converting a subnet to an L1 blockchain:

```go
func testL1Conversion(t *testing.T) {
    // Create initial subnet
    network := createNetworkWithSubnet()
    defer network.Stop(context.Background())

    subnet := network.Subnets[0]

    // Perform L1 conversion operations
    // 1. Register L1 validators
    for _, node := range network.Nodes {
        err := registerL1Validator(subnet, node)
        require.NoError(t, err)
    }

    // 2. Convert subnet to L1
    err := convertSubnetToL1(subnet)
    require.NoError(t, err)

    // 3. Wait for validators to activate
    err = waitForL1Validators(subnet)
    require.NoError(t, err)

    // 4. Verify L1 functionality
    verifyL1Behavior(t, subnet)
}
```

## Cross-Subnet Messaging

Test Lux Warp Messaging between subnets:

```go
func testWarpMessaging(t *testing.T) {
    // Create network with two subnets
    network := createMultiSubnetNetwork()
    defer network.Stop(context.Background())

    sourceSubnet := network.Subnets[0]
    destSubnet := network.Subnets[1]

    // Send a Warp message from source to destination
    message := createWarpMessage(sourceSubnet)

    // Get signatures from source subnet validators
    signatures := collectWarpSignatures(sourceSubnet, message)

    // Submit message to destination subnet
    err := submitWarpMessage(destSubnet, message, signatures)
    require.NoError(t, err)

    // Verify message was received and processed
    verifyWarpMessage(t, destSubnet, message)
}
```

## Subnet Validator Lifecycle Testing

Test the complete validator lifecycle on a subnet:

```go
func TestSubnetValidatorLifecycle(t *testing.T) {
    network := setupNetwork(t)
    defer network.Stop(context.Background())

    subnet := network.Subnets[0]

    // Create a new node to add as validator
    node := tmpnet.NewEphemeralNode(tmpnet.FlagsMap{
        config.TrackSubnetsKey: subnet.SubnetID.String(),
    })

    // Start the node
    err := network.StartNode(context.Background(), node)
    require.NoError(t, err)

    // Add as pending validator
    t.Run("AddValidator", func(t *testing.T) {
        err := addSubnetValidator(subnet, node.NodeID, startTime, endTime, weight)
        require.NoError(t, err)
    })

    // Wait for validation period to start
    t.Run("WaitForActive", func(t *testing.T) {
        err := subnet.WaitForActiveValidators(context.Background(), node.NodeID)
        require.NoError(t, err)
    })

    // Verify validator is active
    t.Run("VerifyActive", func(t *testing.T) {
        active := isValidatorActive(subnet, node.NodeID)
        require.True(t, active)
    })

    // Remove validator
    t.Run("RemoveValidator", func(t *testing.T) {
        err := removeSubnetValidator(subnet, node.NodeID)
        require.NoError(t, err)
    })

    // Verify validator is removed
    t.Run("VerifyRemoved", func(t *testing.T) {
        active := isValidatorActive(subnet, node.NodeID)
        require.False(t, active)
    })
}
```

## Testing Subnet Configuration Changes

Test how subnet configuration changes affect behavior:

```go
func testSubnetConfigUpdate(t *testing.T) {
    // Initial configuration
    subnet := &tmpnet.Subnet{
        Name: "configurable-subnet",
        Config: tmpnet.ConfigMap{
            "proposerMinBlockDelay": 1000, // 1 second
        },
        Chains:       []*tmpnet.Chain{chain},
        ValidatorIDs: validatorIDs,
    }

    network := &tmpnet.Network{
        Nodes:   nodes,
        Subnets: []*tmpnet.Subnet{subnet},
        DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
            Process: &tmpnet.ProcessRuntimeConfig{
                LuxGoPath: luxgoPath,
                PluginDir:       pluginDir,
            },
        },
    }

    // Bootstrap network
    require.NoError(t, tmpnet.BootstrapNewNetwork(ctx, os.Stdout, network, ""))

    // Test behavior with initial config
    measureBlockTime(t, subnet, 1000)

    // Update configuration
    subnet.Config["proposerMinBlockDelay"] = 0

    // Restart nodes to apply new configuration
    network.Restart(context.Background())

    // Test behavior with updated config
    measureBlockTime(t, subnet, 0)
}
```

## Tracking Specific Subnets

Configure nodes to track specific subnets for testing:

```go
// Configure network to track subnet
network.DefaultFlags = tmpnet.FlagsMap{
    config.TrackSubnetsKey: subnetID.String(),
}

// Or configure individual nodes
node.Flags = tmpnet.FlagsMap{
    config.TrackSubnetsKey: fmt.Sprintf("%s,%s", subnet1.String(), subnet2.String()),
}
```

## Testing Subnet Validator Weights

Test different validator weight distributions:

```go
func testValidatorWeights(t *testing.T) {
    network := setupNetwork(t)

    // Add validators with different weights
    validators := []struct {
        nodeID ids.NodeID
        weight uint64
    }{
        {network.Nodes[0].NodeID, 100}, // 50% of total weight
        {network.Nodes[1].NodeID, 50},  // 25% of total weight
        {network.Nodes[2].NodeID, 30},  // 15% of total weight
        {network.Nodes[3].NodeID, 20},  // 10% of total weight
    }

    for _, v := range validators {
        err := addSubnetValidator(subnet, v.nodeID, startTime, endTime, v.weight)
        require.NoError(t, err)
    }

    // Test consensus with weighted validators
    testConsensusWithWeights(t, subnet, validators)
}
```

## Ephemeral Subnet Validators

Add temporary validators for specific test scenarios:

```go
func addEphemeralValidator(network *tmpnet.Network, subnet *tmpnet.Subnet) (*tmpnet.Node, error) {
    // Create ephemeral node that tracks the subnet
    ephemeralNode := tmpnet.NewEphemeralNode(tmpnet.FlagsMap{
        config.TrackSubnetsKey:          subnet.SubnetID.String(),
        config.SybilProtectionEnabledKey: "false", // For testing only
    })

    // Add to network
    err := network.AddEphemeralNode(context.Background(), ephemeralNode)
    if err != nil {
        return nil, err
    }

    // Add as subnet validator with short duration
    shortDuration := 5 * time.Minute
    err = addSubnetValidator(
        subnet,
        ephemeralNode.NodeID,
        time.Now(),
        time.Now().Add(shortDuration),
        20, // weight
    )

    return ephemeralNode, err
}
```

## Common Testing Patterns

### Testing Subnet Bootstrap

Verify that nodes can bootstrap from a subnet:

```go
func testSubnetBootstrap(t *testing.T) {
    // Create and bootstrap network with subnet
    network := createNetworkWithSubnet()
    defer network.Stop(context.Background())

    // Create a new node
    newNode := tmpnet.NewNode()
    newNode.Flags = tmpnet.FlagsMap{
        config.TrackSubnetsKey: subnet.SubnetID.String(),
    }

    // Start the node
    err := network.StartNode(context.Background(), newNode)
    require.NoError(t, err)

    // Verify the node bootstrapped the subnet
    verifySubnetBootstrap(t, newNode, subnet)
}
```

### Testing Subnet Chain Upgrades

Test deploying chain upgrades on a subnet:

```go
func testChainUpgrade(t *testing.T) {
    network := setupNetworkWithSubnet(t)

    // Deploy initial chain version
    // ... operate chain ...

    // Stop network
    network.Stop(context.Background())

    // Update chain configuration or VM binary
    updateChainConfig(network.Subnets[0])

    // Restart network
    err := network.Restart(context.Background())
    require.NoError(t, err)

    // Verify upgrade succeeded
    verifyChainUpgrade(t, network.Subnets[0])
}
```

## Troubleshooting

### Subnet Creation Fails

**Check:**
- Sufficient nodes are specified as validators (minimum 1)
- Nodes have generated staking keys
- Bootstrap node has sufficient funds for transactions

**Debug:**
```bash
# Check subnet creation logs
grep -i "subnet" ~/.tmpnet/networks/latest/NodeID-*/logs/main.log
```

### Validators Not Becoming Active

**Check:**
- Validation period has started
- Nodes are tracking the subnet
- Subnet validators were added correctly

**Debug:**
```bash
# Check if node is tracking subnet
cat ~/.tmpnet/networks/latest/NodeID-*/flags.json | jq '.["track-subnets"]'
```

### Cross-Subnet Messaging Issues

**Check:**
- Both subnets have active validators
- Nodes validating both subnets have proper connectivity
- Warp messaging is enabled

## Next Steps

<Cards>
  <Card title="Runtime Environments" href="/docs/tooling/tmpnet/guides/runtimes">
    Choose between local and Kubernetes runtimes
  </Card>
  <Card title="Monitoring" href="/docs/tooling/tmpnet/guides/monitoring">
    Monitor subnet behavior with metrics
  </Card>
  <Card title="Configuration Reference" href="/docs/tooling/tmpnet/reference/configuration">
    Detailed configuration options
  </Card>
</Cards>

## Additional Resources

- [Subnet Examples in E2E Tests](https://github.com/luxfi/luxgo/tree/master/tests/e2e)
- [Subnet Documentation](/docs/subnets)
- [Warp Messaging](/docs/cross-chain)


# Testing Custom VMs (/docs/tooling/tmpnet/guides/testing-custom-vms)

---
title: Testing Custom VMs
description: Deploy and test your custom Virtual Machine on a local temporary network
---

This guide shows you how to use tmpnet to test your custom Virtual Machine (VM) or L1 blockchain before deploying to testnet or mainnet.

## Overview

Testing custom VMs with tmpnet allows you to deploy your VM to a multi-node network, test consensus behavior, and iterate quickly before public deployment.

## Prerequisites

1. **tmpnet installed** - See [Installation](/docs/tooling/tmpnet/installation)
2. **VM binary compiled** - Your VM binary in `~/.luxgo/plugins/`
3. **Genesis file** - Genesis configuration for your chain

## Quick Example: Testing a Custom VM

Here's a complete workflow for testing a custom VM:

### 1. Prepare Your VM Binary

Build your VM and place it in the plugins directory:

```bash
# Build your VM (example)
cd /path/to/your-vm
go build -o ~/.luxgo/plugins/your-vm ./cmd/your-vm

# Verify the binary exists
ls -lh ~/.luxgo/plugins/your-vm
```

The binary name should match your VM name.

### 2. Create Genesis Configuration

Create a genesis file for your chain. The exact format depends on your VM. Example for a simple VM:

```json
{
  "config": {
    "chainId": 12345,
    "feeConfig": {
      "gasLimit": 8000000
    }
  },
  "alloc": {
    "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000"
    }
  }
}
```

Save this as `genesis.json`.

### 3. Test Your VM Using Go Code

Create a test script to deploy your VM:

```go
package main

import (
    "context"
    "os"
    "time"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/utils/logging"
)

func main() {
    // Read genesis
    genesisBytes, _ := os.ReadFile("genesis.json")

    // Define your VM chain
    chain := &tmpnet.Chain{
        VMID:    ids.ID{'y', 'o', 'u', 'r', 'v', 'm', 'i', 'd'},
        Genesis: genesisBytes,
        Config:  `{"blockGasLimit": 8000000}`,
    }

    // Create subnet with your chain
    subnet := &tmpnet.Subnet{
        Name:   "my-vm-subnet",
        Chains: []*tmpnet.Chain{chain},
    }

    // Create 5-node network
    network := &tmpnet.Network{
        Nodes:   tmpnet.NewNodesOrPanic(5),
        Subnets: []*tmpnet.Subnet{subnet},
        DefaultRuntimeConfig: tmpnet.NodeRuntimeConfig{
            Process: &tmpnet.ProcessRuntimeConfig{
                LuxGoPath: "./bin/luxgo",
                PluginDir:       "./build/plugins",
            },
        },
    }

    // All nodes validate the subnet
    for _, node := range network.Nodes {
        subnet.ValidatorIDs = append(subnet.ValidatorIDs, node.NodeID)
    }

    // Bootstrap network
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()

    err := tmpnet.BootstrapNewNetwork(
        ctx,
        logging.NoLog{}, // Or use a real logger
        network,
        "",              // Empty string uses default path (~/.tmpnet/networks)
    )
    if err != nil {
        panic(err)
    }

    println("Chain ID:", subnet.Chains[0].ChainID.String())

    // Test your chain...

    network.Stop(context.Background())
}
```

**Key steps:**
1. Read your genesis configuration
2. Define a `Chain` with your VM ID and genesis
3. Create a `Subnet` containing your chain
4. Set up `DefaultRuntimeConfig` with paths to luxgo and plugins
5. Assign validator nodes to the subnet
6. Bootstrap and test

### 4. Interact with Your Chain

Once your chain is deployed, interact with it using the chain's API:

```bash
# Get the chain ID from the network configuration
CHAIN_ID=$(cat ~/.tmpnet/networks/latest/subnets/your-vm-subnet.json | jq -r '.chains[0].chainId')

# Get a node URI
NODE_URI=$(cat ~/.tmpnet/networks/latest/NodeID-*/process.json | jq -r '.uri' | head -1)

# Call your chain's API
curl -X POST --data '{
  "jsonrpc": "2.0",
  "method": "your.method",
  "params": {},
  "id": 1
}' -H 'content-type:application/json;' ${NODE_URI}/ext/bc/${CHAIN_ID}/rpc
```

## Development Workflow

### Iterative Testing

**1. Make code changes**
**2. Rebuild your VM:**
```bash
go build -o ~/.luxgo/plugins/your-vm ./cmd/your-vm
```

**3. Restart the network:**
```bash
tmpnetctl stop-network
go run test-vm.go
```

### Automated Testing

Integrate tmpnet into your test suite:

```go
func TestYourVM(t *testing.T) {
    network := setupNetwork(t)
    defer network.Stop(context.Background())

    chain := deployChain(t, network)

    t.Run("BasicTransaction", func(t *testing.T) {
        // Test transaction functionality
    })

    t.Run("Consensus", func(t *testing.T) {
        // Test consensus behavior
    })
}
```

### Monitor Logs

```bash
# Watch logs from all nodes
tail -f ~/.tmpnet/networks/latest/NodeID-*/logs/main.log

# Search for errors
grep -i error ~/.tmpnet/networks/latest/NodeID-*/logs/main.log
```

## Common Patterns

### Testing VM Upgrades

```go
// Start with v1
network := createNetworkWithVM("your-vm", "v1.0.0")
// ... test v1 behavior ...
network.Stop(ctx)

// Replace plugin binary with v2
// cp your-vm-v2 ~/.luxgo/plugins/your-vm

network.Restart(ctx)
// ... verify v2 upgrade ...
```

### Custom Genesis Allocations

Pre-fund specific addresses:

```go
genesis := map[string]interface{}{
    "alloc": map[string]interface{}{
        "0xYourAddress": map[string]interface{}{
            "balance": "0x1000000000000000000000",
        },
    },
}
genesisBytes, _ := json.Marshal(genesis)
chain.Genesis = genesisBytes
```

### Testing with Debug Logging

Enable verbose logging for debugging:

```go
network.DefaultFlags = tmpnet.FlagsMap{
    "log-level": "debug",
    "log-display-level": "debug",
}
```

## Troubleshooting

### VM Binary Not Found

**Error:** `plugin binary not found`

**Solution:** Ensure your VM binary is in the correct location:
```bash
ls -lh ~/.luxgo/plugins/your-vm
```

The plugin directory can be customized with `--plugin-dir` flag.

### Genesis Validation Fails

**Error:** `invalid genesis`

**Solution:** Verify your genesis format matches your VM's expectations. Check logs:
```bash
grep -i genesis ~/.tmpnet/networks/latest/NodeID-*/logs/main.log
```

### Chain Not Starting

**Error:** Chain doesn't appear in network

**Solution:**
1. Verify VM binary is executable: `chmod +x ~/.luxgo/plugins/your-vm`
2. Check node logs for VM loading errors
3. Ensure VM ID is correct and unique

### Subnet Validators Not Active

**Error:** Validators don't become active

**Solution:**
- Ensure sufficient validators are assigned to the subnet
- Check that nodes are tracking the subnet
- Verify subnet creation succeeded in logs

## Next Steps

<Cards>
  <Card title="Subnet Testing" href="/docs/tooling/tmpnet/guides/subnet-testing">
    Advanced subnet testing scenarios
  </Card>
  <Card title="Runtime Environments" href="/docs/tooling/tmpnet/guides/runtimes">
    Choose between local and Kubernetes runtimes
  </Card>
  <Card title="Monitoring" href="/docs/tooling/tmpnet/guides/monitoring">
    Set up monitoring for your test network
  </Card>
</Cards>

## Additional Resources

- [Full tmpnet README](https://github.com/luxfi/luxgo/blob/master/tests/fixture/tmpnet/README.md)
- [VM Testing Examples](https://github.com/luxfi/luxgo/tree/master/tests/e2e/vms)
- [Custom VM Documentation](/docs/virtual-machines)


# Transaction Utilities (/docs/tooling/tmpnet/guides/transaction-utilities)

---
title: Transaction Utilities
description: Helper functions for transactions, events, and common testing operations
---

This guide covers utility patterns for working with transactions, events, and common operations in tmpnet tests.

> Pattern guide only. The snippets mirror helpers used in icm-services (for example `tests/contracts/lib/icm-contracts/lib/subnet-evm/tests/utils`) and luxgo e2e utilities. Copy from those source files for runnable code; adjust imports/types to your project.

## Transaction Management

### Calculating Transaction Parameters

Every transaction needs gas parameters and nonce. Use this helper:

```go title="transaction_utils.go"
package testutils

import (
    "context"
    "math/big"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/ethclient"
    . "github.com/onsi/gomega"
)

// CalculateTxParams calculates gas parameters and nonce for a transaction
func CalculateTxParams(
    ctx context.Context,
    l1 L1TestInfo,
    fromAddress common.Address,
) (*big.Int, *big.Int, uint64) {

    // Get base fee from latest block
    baseFee, err := l1.RPCClient.EstimateBaseFee(ctx)
    Expect(err).NotTo(HaveOccurred())

    // Get suggested tip
    gasTipCap, err := l1.RPCClient.SuggestGasTipCap(ctx)
    Expect(err).NotTo(HaveOccurred())

    // Get current nonce
    nonce, err := l1.RPCClient.NonceAt(ctx, fromAddress, nil)
    Expect(err).NotTo(HaveOccurred())

    // Calculate gas fee cap: baseFee * 2.5 + maxPriorityFee
    gasFeeCap := new(big.Int).Mul(baseFee, big.NewInt(25))
    gasFeeCap.Div(gasFeeCap, big.NewInt(10))

    maxPriorityFee := big.NewInt(2_500_000_000) // 2.5 gwei
    gasFeeCap.Add(gasFeeCap, maxPriorityFee)

    // Cap the tip at maxPriorityFee
    if gasTipCap.Cmp(maxPriorityFee) > 0 {
        gasTipCap = maxPriorityFee
    }

    return gasFeeCap, gasTipCap, nonce
}
```

### Creating Transactions

#### Native Transfer

```go
const NativeTransferGas = uint64(21000)

func CreateNativeTransferTransaction(
    ctx context.Context,
    l1 L1TestInfo,
    fromKey *ecdsa.PrivateKey,
    to common.Address,
    amount *big.Int,
) *types.Transaction {

    fromAddress := crypto.PubkeyToAddress(fromKey.PublicKey)
    gasFeeCap, gasTipCap, nonce := CalculateTxParams(ctx, l1, fromAddress)

    tx := types.NewTx(&types.DynamicFeeTx{
        ChainID:   l1.EVMChainID,
        Nonce:     nonce,
        To:        &to,
        Gas:       NativeTransferGas,
        GasFeeCap: gasFeeCap,
        GasTipCap: gasTipCap,
        Value:     amount,
    })

    return SignTransaction(tx, fromKey, l1.EVMChainID)
}

func SendNativeTransfer(
    ctx context.Context,
    l1 L1TestInfo,
    fromKey *ecdsa.PrivateKey,
    to common.Address,
    amount *big.Int,
) *types.Receipt {

    tx := CreateNativeTransferTransaction(ctx, l1, fromKey, to, amount)
    return SendTransactionAndWaitForSuccess(ctx, l1, tx)
}
```

#### Contract Call Transaction

```go
func CreateContractCallTransaction(
    ctx context.Context,
    l1 L1TestInfo,
    fromKey *ecdsa.PrivateKey,
    contract common.Address,
    callData []byte,
    gasLimit uint64,
) *types.Transaction {

    fromAddress := crypto.PubkeyToAddress(fromKey.PublicKey)
    gasFeeCap, gasTipCap, nonce := CalculateTxParams(ctx, l1, fromAddress)

    tx := types.NewTx(&types.DynamicFeeTx{
        ChainID:   l1.EVMChainID,
        Nonce:     nonce,
        To:        &contract,
        Gas:       gasLimit,
        GasFeeCap: gasFeeCap,
        GasTipCap: gasTipCap,
        Data:      callData,
    })

    return SignTransaction(tx, fromKey, l1.EVMChainID)
}
```

### Signing Transactions

```go
func SignTransaction(
    tx *types.Transaction,
    key *ecdsa.PrivateKey,
    chainID *big.Int,
) *types.Transaction {

    signer := types.NewLondonSigner(chainID)
    signedTx, err := types.SignTx(tx, signer, key)
    Expect(err).NotTo(HaveOccurred())

    return signedTx
}
```

### Sending and Waiting

```go
func SendTransactionAndWaitForSuccess(
    ctx context.Context,
    l1 L1TestInfo,
    tx *types.Transaction,
) *types.Receipt {

    err := l1.RPCClient.SendTransaction(ctx, tx)
    Expect(err).NotTo(HaveOccurred())

    return WaitForTransactionSuccess(ctx, l1, tx.Hash())
}

func SendTransactionAndWaitForFailure(
    ctx context.Context,
    l1 L1TestInfo,
    tx *types.Transaction,
) *types.Receipt {

    err := l1.RPCClient.SendTransaction(ctx, tx)
    Expect(err).NotTo(HaveOccurred())

    return WaitForTransactionFailure(ctx, l1, tx.Hash())
}
```

### Waiting for Receipts

```go
func WaitForTransactionSuccess(
    ctx context.Context,
    l1 L1TestInfo,
    txHash common.Hash,
) *types.Receipt {

    var receipt *types.Receipt

    Eventually(func() bool {
        var err error
        receipt, err = l1.RPCClient.TransactionReceipt(ctx, txHash)
        return err == nil
    }, 30*time.Second, 500*time.Millisecond).Should(BeTrue(),
        "Transaction receipt not found: %s", txHash.Hex())

    Expect(receipt.Status).To(Equal(uint64(1)),
        "Transaction failed: %s", txHash.Hex())

    return receipt
}

func WaitForTransactionFailure(
    ctx context.Context,
    l1 L1TestInfo,
    txHash common.Hash,
) *types.Receipt {

    var receipt *types.Receipt

    Eventually(func() bool {
        var err error
        receipt, err = l1.RPCClient.TransactionReceipt(ctx, txHash)
        return err == nil
    }, 30*time.Second, 500*time.Millisecond).Should(BeTrue())

    Expect(receipt.Status).To(Equal(uint64(0)),
        "Transaction succeeded unexpectedly: %s", txHash.Hex())

    return receipt
}
```

## Predicate Transactions (Warp)

Predicate transactions include Warp messages in the access list:

```go
func CreatePredicateTx(
    ctx context.Context,
    l1 L1TestInfo,
    contractAddress common.Address,
    signedWarpMessage *luxWarp.Message,
    senderKey *ecdsa.PrivateKey,
    gasLimit uint64,
    callData []byte,
) *types.Transaction {

    fromAddress := crypto.PubkeyToAddress(senderKey.PublicKey)
    gasFeeCap, gasTipCap, nonce := CalculateTxParams(ctx, l1, fromAddress)

    // Create predicate access list with Warp message
    tx := predicateutils.NewPredicateTx(
        l1.EVMChainID,
        nonce,
        &contractAddress,
        gasLimit,
        gasFeeCap,
        gasTipCap,
        big.NewInt(0),
        callData,
        types.AccessList{},
        warp.ContractAddress,
        signedWarpMessage.Bytes(),
    )

    return SignTransaction(tx, senderKey, l1.EVMChainID)
}
```

## Event Parsing

### Extract Events from Logs

```go
func GetEventFromLogs[T any](
    logs []*types.Log,
    parser func(*types.Log) (T, error),
) (T, error) {

    for _, log := range logs {
        event, err := parser(log)
        if err == nil {
            return event, nil
        }
    }

    var zero T
    return zero, errors.New("event not found in logs")
}

// Usage example
event, err := GetEventFromLogs(
    receipt.Logs,
    teleporter.ParseSendCrossChainMessage,
)
Expect(err).NotTo(HaveOccurred())
messageID := event.MessageID
```

### With Transaction Trace Fallback

For better debugging when events aren't found:

```go
func GetEventFromLogsOrTrace[T any](
    ctx context.Context,
    l1 L1TestInfo,
    receipt *types.Receipt,
    parser func(*types.Log) (T, error),
) T {

    event, err := GetEventFromLogs(receipt.Logs, parser)
    if err == nil {
        return event
    }

    // Event not found - trace transaction for debugging
    trace := TraceTransaction(ctx, l1.RPCClient, receipt.TxHash)
    ginkgo.GinkgoWriter.Printf("Transaction trace:\n%s\n", trace)

    Fail("Event not found in logs. See trace above.")

    var zero T
    return zero
}
```

## Transaction Tracing

### Get Transaction Trace

```go
func TraceTransaction(
    ctx context.Context,
    client *ethclient.Client,
    txHash common.Hash,
) string {

    var result interface{}
    err := client.Client().CallContext(
        ctx,
        &result,
        "debug_traceTransaction",
        txHash,
        map[string]interface{}{
            "tracer": "callTracer",
        },
    )

    if err != nil {
        return fmt.Sprintf("Failed to trace: %v", err)
    }

    jsonBytes, _ := json.MarshalIndent(result, "", "  ")
    return string(jsonBytes)
}

func TraceTransactionAndExit(
    ctx context.Context,
    client *ethclient.Client,
    txHash common.Hash,
) {

    trace := TraceTransaction(ctx, client, txHash)
    ginkgo.GinkgoWriter.Printf("Transaction trace:\n%s\n", trace)
    Fail("Transaction trace requested")
}
```

## Contract Deployment

### Deploy Contract

```go
func DeployContract(
    ctx context.Context,
    l1 L1TestInfo,
    fromKey *ecdsa.PrivateKey,
    contractBytecode []byte,
) (common.Address, *types.Receipt) {

    fromAddress := crypto.PubkeyToAddress(fromKey.PublicKey)
    gasFeeCap, gasTipCap, nonce := CalculateTxParams(ctx, l1, fromAddress)

    tx := types.NewTx(&types.DynamicFeeTx{
        ChainID:   l1.EVMChainID,
        Nonce:     nonce,
        Gas:       5_000_000,
        GasFeeCap: gasFeeCap,
        GasTipCap: gasTipCap,
        Data:      contractBytecode,
    })

    signedTx := SignTransaction(tx, fromKey, l1.EVMChainID)
    receipt := SendTransactionAndWaitForSuccess(ctx, l1, signedTx)

    return receipt.ContractAddress, receipt
}
```

### Deploy with Constructor Args

```go
func DeployContractWithArgs(
    ctx context.Context,
    l1 L1TestInfo,
    fromKey *ecdsa.PrivateKey,
    contractBytecode []byte,
    constructorArgs []byte,
) (common.Address, *types.Receipt) {

    // Combine bytecode and constructor args
    data := append(contractBytecode, constructorArgs...)

    return DeployContract(ctx, l1, fromKey, data)
}
```

## Block and Network Utilities

### Wait for Block Acceptance

```go
func WaitForAllValidatorsToAcceptBlock(
    ctx context.Context,
    nodeURIs []string,
    blockchainID ids.ID,
    blockHeight uint64,
) {

    for _, nodeURI := range nodeURIs {
        Eventually(func() bool {
            client := ethclient.NewClient(nodeURI + "/ext/bc/" + blockchainID.String() + "/rpc")

            block, err := client.BlockByNumber(ctx, big.NewInt(int64(blockHeight)))
            if err != nil {
                return false
            }

            return block != nil
        }, 30*time.Second, 500*time.Millisecond).Should(BeTrue(),
            "Node %s did not accept block %d", nodeURI, blockHeight)
    }
}
```

### Advance Proposer VM

For networks using Proposer VM:

```go
func AdvanceProposerVM(
    ctx context.Context,
    l1 L1TestInfo,
    fundedKey *ecdsa.PrivateKey,
    numBlocks int,
) {

    recipient := common.HexToAddress("0x0123456789012345678901234567890123456789")

    for i := 0; i < numBlocks; i++ {
        // Send dummy transaction to produce block
        SendNativeTransfer(
            ctx,
            l1,
            fundedKey,
            recipient,
            big.NewInt(1),
        )
    }
}
```

## Balance Checking

### Check Balance

```go
func CheckBalance(
    ctx context.Context,
    address common.Address,
    expectedBalance *big.Int,
    client *ethclient.Client,
) {

    balance, err := client.BalanceAt(ctx, address, nil)
    Expect(err).NotTo(HaveOccurred())

    Expect(balance).To(Equal(expectedBalance),
        "Address %s has balance %s, expected %s",
        address.Hex(),
        balance.String(),
        expectedBalance.String())
}
```

### BigInt Helpers

```go
func ExpectBigEqual(a, b *big.Int) {
    Expect(a.Cmp(b)).To(Equal(0),
        "Expected %s to equal %s", a.String(), b.String())
}

func BigIntSub(a, b *big.Int) *big.Int {
    return new(big.Int).Sub(a, b)
}

func BigIntMul(a, b *big.Int) *big.Int {
    return new(big.Int).Mul(a, b)
}

func BigIntAdd(a, b *big.Int) *big.Int {
    return new(big.Int).Add(a, b)
}
```

## URI Conversion

### Convert HTTP to WebSocket/RPC

```go
func HttpToWebsocketURI(uri string, blockchainID string) string {
    return strings.Replace(uri, "http://", "ws://", 1) +
        "/ext/bc/" + blockchainID + "/ws"
}

func HttpToRPCURI(uri string, blockchainID string) string {
    return uri + "/ext/bc/" + blockchainID + "/rpc"
}
```

## Complete Helper Package Example

```go title="testutils/helpers.go"
package testutils

import (
    "context"
    "crypto/ecdsa"
    "math/big"
    "time"

    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/core/types"
    "github.com/ethereum/go-ethereum/crypto"
    . "github.com/onsi/gomega"
)

type TxHelper struct {
    L1   L1TestInfo
    Key  *ecdsa.PrivateKey
    From common.Address
}

func NewTxHelper(l1 L1TestInfo, key *ecdsa.PrivateKey) *TxHelper {
    return &TxHelper{
        L1:   l1,
        Key:  key,
        From: crypto.PubkeyToAddress(key.PublicKey),
    }
}

func (h *TxHelper) SendNative(
    ctx context.Context,
    to common.Address,
    amount *big.Int,
) *types.Receipt {
    return SendNativeTransfer(ctx, h.L1, h.Key, to, amount)
}

func (h *TxHelper) CallContract(
    ctx context.Context,
    contract common.Address,
    callData []byte,
    gasLimit uint64,
) *types.Receipt {
    tx := CreateContractCallTransaction(
        ctx, h.L1, h.Key, contract, callData, gasLimit,
    )
    return SendTransactionAndWaitForSuccess(ctx, h.L1, tx)
}

func (h *TxHelper) GetBalance(ctx context.Context) *big.Int {
    balance, err := h.L1.RPCClient.BalanceAt(ctx, h.From, nil)
    Expect(err).NotTo(HaveOccurred())
    return balance
}
```

## Usage in Tests

```go
var _ = ginkgo.Describe("[Transaction Tests]", func() {
    var helper *TxHelper

    ginkgo.BeforeEach(func() {
        helper = NewTxHelper(l1A, fundedKey)
    })

    ginkgo.It("should transfer native tokens", func() {
        ctx := context.Background()
        recipient := common.HexToAddress("0x1234...")
        amount := big.NewInt(1e18)

        initialBalance := helper.GetBalance(ctx)

        receipt := helper.SendNative(ctx, recipient, amount)
        Expect(receipt.Status).To(Equal(uint64(1)))

        finalBalance := helper.GetBalance(ctx)

        // Account for gas cost
        gasUsed := new(big.Int).Mul(
            receipt.EffectiveGasPrice,
            big.NewInt(int64(receipt.GasUsed)),
        )

        expected := BigIntSub(
            BigIntSub(initialBalance, amount),
            gasUsed,
        )

        ExpectBigEqual(finalBalance, expected)
    })
})
```

## Best Practices

1. **Always use CalculateTxParams**: Don't hardcode gas values
2. **Use Eventually for receipts**: Network delays are common
3. **Trace failed transactions**: Use TraceTransaction for debugging
4. **Extract events safely**: Use GetEventFromLogsOrTrace
5. **Check transaction status**: Always verify receipt.Status
6. **Handle BigInt carefully**: Use helper functions to avoid mutations

## Next Steps

<Cards>
  <Card title="Warp Messages" href="/docs/tooling/tmpnet/guides/warp-messages">
    Construct and sign Warp messages
  </Card>
  <Card title="Cross-Chain Messaging" href="/docs/tooling/tmpnet/guides/cross-chain-messaging">
    Use these utilities for Teleporter testing
  </Card>
  <Card title="Getting Started" href="/docs/tooling/tmpnet/guides/getting-started">
    Back to testing fundamentals
  </Card>
</Cards>


# Testing Native Token Staking (/docs/tooling/tmpnet/guides/validator-management-native-staking)

---
title: Testing Native Token Staking
description: Test complete validator lifecycle with native token staking on Lux L1s
---

This guide covers testing native token staking validators on L1s, including the complete lifecycle: registration, delegation, rewards, and removal.

> Pattern guide only. These examples follow the staking helpers in `icm-services` (see `tests/contracts/lib/icm-contracts/tests/network` for runnable code). They rely on shared utilities for contract bindings, Warp signatures, and tmpnet setup.

## Overview

Native token staking allows validators to stake the L1's native currency (like LUX) to secure the network. This guide covers:

- Deploying a native staking manager
- Registering validators with stake
- Adding and removing delegators
- Removing validators with uptime proofs
- Testing edge cases and failures

## Prerequisites

- Complete [Getting Started](/docs/tooling/tmpnet/guides/getting-started)
- Understand [L1 Conversion](/docs/tooling/tmpnet/guides/l1-conversion)
- Have an L1 converted to use native staking

## Complete Lifecycle Test

```go title="native_staking_test.go"
package staking_test

import (
    "context"
    "flag"
    "math/big"
    "os"
    "testing"
    "time"

    "github.com/luxfi/luxgo/ids"
    "github.com/luxfi/luxgo/tests/fixture/e2e"
    "github.com/luxfi/luxgo/tests/fixture/tmpnet"
    "github.com/luxfi/luxgo/units"
    nativestaking "github.com/luxfi/icm-contracts/abi-bindings/go/validator-manager/NativeTokenStakingManager"
    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/crypto"
    "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

var (
    network               *tmpnet.Network
    e2eFlags              *e2e.FlagVars
    l1Info                L1TestInfo
    stakingManagerAddress common.Address
    fundedKey             *ecdsa.PrivateKey
)

func TestMain(m *testing.M) {
    e2eFlags = e2e.RegisterFlags()
    flag.Parse()
    os.Exit(m.Run())
}

func TestNativeStaking(t *testing.T) {
    if os.Getenv("RUN_E2E") == "" {
        t.Skip("RUN_E2E not set")
    }

    RegisterFailHandler(ginkgo.Fail)
    ginkgo.RunSpecs(t, "Native Staking Test Suite")
}

var _ = ginkgo.BeforeSuite(func() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
    defer cancel()

    // Create network and convert L1 to native staking
    network, l1Info, stakingManagerAddress = setupNativeStakingL1(ctx)

    fundedKey = network.PreFundedKeys[0]
})

var _ = ginkgo.AfterSuite(func() {
    if network != nil {
        network.Stop(context.Background())
    }
})

var _ = ginkgo.Describe("[Native Token Staking]", func() {
    ginkgo.It("should complete full validator lifecycle",
        ginkgo.Label("staking", "validator"),
        func() {
            ctx := context.Background()

            // Register new validator
            validationID, node := registerValidator(
                ctx,
                network,
                l1Info,
                stakingManagerAddress,
                100*units.Lux,
                fundedKey,
            )

            // Add delegator
            delegationID := addDelegator(
                ctx,
                l1Info,
                stakingManagerAddress,
                validationID,
                50*units.Lux,
                fundedKey,
            )

            // Wait for active period
            time.Sleep(2 * time.Second)

            // Remove delegator
            removeDelegator(
                ctx,
                network,
                l1Info,
                stakingManagerAddress,
                delegationID,
                fundedKey,
            )

            // Remove validator
            removeValidator(
                ctx,
                network,
                l1Info,
                stakingManagerAddress,
                validationID,
                100, // 100% uptime
                fundedKey,
            )
        })
})
```

## Validator Registration

### Step-by-Step Registration Flow

The registration process has three phases:

1. **Initialize** - Submit registration on L1
2. **Platform-Chain** - Register on Platform-Chain with Warp message
3. **Complete** - Finalize with Platform-Chain acknowledgment

```go
func registerValidator(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    stakeAmount uint64,
    senderKey *ecdsa.PrivateKey,
) (ids.ID, *tmpnet.Node) {

    // Create new node to validate
    node := tmpnet.NewEphemeralNode(tmpnet.FlagsMap{})
    err := network.StartNode(ctx, node)
    Expect(err).NotTo(HaveOccurred())

    err = node.WaitForHealthy(ctx)
    Expect(err).NotTo(HaveOccurred())

    // Step 1: Initialize registration on L1
    registrationReceipt := initializeValidatorRegistration(
        ctx,
        l1,
        stakingManagerAddress,
        node,
        stakeAmount,
        senderKey,
    )

    // Extract registration details from event
    validationID, warpMessage := extractRegistrationInfo(registrationReceipt)

    // Step 2: Register on Platform-Chain
    registerOnPChain(
        ctx,
        network,
        l1.SubnetID,
        node,
        stakeAmount,
        warpMessage,
        senderKey,
    )

    // Step 3: Complete registration with Platform-Chain proof
    completeRegistration(
        ctx,
        network,
        l1,
        stakingManagerAddress,
        validationID,
        senderKey,
    )

    // Verify validator is active
    verifyValidatorActive(ctx, l1, stakingManagerAddress, validationID)

    return validationID, node
}
```

### Initialize Registration

```go
func initializeValidatorRegistration(
    ctx context.Context,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    node *tmpnet.Node,
    stakeAmount uint64,
    senderKey *ecdsa.PrivateKey,
) *types.Receipt {

    stakingManager, err := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )
    Expect(err).NotTo(HaveOccurred())

    // Prepare node PoP (Proof of Possession)
    nodeID := node.NodeID
    blsPublicKey := node.BlsPublicKey
    expiry := uint64(time.Now().Add(24 * time.Hour).Unix())

    // Create transaction with staked native tokens
    opts, err := bind.NewKeyedTransactorWithChainID(senderKey, l1.EVMChainID)
    Expect(err).NotTo(HaveOccurred())

    // Send native tokens as stake
    opts.Value = new(big.Int).SetUint64(stakeAmount)

    // Call initializeValidatorRegistration
    tx, err := stakingManager.InitializeValidatorRegistration(
        opts,
        nativestaking.ValidatorRegistrationInput{
            NodeID:             nodeID.Bytes(),
            BlsPublicKey:       blsPublicKey,
            RegistrationExpiry: expiry,
            RemainingBalanceOwner: nativestaking.PChainOwner{
                Threshold: 1,
                Addresses: []common.Address{
                    crypto.PubkeyToAddress(senderKey.PublicKey),
                },
            },
            DisableOwner: nativestaking.PChainOwner{
                Threshold: 1,
                Addresses: []common.Address{
                    crypto.PubkeyToAddress(senderKey.PublicKey),
                },
            },
        },
        uint16(20), // Delegation fee: 20%
        uint64(1),  // Min stake duration: 1 second
    )
    Expect(err).NotTo(HaveOccurred())

    receipt := waitForSuccess(ctx, l1, tx.Hash())

    return receipt
}
```

### Register on Platform-Chain

```go
func registerOnPChain(
    ctx context.Context,
    network *tmpnet.Network,
    subnetID ids.ID,
    node *tmpnet.Node,
    stakeAmount uint64,
    warpMessage []byte,
    senderKey *ecdsa.PrivateKey,
) {

    // Get Platform-Chain wallet
    pWallet := network.GetPChainWallet(senderKey)

    // Issue RegisterL1ValidatorTx
    txID, err := pWallet.IssueRegisterL1ValidatorTx(
        stakeAmount,
        node.NodePoP.ProofOfPossession,
        warpMessage,
    )
    Expect(err).NotTo(HaveOccurred())

    // Wait for Platform-Chain acceptance
    Eventually(func() bool {
        status, err := pWallet.GetTxStatus(ctx, txID)
        if err != nil {
            return false
        }
        return status == status.Committed
    }, 30*time.Second, 500*time.Millisecond).Should(BeTrue())
}
```

### Complete Registration

```go
func completeRegistration(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    validationID ids.ID,
    senderKey *ecdsa.PrivateKey,
) {

    // Get Platform-Chain info
    pChainInfo := getPChainInfo(network)

    // Query Platform-Chain for registration message
    unsignedMessage := createL1ValidatorRegistrationMessage(
        validationID,
        true, // valid
    )

    // Sign with Platform-Chain validators
    aggregator := NewSignatureAggregator(
        pChainInfo.NodeURIs[0],
        []ids.ID{constants.PrimaryNetworkID},
    )
    defer aggregator.Shutdown()

    signedMessage, err := aggregator.CreateSignedMessage(
        unsignedMessage,
        nil,
        constants.PrimaryNetworkID,
        67,
    )
    Expect(err).NotTo(HaveOccurred())

    // Complete on L1 with signed message
    stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )

    tx := createPredicateTx(
        ctx,
        l1,
        stakingManagerAddress,
        signedMessage,
        senderKey,
        func(opts *bind.TransactOpts) (*types.Transaction, error) {
            return stakingManager.CompleteValidatorRegistration(opts, 0)
        },
    )

    err = l1.RPCClient.SendTransaction(ctx, tx)
    Expect(err).NotTo(HaveOccurred())

    receipt := waitForSuccess(ctx, l1, tx.Hash())

    // Verify completion event
    event, err := getEventFromLogs(
        receipt.Logs,
        stakingManager.ParseValidatorRegistrationCompleted,
    )
    Expect(err).NotTo(HaveOccurred())
    Expect(event.ValidationID).To(Equal(validationID))
}
```

## Delegation

### Adding a Delegator

```go
func addDelegator(
    ctx context.Context,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    validationID ids.ID,
    delegationAmount uint64,
    delegatorKey *ecdsa.PrivateKey,
) ids.ID {

    // Step 1: Initialize delegation
    delegationID := initializeDelegation(
        ctx,
        l1,
        stakingManagerAddress,
        validationID,
        delegationAmount,
        delegatorKey,
    )

    // Step 2: Complete delegation (similar to validator registration)
    completeDelegation(
        ctx,
        l1,
        stakingManagerAddress,
        delegationID,
        delegatorKey,
    )

    return delegationID
}

func initializeDelegation(
    ctx context.Context,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    validationID ids.ID,
    delegationAmount uint64,
    delegatorKey *ecdsa.PrivateKey,
) ids.ID {

    stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )

    opts, _ := bind.NewKeyedTransactorWithChainID(delegatorKey, l1.EVMChainID)
    opts.Value = new(big.Int).SetUint64(delegationAmount)

    tx, err := stakingManager.InitializeDelegatorRegistration(
        opts,
        validationID,
    )
    Expect(err).NotTo(HaveOccurred())

    receipt := waitForSuccess(ctx, l1, tx.Hash())

    // Extract delegation ID from event
    event, err := getEventFromLogs(
        receipt.Logs,
        stakingManager.ParseDelegatorAdded,
    )
    Expect(err).NotTo(HaveOccurred())

    return event.DelegationID
}
```

### Removing a Delegator

```go
func removeDelegator(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    delegationID ids.ID,
    delegatorKey *ecdsa.PrivateKey,
) {

    // Step 1: Initialize end delegation
    initializeEndDelegation(
        ctx,
        l1,
        stakingManagerAddress,
        delegationID,
        delegatorKey,
    )

    // Step 2: Complete end delegation with uptime proof
    completeEndDelegation(
        ctx,
        network,
        l1,
        stakingManagerAddress,
        delegationID,
        delegatorKey,
    )

    // Verify delegation removed
    stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )

    delegation, err := stakingManager.GetDelegation(
        &bind.CallOpts{},
        delegationID,
    )
    Expect(err).NotTo(HaveOccurred())
    Expect(delegation.Status).To(Equal(DelegationStatusCompleted))
}
```

## Validator Removal

### Removing with Uptime Proof

```go
func removeValidator(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    validationID ids.ID,
    uptimePercentage uint64,
    senderKey *ecdsa.PrivateKey,
) {

    // Step 1: Initialize validator removal
    initializeEndValidation(
        ctx,
        l1,
        stakingManagerAddress,
        validationID,
        senderKey,
    )

    // Step 2: Complete with uptime proof from Platform-Chain
    completeEndValidationWithUptime(
        ctx,
        network,
        l1,
        stakingManagerAddress,
        validationID,
        uptimePercentage,
        senderKey,
    )

    // Verify validator removed
    verifyValidatorRemoved(ctx, l1, stakingManagerAddress, validationID)
}

func completeEndValidationWithUptime(
    ctx context.Context,
    network *tmpnet.Network,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    validationID ids.ID,
    uptimePercentage uint64,
    senderKey *ecdsa.PrivateKey,
) {

    // Create L1ValidatorWeightMessage with uptime
    unsignedMessage := createL1ValidatorWeightMessage(
        validationID,
        0, // nonce
        0, // weight (removal)
        uptimePercentage,
    )

    // Sign with Platform-Chain validators
    pChainInfo := getPChainInfo(network)
    aggregator := NewSignatureAggregator(
        pChainInfo.NodeURIs[0],
        []ids.ID{constants.PrimaryNetworkID},
    )
    defer aggregator.Shutdown()

    signedMessage, err := aggregator.CreateSignedMessage(
        unsignedMessage,
        nil,
        constants.PrimaryNetworkID,
        67,
    )
    Expect(err).NotTo(HaveOccurred())

    // Complete on L1
    stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )

    tx := createPredicateTx(
        ctx,
        l1,
        stakingManagerAddress,
        signedMessage,
        senderKey,
        func(opts *bind.TransactOpts) (*types.Transaction, error) {
            return stakingManager.CompleteEndValidation(opts, 0)
        },
    )

    err = l1.RPCClient.SendTransaction(ctx, tx)
    Expect(err).NotTo(HaveOccurred())

    receipt := waitForSuccess(ctx, l1, tx.Hash())

    // Verify completion event
    event, err := getEventFromLogs(
        receipt.Logs,
        stakingManager.ParseValidationPeriodEnded,
    )
    Expect(err).NotTo(HaveOccurred())
    Expect(event.ValidationID).To(Equal(validationID))
}
```

## Testing Edge Cases

### Minimum Stake Requirements

```go
ginkgo.It("should enforce minimum stake",
    ginkgo.Label("staking", "validation"),
    func() {
        ctx := context.Background()

        // Try to register with less than minimum stake
        stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
            stakingManagerAddress,
            l1Info.RPCClient,
        )

        // Get minimum stake
        minStake, err := stakingManager.MinimumStakeAmount(&bind.CallOpts{})
        Expect(err).NotTo(HaveOccurred())

        // Try with less than minimum
        belowMinimum := new(big.Int).Sub(minStake, big.NewInt(1))

        opts, _ := bind.NewKeyedTransactorWithChainID(fundedKey, l1Info.EVMChainID)
        opts.Value = belowMinimum

        _, err = stakingManager.InitializeValidatorRegistration(
            opts,
            validatorInput,
            20,
            1,
        )

        // Should fail
        Expect(err).To(HaveOccurred())
    })
```

### Expired Registration

```go
ginkgo.It("should reject expired registration",
    ginkgo.Label("staking", "validation"),
    func() {
        ctx := context.Background()

        node := createTestNode(ctx, network)

        // Create registration with past expiry
        expiry := uint64(time.Now().Add(-1 * time.Hour).Unix())

        validatorInput := nativestaking.ValidatorRegistrationInput{
            NodeID:             node.NodeID.Bytes(),
            BlsPublicKey:       node.BlsPublicKey,
            RegistrationExpiry: expiry,
            // ... other fields
        }

        // Initialize registration
        receipt := initializeValidatorRegistration(
            ctx,
            l1Info,
            stakingManagerAddress,
            validatorInput,
            100*units.Lux,
            fundedKey,
        )

        validationID, warpMessage := extractRegistrationInfo(receipt)

        // Try to register on Platform-Chain - should fail due to expiry
        pWallet := network.GetPChainWallet(fundedKey)

        _, err := pWallet.IssueRegisterL1ValidatorTx(
            100*units.Lux,
            node.NodePoP.ProofOfPossession,
            warpMessage,
        )

        Expect(err).To(HaveOccurred())
        Expect(err.Error()).To(ContainSubstring("expired"))
    })
```

## Helper Functions

### Verify Validator Status

```go
func verifyValidatorActive(
    ctx context.Context,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    validationID ids.ID,
) {
    stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )

    validator, err := stakingManager.GetValidator(&bind.CallOpts{}, validationID)
    Expect(err).NotTo(HaveOccurred())

    Expect(validator.Status).To(Equal(ValidatorStatusActive))
    Expect(validator.Weight).To(BeNumerically(">", 0))
    Expect(validator.StartedAt).To(BeNumerically(">", 0))
}
```

### Check Delegation Rewards

```go
func checkDelegationRewards(
    ctx context.Context,
    l1 L1TestInfo,
    stakingManagerAddress common.Address,
    delegationID ids.ID,
    expectedMinimum uint64,
) {
    stakingManager, _ := nativestaking.NewNativeTokenStakingManager(
        stakingManagerAddress,
        l1.RPCClient,
    )

    delegation, err := stakingManager.GetDelegation(&bind.CallOpts{}, delegationID)
    Expect(err).NotTo(HaveOccurred())

    // Check rewards accrued
    Expect(delegation.Rewards).To(BeNumerically(">=", expectedMinimum))
}
```

## Best Practices

1. **Always complete registration**: Don't leave validators in pending state
2. **Test minimum/maximum stakes**: Verify contract validation works
3. **Handle Platform-Chain delays**: Platform-Chain operations can be slow, use appropriate timeouts
4. **Verify uptime calculations**: Test different uptime percentages
5. **Clean up validators**: Remove test validators in AfterEach/AfterSuite
6. **Test delegation limits**: Verify maximum delegators per validator

## Next Steps

<Cards>
  <Card title="L1 Conversion" href="/docs/tooling/tmpnet/guides/l1-conversion">
    Convert subnets to L1s with validator managers
  </Card>
  <Card title="Staking and Delegation" href="/docs/tooling/tmpnet/guides/staking-and-delegation">
    Test staking and delegation workflows
  </Card>
  <Card title="Configuration Reference" href="/docs/tooling/tmpnet/reference/configuration">
    Complete configuration options for tmpnet
  </Card>
</Cards>


# Warp Message Construction (/docs/tooling/tmpnet/guides/warp-messages)

---
title: Warp Message Construction
description: Learn how to construct, sign, and verify Warp messages for cross-chain communication
---

Warp messages enable secure cross-chain communication on Lux. This guide covers constructing unsigned messages, aggregating signatures, and verifying signed messages.

## Overview

Warp message flow:
1. **Extract** unsigned message from transaction logs
2. **Wait** for validator acceptance
3. **Aggregate** signatures from validators
4. **Create** signed message
5. **Include** in predicate transaction on destination

## Extracting Unsigned Messages

### From Transaction Logs

```go
func ExtractWarpMessageFromLogs(
    ctx context.Context,
    receipt *types.Receipt,
    source L1TestInfo,
) *luxWarp.UnsignedMessage {

    // Find SendWarpMessage log
    var warpMessageBytes []byte

    for _, log := range receipt.Logs {
        if log.Topics[0] == warpMesssageEventTopic {
            warpMessageBytes = log.Data
            break
        }
    }

    Expect(warpMessageBytes).NotTo(BeEmpty())

    // Parse unsigned message
    unsignedMessage, err := luxWarp.ParseUnsignedMessage(warpMessageBytes)
    Expect(err).NotTo(HaveOccurred())

    return unsignedMessage
}
```

## Signature Aggregation

### Setting Up Aggregator

```go
type SignatureAggregator struct {
    client    *aggregator.SignatureAggregatorClient
    subnetIDs []ids.ID
}

func NewSignatureAggregator(
    nodeURI string,
    subnetIDs []ids.ID,
) *SignatureAggregator {

    apiURI := fmt.Sprintf("%s/ext/bc/P", nodeURI)

    client, err := aggregator.NewSignatureAggregatorClient(apiURI)
    Expect(err).NotTo(HaveOccurred())

    return &SignatureAggregator{
        client:    client,
        subnetIDs: subnetIDs,
    }
}

func (a *SignatureAggregator) Shutdown() {
    // Clean up resources
}
```

### Creating Signed Messages

```go
func (a *SignatureAggregator) CreateSignedMessage(
    unsignedMessage *luxWarp.UnsignedMessage,
    justification []byte,
    subnetID ids.ID,
    quorumNum uint64,
) (*luxWarp.Message, error) {

    signedMessage, err := a.client.AggregateSignatures(
        context.Background(),
        unsignedMessage.ID(),
        justification,
        subnetID,
        quorumNum,
    )

    return signedMessage, err
}
```

## Complete Construction Flow

```go
func ConstructSignedWarpMessage(
    ctx context.Context,
    sourceReceipt *types.Receipt,
    source L1TestInfo,
    destination L1TestInfo,
    justification []byte,
    aggregator *SignatureAggregator,
) *luxWarp.Message {

    // Step 1: Extract unsigned message
    unsignedMessage := ExtractWarpMessageFromLogs(ctx, sourceReceipt, source)

    // Step 2: Wait for block acceptance
    WaitForAllValidatorsToAcceptBlock(
        ctx,
        source.NodeURIs,
        source.BlockchainID,
        sourceReceipt.BlockNumber.Uint64(),
    )

    // Step 3: Aggregate signatures (67% quorum)
    signedMessage, err := aggregator.CreateSignedMessage(
        unsignedMessage,
        justification,
        source.SubnetID,
        67, // warp.WarpDefaultQuorumNumerator
    )
    Expect(err).NotTo(HaveOccurred())

    return signedMessage
}
```

## Using Signed Messages

### In Predicate Transactions

```go
// Create transaction with Warp message
tx := predicateutils.NewPredicateTx(
    l1.EVMChainID,
    nonce,
    &contractAddress,
    gasLimit,
    gasFeeCap,
    gasTipCap,
    big.NewInt(0),
    callData,
    types.AccessList{},
    warp.ContractAddress,      // Predicate address
    signedMessage.Bytes(),      // Warp message
)
```

## Best Practices

1. **Always wait for acceptance**: Don't aggregate before validators see the block
2. **Use 67% quorum**: Standard for Warp messages
3. **Clean up aggregator**: Always defer `aggregator.Shutdown()`
4. **Handle errors**: Signature aggregation can fail if nodes are down
5. **Cache aggregators**: Reuse for multiple messages in same test

## Next Steps

<Cards>
  <Card title="Cross-Chain Messaging" href="/docs/tooling/tmpnet/guides/cross-chain-messaging">
    Use Warp messages for Teleporter
  </Card>
  <Card title="Transaction Utilities" href="/docs/tooling/tmpnet/guides/transaction-utilities">
    Helper functions for transactions
  </Card>
</Cards>


# CLI Commands Reference (/docs/tooling/tmpnet/reference/cli-commands)

---
title: CLI Commands Reference
description: Complete reference for all tmpnetctl commands and options
---

This reference covers all commands available in the `tmpnetctl` CLI tool.

## Global Flags

These flags are available for all commands:

| Flag | Description | Default |
|------|-------------|---------|
| `--network-dir` | Path to an existing network (needed for stop/restart/check) | `$TMPNET_NETWORK_DIR` if set |
| `--log-format` | Logging format (auto, json) | `auto` |
| `--help, -h` | Show help | |

## Network Commands

### start-network

Start a new temporary network.

```bash
tmpnetctl start-network [flags]
```

**Flags:**

| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--luxgo-path` | string | Path to luxgo binary | `$LUXGO_PATH` (required) |
| `--plugin-dir` | string | Directory containing VM plugins | `$AVAGO_PLUGIN_DIR` or `~/.luxgo/plugins` |
| `--node-count` | int | Number of validator nodes | `5` |
| `--network-owner` | string | Owner identifier for the network | `tmpnet-owner` |
| `--root-dir` | string | Root directory for networks | `~/.tmpnet/networks` |

**Example:**

```bash
# Start default 5-node network
tmpnetctl start-network --luxgo-path=./bin/luxgo

# Start 3-node network
tmpnetctl start-network --luxgo-path=./bin/luxgo --node-count=3

# Custom plugin directory
tmpnetctl start-network \
  --luxgo-path=./bin/luxgo \
  --plugin-dir=/custom/plugins
```

**Output:**

```
Starting network with 5 nodes
...
Started network /home/user/.tmpnet/networks/20240312-143052.123456 (UUID: abc-123...)

Configure tmpnetctl to target this network by default:
 - source /home/user/.tmpnet/networks/20240312-143052.123456/network.env
 - export TMPNET_NETWORK_DIR=/home/user/.tmpnet/networks/20240312-143052.123456
 - export TMPNET_NETWORK_DIR=/home/user/.tmpnet/networks/latest
```

### stop-network

Stop a running network.

```bash
tmpnetctl stop-network [flags]
```

**Flags:**

| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--network-dir` | string | Network directory to stop | `$TMPNET_NETWORK_DIR` (required) |

**Example:**

```bash
# Stop using TMPNET_NETWORK_DIR
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest
tmpnetctl stop-network

# Stop with explicit path
tmpnetctl stop-network --network-dir=~/.tmpnet/networks/20240312-143052.123456
```

### restart-network

Restart a stopped network.

```bash
tmpnetctl restart-network [flags]
```

**Flags:**

| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--network-dir` | string | Network directory to restart | `$TMPNET_NETWORK_DIR` (required) |

**Example:**

```bash
# Restart using TMPNET_NETWORK_DIR
tmpnetctl restart-network

# Restart with explicit path
tmpnetctl restart-network --network-dir=~/.tmpnet/networks/latest
```

## Monitoring Commands

### start-metrics-collector

Start Prometheus to collect metrics from networks.

```bash
tmpnetctl start-metrics-collector [flags]
```

**Required Environment Variables:**

- `PROMETHEUS_URL` - Prometheus backend URL
- `PROMETHEUS_PUSH_URL` - Prometheus push URL
- `PROMETHEUS_USERNAME` - Username for authentication
- `PROMETHEUS_PASSWORD` - Password for authentication

**Example:**

```bash
# Set environment variables
export PROMETHEUS_URL="https://prometheus.example.com"
export PROMETHEUS_PUSH_URL="https://prometheus.example.com/api/v1/push"
export PROMETHEUS_USERNAME="user"
export PROMETHEUS_PASSWORD="pass"

# Start collector
tmpnetctl start-metrics-collector
```

**Output:**

```
Starting Prometheus metrics collector...
Metrics collector started successfully
```

### stop-metrics-collector

Stop the running Prometheus metrics collector.

```bash
tmpnetctl stop-metrics-collector
```

**Example:**

```bash
tmpnetctl stop-metrics-collector
```

### start-logs-collector

Start Promtail to collect logs from networks.

```bash
tmpnetctl start-logs-collector [flags]
```

**Required Environment Variables:**

- `LOKI_URL` - Loki backend URL
- `LOKI_PUSH_URL` - Loki push URL
- `LOKI_USERNAME` - Username for authentication
- `LOKI_PASSWORD` - Password for authentication

**Example:**

```bash
# Set environment variables
export LOKI_URL="https://loki.example.com"
export LOKI_PUSH_URL="https://loki.example.com/loki/api/v1/push"
export LOKI_USERNAME="user"
export LOKI_PASSWORD="pass"

# Start collector
tmpnetctl start-logs-collector
```

### stop-logs-collector

Stop the running Promtail logs collector.

```bash
tmpnetctl stop-logs-collector
```

**Example:**

```bash
tmpnetctl stop-logs-collector
```

### check-metrics

Verify that metrics are being collected for a network.

```bash
tmpnetctl check-metrics [flags]
```

**Flags:**

| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--network-dir` | string | Network directory | `$TMPNET_NETWORK_DIR` (required) |

**Required Environment Variables:**

- `PROMETHEUS_URL`
- `PROMETHEUS_USERNAME`
- `PROMETHEUS_PASSWORD`

**Example:**

```bash
tmpnetctl check-metrics --network-dir=~/.tmpnet/networks/latest
```

**Output:**

```
Checking metrics for network abc-123...
✓ Metrics found for network
```

### check-logs

Verify that logs are being collected for a network.

```bash
tmpnetctl check-logs [flags]
```

**Flags:**

| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--network-dir` | string | Network directory | `$TMPNET_NETWORK_DIR` (required) |

**Required Environment Variables:**

- `LOKI_URL`
- `LOKI_USERNAME`
- `LOKI_PASSWORD`

**Example:**

```bash
tmpnetctl check-logs --network-dir=~/.tmpnet/networks/latest
```

## Kubernetes Commands

### start-kind-cluster

Start a local kind (Kubernetes in Docker) cluster for tmpnet.

```bash
tmpnetctl start-kind-cluster [flags]
```

**Flags:**

| Flag | Type | Description | Default |
|------|------|-------------|---------|
| `--kubeconfig` | string | Path to kubeconfig file | `~/.kube/config` |
| `--start-metrics-collector` | bool | Start metrics collector | `false` |
| `--start-logs-collector` | bool | Start logs collector | `false` |
| `--install-chaos-mesh` | bool | Install Chaos Mesh | `false` |

**Example:**

```bash
# Start basic kind cluster
tmpnetctl start-kind-cluster

# Start with monitoring
tmpnetctl start-kind-cluster \
  --start-metrics-collector \
  --start-logs-collector

# Start with Chaos Mesh for chaos engineering
tmpnetctl start-kind-cluster --install-chaos-mesh
```

## Utility Commands

### version

Print tmpnetctl version information.

```bash
tmpnetctl version
```

**Example:**

```bash
tmpnetctl version
```

**Output:**

```
tmpnetctl version 1.11.0
```

### help

Show help for tmpnetctl or a specific command.

```bash
tmpnetctl help [command]
```

**Example:**

```bash
# General help
tmpnetctl help

# Help for specific command
tmpnetctl help start-network
```

## Common Usage Patterns

### Setting Up a Network

Complete workflow for creating and using a network:

```bash
# Build binaries
./scripts/build.sh
./scripts/build_tmpnetctl.sh

# Start network
tmpnetctl start-network --luxgo-path=./bin/luxgo

# Configure shell
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest

# Use the network...

# Stop when done
tmpnetctl stop-network
```

### Using with direnv

Simplify commands with direnv:

```bash
# Enable direnv
cd luxgo
direnv allow

# Now you can use simplified commands
tmpnetctl start-network        # No --luxgo-path needed
tmpnetctl stop-network
tmpnetctl restart-network
```

### Monitoring Workflow

Set up monitoring for development:

```bash
# Configure monitoring environment
export PROMETHEUS_URL="..."
export PROMETHEUS_PUSH_URL="..."
export PROMETHEUS_USERNAME="..."
export PROMETHEUS_PASSWORD="..."
export LOKI_URL="..."
export LOKI_PUSH_URL="..."
export LOKI_USERNAME="..."
export LOKI_PASSWORD="..."

# Start collectors once
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector

# Create/destroy networks as needed
tmpnetctl start-network --luxgo-path=./bin/luxgo
# ... test ...
tmpnetctl stop-network

# Collectors continue running
# Stop when done
tmpnetctl stop-metrics-collector
tmpnetctl stop-logs-collector
```

### Multiple Networks

Manage multiple networks:

```bash
# Start first network
tmpnetctl start-network --luxgo-path=./bin/luxgo
NETWORK1=~/.tmpnet/networks/latest

# Start second network
tmpnetctl start-network --luxgo-path=./bin/luxgo
NETWORK2=~/.tmpnet/networks/latest

# Target specific networks
tmpnetctl stop-network --network-dir=$NETWORK1
tmpnetctl restart-network --network-dir=$NETWORK2
```

## Environment Configuration

### Recommended Shell Setup

Add to your `.bashrc` or `.zshrc`:

```bash
# Set default network to latest
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest

# Set luxgo path
export LUXGO_PATH=~/luxgo/bin/luxgo

# Add tmpnetctl to PATH (if not using direnv)
export PATH=$PATH:~/luxgo/bin
```

### Monitoring Environment

Create a monitoring env file:

```bash
# monitoring.env
export PROMETHEUS_URL="https://prometheus.example.com"
export PROMETHEUS_PUSH_URL="https://prometheus.example.com/api/v1/push"
export PROMETHEUS_USERNAME="user"
export PROMETHEUS_PASSWORD="pass"
export LOKI_URL="https://loki.example.com"
export LOKI_PUSH_URL="https://loki.example.com/loki/api/v1/push"
export LOKI_USERNAME="user"
export LOKI_PASSWORD="pass"
```

Source when needed:

```bash
source monitoring.env
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector
```

## Exit Codes

tmpnetctl uses standard exit codes:

- `0` - Success
- `1` - General error
- `2` - Invalid arguments or usage

## Error Handling

### Common Errors

**Network directory not found:**
```
Error: network directory not found: /path/to/network
```
**Solution:** Check that `TMPNET_NETWORK_DIR` is set correctly or provide `--network-dir`

**Binary not found:**
```
Error: luxgo binary not found: /path/to/luxgo
```
**Solution:** Verify `--luxgo-path` points to a valid binary

**Port already in use:**
```
Error: failed to start node: address already in use
```
**Solution:** Stop conflicting processes or use dynamic ports (default)

**Missing monitoring credentials:**
```
Error: PROMETHEUS_URL environment variable not set
```
**Solution:** Set required environment variables for monitoring

## See Also

- [Configuration Reference](/docs/tooling/tmpnet/reference/configuration)
- [Quick Start Guide](/docs/tooling/tmpnet/quick-start)
- [Monitoring Guide](/docs/tooling/tmpnet/guides/monitoring)
- [Full README](https://github.com/luxfi/luxgo/blob/master/tests/fixture/tmpnet/README.md)


# Configuration Reference (/docs/tooling/tmpnet/reference/configuration)

---
title: Configuration Reference
description: Complete reference for tmpnet configuration options
---

This reference covers all configuration options available in tmpnet for networks, nodes, subnets, and chains.

## Network Configuration

The `Network` type represents a complete temporary network.

### Basic Properties

```go
type Network struct {
    // Owner identifier for the network
    Owner string

    // UUID for unique identification across hosts
    UUID string

    // Genesis configuration for the network
    Genesis *genesis.Genesis

    // Collection of nodes in the network
    Nodes []*Node

    // Subnets to create on the network
    Subnets []*Subnet

    // Keys pre-funded in genesis
    PreFundedKeys []*secp256k1.PrivateKey

    // Default flags applied to all nodes
    DefaultFlags FlagsMap

    // Default runtime configuration for nodes
    DefaultRuntimeConfig NodeRuntimeConfig

    // Network directory path
    Dir string
}
```

### Default Flags

Common default flags for networks:

```go
network.DefaultFlags = tmpnet.FlagsMap{
    // Logging
    "log-level":         "info",      // trace, debug, info, warn, error, fatal
    "log-display-level": "info",
    "log-format":        "auto",      // auto, plain, colors, json

    // Network
    "network-id":                    "local",
    "network-max-reconnect-delay":   "1s",
    "public-ip":                     "127.0.0.1",
    "public-ip-resolution-service":  "",

    // Staking
    "staking-enabled":               "true",
    "staking-tls-cert-file":         "", // Auto-generated
    "staking-tls-key-file":          "", // Auto-generated

    // API
    "http-host":                     "",
    "http-port":                     "0", // Dynamic port
    "staking-port":                  "0", // Dynamic port

    // Performance
    "snow-sample-size":              "2",
    "snow-quorum-size":              "2",
    "proposervm-use-current-height": "true",
}
```

### Configuration on Disk

Network configuration is stored at `[network-dir]/config.json`:

```json
{
  "owner": "test-owner",
  "uuid": "abc-123-def-456",
  "defaultFlags": {
    "log-level": "info",
    "network-id": "local"
  },
  "defaultRuntimeConfig": {
    "process": {
      "luxGoPath": "/path/to/luxgo",
      "pluginDir": "/path/to/plugins"
    }
  },
  "preFundedKeys": ["PrivateKey-..."],
  "subnets": []
}
```

## Node Configuration

The `Node` type represents a single LuxGo node.

### Basic Properties

```go
type Node struct {
    // Node identifier derived from staking certificate
    NodeID ids.NodeID

    // Node-specific flags (override network defaults)
    Flags FlagsMap

    // Optional node-specific runtime configuration
    RuntimeConfig *NodeRuntimeConfig

    // URI of the node's API endpoint (set at runtime)
    URI string

    // Staking address for P2P (set at runtime)
    StakingAddress string

    // Whether this is a temporary/ephemeral node
    IsEphemeral bool
}
```

### Node-Specific Flags

Override network defaults for individual nodes:

```go
node.Flags = tmpnet.FlagsMap{
    "log-level":  "debug",        // More verbose than network default
    "http-port":  "9650",          // Fixed port instead of dynamic
    "track-subnets": "subnet-id",  // Track specific subnet
}
```

### Node Configuration Files

**Runtime Config** (`[node-dir]/config.json`):
```json
{
  "process": {
    "luxGoPath": "/path/to/luxgo",
    "pluginDir": "/path/to/plugins"
  }
}
```

**Flags** (`[node-dir]/flags.json`):
```json
{
  "log-level": "info",
  "http-host": "",
  "http-port": "0",
  "staking-port": "0",
  "network-id": "local",
  "genesis-file-content": "...",
  "track-subnets": ""
}
```

<Callout type="info" title="Dynamic Port Allocation">
The `"http-port": "0"` and `"staking-port": "0"` values tell the OS to allocate available ports dynamically. The actual allocated ports are written to `process.json` by luxgo at startup.
</Callout>

**Process Info** (`[node-dir]/process.json`):

This file is created by **luxgo itself** (not tmpnetctl) when the node starts. Tmpnet passes the `--process-context-file` flag to luxgo, which writes the runtime information to this file.

```json
{
  "pid": 12345,
  "uri": "http://127.0.0.1:56395",
  "stakingAddress": "127.0.0.1:56396"
}
```

| Field | Description |
|-------|-------------|
| `pid` | Process ID of the running luxgo instance |
| `uri` | HTTP API endpoint with the dynamically allocated port |
| `stakingAddress` | Staking/P2P address with the dynamically allocated port |

<Callout type="warning" title="Manual Setups">
If you're running luxgo manually (not via tmpnetctl), you must pass `--process-context-file=/path/to/process.json` for this file to be created. Without this flag, there's no way to discover which ports were allocated.
</Callout>

## Runtime Configuration

Runtime configuration controls how nodes are executed.

### Process Runtime

For local process-based nodes:

```go
type ProcessRuntimeConfig struct {
    // Path to luxgo binary
    LuxGoPath string

    // Plugin directory for custom VMs
    PluginDir string

    // Whether to reuse dynamic ports across restarts
    ReuseDynamicPorts bool
}
```

**Usage:**
```go
network.DefaultRuntimeConfig = tmpnet.NodeRuntimeConfig{
    Process: &tmpnet.ProcessRuntimeConfig{
        LuxGoPath:   "/path/to/luxgo",
        PluginDir:         "~/.luxgo/plugins",
        ReuseDynamicPorts: true,
    },
}
```

### Kubernetes Runtime

For Kubernetes-based deployment:

```go
type KubeRuntimeConfig struct {
    // Kubeconfig file path
    ConfigPath string

    // Kubeconfig context to use
    ConfigContext string

    // Target namespace
    Namespace string

    // Docker image for nodes
    Image string

    // Persistent volume size in GB
    VolumeSizeGB int

    // Use exclusive scheduling (one pod per k8s node)
    UseExclusiveScheduling bool

    // Custom scheduling labels
    SchedulingLabelKey   string
    SchedulingLabelValue string

    // Ingress configuration
    IngressHost   string
    IngressSecret string
}
```

## FlagsMap

`FlagsMap` is a string map for luxgo flags with special handling for defaults.

### Operations

```go
flags := tmpnet.FlagsMap{
    "log-level": "info",
}

// Set a value
flags["log-level"] = "debug"

// Set only if not already set
flags.SetDefault("log-level", "warn") // No effect, already set

// Set multiple defaults
flags.SetDefaults(tmpnet.FlagsMap{
    "log-display-level": "info",
    "http-port":         "0",
})

// Get a value
logLevel := flags["log-level"]
```

### Common Flags

**Logging:**
- `log-level` - Minimum log level (trace, debug, info, warn, error, fatal)
- `log-display-level` - Level to display
- `log-format` - Format (auto, plain, colors, json)

**Network:**
- `network-id` - Network identifier
- `bootstrap-ips` - Bootstrap node IPs (auto-configured)
- `bootstrap-ids` - Bootstrap node IDs (auto-configured)
- `public-ip` - Node's public IP

**API:**
- `http-host` - HTTP host for API
- `http-port` - HTTP port (0 for dynamic)
- `http-allowed-hosts` - Allowed hosts for API

**Staking:**
- `staking-enabled` - Enable staking
- `staking-port` - Staking port (0 for dynamic)
- `staking-tls-cert-file` - TLS certificate path
- `staking-tls-key-file` - TLS key path

**Consensus:**
- `snow-sample-size` - Sample size for consensus
- `snow-quorum-size` - Quorum size
- `snow-concurrent-repolls` - Concurrent repolls

**Subnets:**
- `track-subnets` - Comma-separated list of subnet IDs to track

**Advanced:**
- `proposervm-use-current-height` - Use current height in proposervm
- `throttler-inbound-validator-alloc-size` - Validator bandwidth allocation
- `consensus-on-accept-gossip-validator-size` - Gossip size

## Subnet Configuration

The `Subnet` type represents a custom subnet.

### Basic Properties

```go
type Subnet struct {
    // User-defined name
    Name string

    // Subnet ID (set after creation)
    SubnetID ids.ID

    // Nodes that validate this subnet
    ValidatorIDs []ids.NodeID

    // Chains on this subnet
    Chains []*Chain

    // Subnet-specific configuration
    Config ConfigMap
}
```

### Subnet Config Options

```go
subnet.Config = tmpnet.ConfigMap{
    // Block proposal delay
    "proposerMinBlockDelay": 0,

    // Historical blocks to keep
    "proposerNumHistoricalBlocks": 50000,

    // Consensus parameters
    "consensusParameters": map[string]interface{}{
        "k":                     20,
        "alpha":                 15,
        "betaVirtuous":          15,
        "betaRogue":             20,
        "concurrentRepolls":     4,
        "optimalProcessing":     10,
        "maxOutstandingItems":   256,
        "maxItemProcessingTime": 120000,
    },
}
```

### Subnet Configuration File

Stored at `[network-dir]/subnets/[subnet-name].json`:

```json
{
  "name": "my-subnet",
  "subnetId": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
  "validatorIds": ["NodeID-..."],
  "config": {
    "proposerMinBlockDelay": 0
  },
  "chains": [...]
}
```

## Chain Configuration

The `Chain` type represents a blockchain on a subnet.

### Basic Properties

```go
type Chain struct {
    // Chain ID (set after creation)
    ChainID ids.ID

    // Virtual Machine ID
    VMID ids.ID

    // Genesis bytes for the chain
    Genesis []byte

    // Chain-specific configuration (JSON string)
    Config string

    // Pre-funded key for the chain
    PreFundedKey *secp256k1.PrivateKey

    // Arguments to get VM version
    VersionArgs []string
}
```

### Chain Configuration Example

```go
chain := &tmpnet.Chain{
    VMID:    myVMID,
    Genesis: genesisBytes,
    Config:  `{
        "blockGasLimit": 8000000,
        "minGasPrice": 25000000000,
        "priorityRegossipFrequency": 1000000000
    }`,
    PreFundedKey: testKey,
    VersionArgs:  []string{"--version"},
}
```

## Directory Structure

Complete directory layout for a tmpnet network:

```
~/.tmpnet/
├── prometheus/                          # Prometheus working directory
│   └── file_sd_configs/
│       └── [network-uuid]-[node-id].json
├── promtail/                            # Promtail working directory
│   └── file_sd_configs/
│       └── [network-uuid]-[node-id].json
└── networks/
    └── [timestamp]/                     # Network directory
        ├── config.json                  # Network configuration
        ├── genesis.json                 # Genesis file
        ├── network.env                  # Shell environment
        ├── metrics.txt                  # Grafana link
        ├── subnets/
        │   └── [subnet-name].json       # Subnet configuration
        └── [node-id]/                   # Node directory
            ├── config.json              # Runtime configuration
            ├── flags.json               # Node flags
            ├── process.json             # Process info
            ├── staking.crt              # Staking certificate
            ├── staking.key              # Staking key
            ├── signer.key               # BLS signing key
            ├── logs/
            │   └── main.log
            ├── db/                      # Node database
            └── plugins/                 # VM plugins
```

## Environment Variables

tmpnet uses these environment variables:

| Variable | Purpose | Default |
|----------|---------|---------|
| `TMPNET_NETWORK_DIR` | Target network directory | None (must specify) |
| `TMPNET_ROOT_NETWORK_DIR` | Root for new networks | `~/.tmpnet/networks` |
| `LUXGO_PATH` | Path to luxgo binary | None (must specify) |
| `AVAGO_PLUGIN_DIR` | Plugin directory | `~/.luxgo/plugins` |
| `STACK_TRACE_ERRORS` | Enable stack traces | Not set |
| `PROMETHEUS_URL` | Prometheus backend URL | None |
| `PROMETHEUS_PUSH_URL` | Prometheus push URL | None |
| `PROMETHEUS_USERNAME` | Prometheus username | None |
| `PROMETHEUS_PASSWORD` | Prometheus password | None |
| `LOKI_URL` | Loki backend URL | None |
| `LOKI_PUSH_URL` | Loki push URL | None |
| `LOKI_USERNAME` | Loki username | None |
| `LOKI_PASSWORD` | Loki password | None |
| `GRAFANA_URI` | Custom Grafana dashboard URI | Default Grafana instance |

## Configuration Precedence

Configuration is applied in this order (later overrides earlier):

1. **tmpnet defaults** - Built-in defaults
2. **Network defaults** - `network.DefaultFlags`
3. **Node-specific** - `node.Flags`
4. **Runtime-generated** - Bootstrap IPs/IDs, genesis content, etc.

Example:

```go
// 1. tmpnet default: log-level = "info"
// 2. Network default:
network.DefaultFlags["log-level"] = "debug"

// 3. Node-specific override:
node.Flags["log-level"] = "trace"

// Final result: node runs with log-level = "trace"
```

## Best Practices

1. **Use defaults for common settings** - Set `network.DefaultFlags` for settings shared by all nodes
2. **Override per-node when needed** - Use `node.Flags` only for node-specific configuration
3. **Use dynamic ports** - Set ports to "0" for automatic allocation
4. **Enable verbose logging during development** - Use "debug" or "trace" log levels
5. **Configure subnet tracking** - Set `track-subnets` for nodes that need to sync subnets
6. **Use environment variables** - Store credentials in environment variables, not in code

## See Also

- [CLI Commands Reference](/docs/tooling/tmpnet/reference/cli-commands)
- [Runtime Environments Guide](/docs/tooling/tmpnet/guides/runtimes)
- [Full README](https://github.com/luxfi/luxgo/blob/master/tests/fixture/tmpnet/README.md)


# Account Management (/docs/tooling/avalanche-sdk/client/accounts)

---
title: Account Management
icon: users
description: Learn how to create and manage accounts in the Lux Client SDK with support for EVM, Exchange-Chain, and Platform-Chain operations.
---

## Overview

Lux accounts work across all three chains—Platform-Chain, Exchange-Chain, and LUExchange-Chain—with a single account. Each account provides both EVM addresses (for LUExchange-Chain) and XP addresses (for X/Platform-Chain), so you can interact with the entire Lux network without managing separate accounts.

## Account Structure

Every Lux account has an EVM account for LUExchange-Chain and an optional XP account for X/Platform-Chain:

```typescript
type LuxAccount = {
  evmAccount: Account; // LUExchange-Chain
  xpAccount?: XPAccount; // X/Platform-Chain
  getEVMAddress: () => Address;
  getXPAddress: (chain?: "X" | "P" | "C", hrp?: string) => XPAddress;
};
```

### Quick Start

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Get addresses for all chains
const evmAddress = account.getEVMAddress(); // 0x742d35Cc...
const xChainAddress = account.getXPAddress("X"); // X-lux1...
const pChainAddress = account.getXPAddress("P"); // P-lux1...
```

## Account Types

### Local Accounts

Local accounts store keys on your machine and sign transactions before broadcasting. Use these for server-side apps, bots, or when you need full control.

- [Private Key Accounts](accounts/local/private-key) - Simple and direct
- [Mnemonic Accounts](accounts/local/mnemonic) - Easy recovery with seed phrases
- [HD Key Accounts](accounts/local/hd-key) - Advanced key derivation

### JSON-RPC Accounts

JSON-RPC accounts use external wallets (MetaMask, Core, etc.) for signing. Perfect for browser-based dApps where users control their own keys.

[Learn more about JSON-RPC accounts →](accounts/json-rpc)

## Working with Accounts

### EVM Account

The `evmAccount` handles all LUExchange-Chain operations—smart contracts, ERC-20 transfers, and standard EVM interactions.

```typescript
const evmAccount = account.evmAccount;
console.log(evmAccount.address); // 0x742d35Cc...
```

### XP Account

The `xpAccount` handles Exchange-Chain and Platform-Chain operations—UTXO transactions, asset transfers, and staking.

```typescript
if (account.xpAccount) {
  const xpAccount = account.xpAccount;
  console.log(xpAccount.publicKey);
}
```

### Getting Addresses

```typescript
// LUExchange-Chain address
const evmAddress = account.getEVMAddress(); // 0x742d35Cc...

// X/Platform-Chain addresses
const xChainAddress = account.getXPAddress("X"); // X-lux1...
const pChainAddress = account.getXPAddress("P"); // P-lux1...

// Network-specific (mainnet vs testnet)
const mainnet = account.getXPAddress("X", "lux");
const testnet = account.getXPAddress("X", "testnet");
```

## Creating Accounts

### Private Key

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");
```

[Private Key Accounts →](accounts/local/private-key)

### Mnemonic

```typescript
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";

const account = mnemonicsToLuxAccount("abandon abandon abandon...");
```

[Mnemonic Accounts →](accounts/local/mnemonic)

### HD Key

```typescript
import { hdKeyToLuxAccount, HDKey } from "@lux-sdk/client/accounts";

const hdKey = HDKey.fromMasterSeed(seed);
const account = hdKeyToLuxAccount(hdKey, { accountIndex: 0 });
```

[HD Key Accounts →](accounts/local/hd-key)

## Address Formats

- **LUExchange-Chain:** `0x...` (Ethereum-compatible)
- **X/Platform-Chain:** `lux1...` or `X-lux1...` / `P-lux1...` (Bech32-encoded)

[Network-Specific Addresses →](accounts/local/addresses)

## Security

<Callout>
  **Never expose private keys or mnemonics in client-side code or commit them to
  version control. Use environment variables.**
</Callout>

```typescript
// ✅ Good
const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);

// ❌ Bad
const account = privateKeyToLuxAccount("0x1234...");
```

## Comparison Table

| Feature           | Private Key | Mnemonic  | HD Key   | JSON-RPC     |
| ----------------- | ----------- | --------- | -------- | ------------ |
| **Ease of Use**   | ⭐⭐⭐⭐⭐  | ⭐⭐⭐⭐  | ⭐⭐⭐   | ⭐⭐⭐⭐⭐   |
| **Recovery**      | ❌          | ✅        | ✅       | ❌           |
| **Multi-Account** | ❌          | ✅        | ✅       | ❌           |
| **Security**      | ⚠️ High     | ✅ High   | ✅ High  | ✅ Very High |
| **Use Case**      | Server/Bots | User Apps | Advanced | User Apps    |

## Next Steps

- [Private Key Accounts](accounts/local/private-key) - Simple and direct
- [Mnemonic Accounts](accounts/local/mnemonic) - Easy recovery
- [HD Key Accounts](accounts/local/hd-key) - Advanced key derivation
- [JSON-RPC Accounts](accounts/json-rpc) - Browser wallet integration
- [Account Utilities](accounts/local/utilities) - Helper functions
- [Wallet Operations](methods/wallet-methods/wallet) - Send transactions


# API Clients (/docs/tooling/avalanche-sdk/client/clients/api-clients)

---
title: API Clients
---

## Overview

API clients provide access to node-level operations. They're included with the main Lux Client and handle administrative tasks, node information, health monitoring, and indexed blockchain queries.

## Accessing from Lux Client

All API clients are available on the main Lux Client:

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

// Admin API - Node configuration and profiling
const admin = client.admin;

// Info API - Node and network information
const info = client.info;

// Health API - Node health monitoring
const health = client.health;

// ProposerVM API - ProposerVM operations per chain
const proposervmPChain = client.proposerVM.pChain;
const proposervmXChain = client.proposerVM.xChain;
const proposervmCChain = client.proposerVM.cChain;

// Index API - Indexed blockchain queries
const indexPChainBlock = client.indexBlock.pChain;
const indexCChainBlock = client.indexBlock.cChain;
const indexXChainBlock = client.indexBlock.xChain;
const indexXChainTx = client.indexTx.xChain;
```

## Admin API Client

Node configuration, aliases, logging, and profiling.

### From Lux Client

```typescript
const admin = client.admin;

// Example: Set logger level
await admin.setLoggerLevel({
  loggerName: "C",
  logLevel: "DEBUG",
});
```

### Create Standalone Client

```typescript
import { createAdminApiClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const adminClient = createAdminApiClient({
  chain: lux,
  transport: {
    type: "http",
    url: "https://api.lux.network/ext/admin",
  },
});

await adminClient.alias({
  endpoint: "bc/X",
  alias: "myAlias",
});
```

[View all Admin API methods →](methods/public-methods/api#admin-api-client)

## Info API Client

Node and network information, statistics, and status.

### From Lux Client

```typescript
const info = client.info;

// Example: Get network info
const networkID = await info.getNetworkID();
const version = await info.getNodeVersion();
```

### Create Standalone Client

```typescript
import { createInfoApiClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const infoClient = createInfoApiClient({
  chain: lux,
  transport: { type: "http" },
});

const networkID = await infoClient.getNetworkID();
const version = await infoClient.getNodeVersion();
```

[View all Info API methods →](methods/public-methods/api#info-api-client)

## Health API Client

Node health monitoring and status checks.

### From Lux Client

```typescript
const health = client.health;

// Example: Check node health
const status = await health.health({});
const isAlive = await health.liveness();
```

### Create Standalone Client

```typescript
import { createHealthApiClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const healthClient = createHealthApiClient({
  chain: lux,
  transport: { type: "http" },
});

const health = await healthClient.health({});
const liveness = await healthClient.liveness();
```

[View all Health API methods →](methods/public-methods/api#health-api-client)

## ProposerVM API Client

ProposerVM operations for each chain.

### From Lux Client

```typescript
// Access ProposerVM for each chain
const proposervmPChain = client.proposerVM.pChain;
const proposervmXChain = client.proposerVM.xChain;
const proposervmCChain = client.proposerVM.cChain;
```

### Create Standalone Client

```typescript
import { createProposervmApiClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

// Platform-Chain ProposerVM
const proposervmPChain = createProposervmApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "proposervmPChain",
});

// Exchange-Chain ProposerVM
const proposervmXChain = createProposervmApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "proposervmXChain",
});

// LUExchange-Chain ProposerVM
const proposervmCChain = createProposervmApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "proposervmCChain",
});

// Example: Get proposed height
const pChainHeight = await proposervmPChain.getProposedHeight();
```

## Index API Clients

Fast indexed queries for blockchain data.

### From Lux Client

```typescript
// Block indexes
const indexPChainBlock = client.indexBlock.pChain;
const indexCChainBlock = client.indexBlock.cChain;
const indexXChainBlock = client.indexBlock.xChain;

// Transaction index
const indexXChainTx = client.indexTx.xChain;

// Example: Get last accepted block
const lastBlock = await indexPChainBlock.getLastAccepted({
  encoding: "hex",
});
```

### Create Standalone Client

```typescript
import { createIndexApiClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

// Platform-Chain block index
const indexPChainBlock = createIndexApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "indexPChainBlock",
});

// LUExchange-Chain block index
const indexCChainBlock = createIndexApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "indexCChainBlock",
});

// Exchange-Chain block index
const indexXChainBlock = createIndexApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "indexXChainBlock",
});

// Exchange-Chain transaction index
const indexXChainTx = createIndexApiClient({
  chain: lux,
  transport: { type: "http" },
  clientType: "indexXChainTx",
});

// Example: Get container by index
const block = await indexPChainBlock.getContainerByIndex({
  index: 12345,
  encoding: "hex",
});
```

[View all Index API methods →](methods/public-methods/api#index-api-clients)

## Quick Examples

### Node Health Check

```typescript
const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const health = await client.health.health({});
const liveness = await client.health.liveness();
console.log("Node healthy:", health.healthy);
```

### Get Node Information

```typescript
const version = await client.info.getNodeVersion();
const networkID = await client.info.getNetworkID();
const nodeID = await client.info.getNodeID();
console.log(`Node ${nodeID.nodeID} v${version} on network ${networkID}`);
```

### Query Indexed Blocks

```typescript
const lastBlock = await client.indexBlock.pChain.getLastAccepted({
  encoding: "hex",
});

const block = await client.indexBlock.cChain.getContainerByIndex({
  index: 12345,
  encoding: "hex",
});
```

## When to Use

- **Admin API**: Node configuration, profiling, logging (requires admin access)
- **Info API**: Node and network information
- **Health API**: Health monitoring and status checks
- **Index API**: Fast indexed queries for blocks and transactions
- **ProposerVM API**: ProposerVM operations per chain

<Callout>
  **Note:** Admin API operations require administrative access and may not be
  available on public endpoints.
</Callout>

## Next Steps

- **[API Methods Reference](methods/public-methods/api)** - Complete method documentation
- **[Lux Client](clients/lux-client)** - Main client operations
- **[Wallet Client](clients/wallet-client)** - Transaction operations


# Lux Client (/docs/tooling/avalanche-sdk/client/clients/avalanche-client)

---
title: Lux Client
---

## Overview

The Lux Client (also known as the Public Client) is the main client for read-only operations across all Lux chains. It provides a unified interface for querying data from Platform-Chain, Exchange-Chain, LUExchange-Chain, and various API endpoints.

**When to use:** Use the Lux Client when you need to query blockchain data but don't need to send transactions.

## Installation & Setup

For setup instructions, see the [Getting Started](/lux-sdk/client-sdk/getting-started) guide.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});
```

## Available Clients

The Lux Client automatically provides access to all chain-specific and API clients:

```typescript
// Chain clients
client.pChain; // Platform-Chain operations (validators, staking, subnets)
client.xChain; // Exchange-Chain operations (assets, UTXOs)
client.cChain; // LUExchange-Chain operations (EVM, atomic transactions)

// API clients
client.admin; // Admin API operations
client.info; // Info API operations
client.health; // Health API operations
client.proposerVM.pChain; // ProposerVM API for P Chain
client.proposerVM.xChain; // ProposerVM API for X Chain
client.proposerVM.cChain; // ProposerVM API for C Chain
client.indexBlock.pChain; // Platform-Chain block index
client.indexBlock.cChain; // LUExchange-Chain block index
client.indexBlock.xChain; // Exchange-Chain block index
client.indexTx.xChain; // Exchange-Chain transaction index
```

## Available Methods

The Lux Client extends viem's Public Client and provides additional Lux-specific methods:

### Lux-Specific Methods

- **Public Methods**: `baseFee`, `getChainConfig`, `maxPriorityFeePerGas`, `feeConfig`, `getActiveRulesAt`

For complete documentation, see [Public Methods Reference](/lux-sdk/client-sdk/methods/public-methods/public).

### Chain-Specific Methods

Access methods through chain clients:

- **Platform-Chain Methods**: See [Platform-Chain Client](/lux-sdk/client-sdk/clients/p-chain-client) and [Platform-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/p-chain)
- **Exchange-Chain Methods**: See [Exchange-Chain Client](/lux-sdk/client-sdk/clients/x-chain-client) and [Exchange-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/x-chain)
- **LUExchange-Chain Methods**: See [LUExchange-Chain Client](/lux-sdk/client-sdk/clients/c-chain-client) and [LUExchange-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/c-chain)

### viem Public Client Methods

The client extends viem's Public Client, providing access to all standard EVM actions:

- `getBalance`, `getBlock`, `getBlockNumber`, `getTransaction`, `getTransactionReceipt`
- `readContract`, `call`, `estimateGas`, `getCode`, `getStorageAt`
- And many more...

See the [viem documentation](https://viem.sh/docs/getting-started) for all available EVM actions.

## Common Operations

### Query Platform-Chain Data

```typescript
// Get current block height
const height = await client.pChain.getHeight();

// Get current validators
const validators = await client.pChain.getCurrentValidators({
  subnetID: "11111111111111111111111111111111LpoYY",
});

// Get subnet information
const subnet = await client.pChain.getSubnet({
  subnetID: "11111111111111111111111111111111LpoYY",
});

// Get balance
const balance = await client.pChain.getBalance({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
});
```

### Query Exchange-Chain Data

```typescript
// Get balance for specific asset
const balance = await client.xChain.getBalance({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
  assetID: "LUX",
});

// Get all balances
const allBalances = await client.xChain.getAllBalances({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
});

// Get asset information
const asset = await client.xChain.getAssetDescription({
  assetID: "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
});
```

### Query LUExchange-Chain Data

```typescript
// Get EVM balance (viem action)
const balance = await client.getBalance({
  address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
});

// Get transaction receipt (viem action)
const receipt = await client.getTransactionReceipt({
  hash: "0x...",
});

// Get base fee (Lux-specific)
const baseFee = await client.baseFee();

// Get chain config
const chainConfig = await client.getChainConfig();

// Get atomic transaction
const atomicTx = await client.cChain.getAtomicTx({
  txID: "2QouvMUbQ6oy7yQ9tLvL3L8tGQG2QK1wJ1q1wJ1q1wJ1q1wJ1q1wJ1q1wJ1",
});
```

### Query API Data

```typescript
// Admin API - Get peers
const peers = await client.admin.getPeers();

// Info API - Get node version
const version = await client.info.getNodeVersion();

// Health API - Get health status
const health = await client.health.health();

// Index API - Get block by index
const block = await client.indexPChainBlock.getContainerByIndex({
  index: 12345,
});
```

## Error Handling

Always handle errors appropriately:

```typescript
import { BaseError } from "viem";

try {
  const balance = await client.getBalance({
    address: "0x...",
  });
} catch (error) {
  if (error instanceof BaseError) {
    console.error("RPC Error:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
}
```

## When to Use This Client

- ✅ Querying blockchain data
- ✅ Reading balances and transaction history
- ✅ Checking validator information
- ✅ Monitoring network status
- ✅ Inspecting smart contract state

**Don't use this client for:**

- ❌ Sending transactions (use [Wallet Client](/lux-sdk/client-sdk/clients/wallet-client))
- ❌ Signing messages (use [Wallet Client](/lux-sdk/client-sdk/clients/wallet-client))
- ❌ Cross-chain transfers (use [Wallet Client](/lux-sdk/client-sdk/clients/wallet-client))

## Best Practices

### Use Specific Clients

```typescript
// Good: Use Platform-Chain client for platform operations
const validators = await client.pChain.getCurrentValidators({});

// Good: Use Exchange-Chain client for asset operations
const balance = await client.xChain.getBalance({
  addresses: ["X-lux..."],
  assetID: "LUX",
});

// Good: Use LUExchange-Chain client for EVM operations
const atomicTx = await client.cChain.getAtomicTx({
  txID: "0x...",
});
```

### Using viem Actions

Since the Lux Client extends viem's Public Client, you have access to all viem actions:

```typescript
// Use viem's readContract action
const result = await client.readContract({
  address: "0x...",
  abi: contractABI,
  functionName: "balanceOf",
  args: ["0x..."],
});

// Use viem's getTransaction action
const tx = await client.getTransaction({
  hash: "0x...",
});

// Use viem's estimateGas action
const gas = await client.estimateGas({
  to: "0x...",
  value: parseEther("0.001"),
});
```

See the [viem documentation](https://viem.sh/docs/getting-started) for all available actions.

## Next Steps

- **[Wallet Client](/lux-sdk/client-sdk/clients/wallet-client)** - Transaction signing and sending
- **[Platform-Chain Client](/lux-sdk/client-sdk/clients/p-chain-client)** - Detailed Platform-Chain operations
- **[Exchange-Chain Client](/lux-sdk/client-sdk/clients/x-chain-client)** - Asset and UTXO operations
- **[LUExchange-Chain Client](/lux-sdk/client-sdk/clients/c-chain-client)** - EVM and atomic operations
- **[Public Methods Reference](/lux-sdk/client-sdk/methods/public-methods/public)** - Complete public method documentation


# LUExchange-Chain Client (/docs/tooling/avalanche-sdk/client/clients/c-chain-client)

---
title: LUExchange-Chain Client
---

## Overview

The LUExchange-Chain (Contract Chain) Client provides an interface for interacting with Lux's Contract Chain, which is an instance of the Ethereum Virtual Machine (EVM) with additional Lux-specific features like cross-chain atomic transactions.

**When to use:** Use the LUExchange-Chain Client for EVM operations and atomic transactions (cross-chain transfers).

## Installation & Setup

For setup instructions, see the [Getting Started](/lux-sdk/client-sdk/getting-started) guide.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const cChainClient = client.cChain;
```

Or create a standalone LUExchange-Chain client:

```typescript
import { createCChainClient } from "@lux-sdk/client";

const cChainClient = createCChainClient({
  chain: lux,
  transport: { type: "http" },
});
```

## Available Methods

The LUExchange-Chain Client provides methods for:

- **Atomic Transaction Operations**: `getAtomicTx`, `getAtomicTxStatus`
- **UTXO Operations**: `getUTXOs`
- **Transaction Operations**: `issueTx`

Additionally, the LUExchange-Chain Client extends viem's Public Client, providing access to all standard EVM actions such as `getBalance`, `getBlock`, `readContract`, `call`, and more.

For complete method documentation with signatures, parameters, and examples, see the [LUExchange-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/c-chain).

## Common Use Cases

### Query Atomic Transactions

```typescript
// Get atomic transaction details
const atomicTx = await client.cChain.getAtomicTx({
  txID: "2QouvMUbQ6oy7yQ9tLvL3L8tGQG2QK1wJ1q1wJ1q1wJ1q1wJ1q1wJ1q1wJ1",
});

console.log("Source chain:", atomicTx.sourceChain);
console.log("Destination chain:", atomicTx.destinationChain);
console.log("Transfers:", atomicTx.transfers);

// Get atomic transaction status
const status = await client.cChain.getAtomicTxStatus({
  txID: "2QouvMUbQ6oy7yQ9tLvL3L8tGQG2QK1wJ1q1wJ1q1wJ1q1wJ1q1wJ1q1wJ1",
});

console.log("Status:", status.status);
```

### Query UTXOs

```typescript
// Get UTXOs for LUExchange-Chain addresses
const utxos = await client.cChain.getUTXOs({
  addresses: ["0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"],
  limit: 100,
});

console.log("Number of UTXOs:", utxos.utxos.length);
```

## Using viem Actions

The LUExchange-Chain Client extends viem's Public Client, so you have access to all standard EVM actions:

```typescript
// Get EVM balance
const balance = await client.getBalance({
  address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
});

// Get transaction receipt
const receipt = await client.getTransactionReceipt({
  hash: "0x...",
});

// Get block number
const blockNumber = await client.getBlockNumber();

// Read smart contract
const result = await client.readContract({
  address: "0x...",
  abi: contractABI,
  functionName: "balanceOf",
  args: ["0x..."],
});

// Get block information
const block = await client.getBlock({
  blockNumber: blockNumber,
});
```

See the [viem documentation](https://viem.sh/docs/getting-started) for all available EVM actions.

## Wallet Operations

For transaction operations (sending transactions, writing contracts), use the wallet client:

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { parseEther } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");
const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Send LUX
const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  value: parseEther("0.001"),
});

console.log("Transaction hash:", txHash);
```

### Cross-Chain Operations

```typescript
// Export from LUExchange-Chain to Platform-Chain
const exportTx = await walletClient.cChain.prepareExportTxn({
  destinationChain: "P",
  to: account.getXPAddress("P"),
  amount: "0.001",
});

const exportTxHash = await walletClient.sendXPTransaction(exportTx);
console.log("Export transaction:", exportTxHash);

// Import to LUExchange-Chain from Platform-Chain
const importTx = await walletClient.cChain.prepareImportTxn({
  to: account.getEVMAddress(),
  amount: "0.001",
  sourceChain: "P",
});

const importTxHash = await walletClient.sendXPTransaction(importTx);
console.log("Import transaction:", importTxHash);
```

For complete wallet operations documentation, see [LUExchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/c-chain-wallet).

## Next Steps

- **[LUExchange-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/c-chain)** - Complete method documentation
- **[LUExchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/c-chain-wallet)** - Transaction preparation and sending
- **[Wallet Client](/lux-sdk/client-sdk/clients/wallet-client)** - Complete wallet operations
- **[Platform-Chain Client](/lux-sdk/client-sdk/clients/p-chain-client)** - Validator operations
- **[Exchange-Chain Client](/lux-sdk/client-sdk/clients/x-chain-client)** - Asset operations


# Clients (/docs/tooling/avalanche-sdk/client/clients)

---
title: Clients
---

## Overview

The SDK provides different client types for interacting with Lux. Each client is optimized for specific use cases.

## Client Architecture

```typescript
Lux Client (Public)
├── Platform-Chain Client
├── Exchange-Chain Client
├── LUExchange-Chain Client
├── Admin API Client
├── Info API Client
├── Health API Client
├── ProposerVM Client
└── Index API Clients

Lux Wallet Client
├── All Public Client Methods
├── Platform-Chain Wallet Operations
├── Exchange-Chain Wallet Operations
├── LUExchange-Chain Wallet Operations
└── ERC20 Token Operations
```

## Client Types

### Main Clients

- **[Lux Client](clients/lux-client)** - Read-only operations for all chains
- **[Lux Wallet Client](clients/wallet-client)** - Transaction signing and sending

### Chain-Specific Clients

- **[Platform-Chain Client](clients/p-chain-client)** - Validator and staking operations
- **[Exchange-Chain Client](clients/x-chain-client)** - Asset transfers and UTXO operations
- **[LUExchange-Chain Client](clients/c-chain-client)** - EVM and atomic transaction operations

### API Clients

- **[Admin API Client](clients/api-clients#admin-api-client)** - Administrative node operations
- **[Info API Client](clients/api-clients#info-api-client)** - Node information and network statistics
- **[Health API Client](clients/api-clients#health-api-client)** - Node health monitoring
- **[ProposerVM Client](clients/api-clients#proposervm-client)** - ProposerVM operations
- **[Index API Clients](clients/api-clients#index-api-clients)** - Indexed blockchain data queries

## Configuration

All clients accept a common configuration:

```typescript
interface LuxClientConfig {
  transport: Transport; // Required: HTTP, WebSocket, or Custom
  chain?: Chain; // Optional: Network configuration
  account?: Account | Address; // Optional: For wallet operations
  apiKey?: string; // Optional: For authenticated endpoints
  rlToken?: string; // Optional: Rate limit token
  key?: string; // Optional: Client key identifier
  name?: string; // Optional: Client name
  pollingInterval?: number; // Optional: Polling interval in ms (default: chain.blockTime / 3)
  cacheTime?: number; // Optional: Cache time in ms (default: chain.blockTime / 3)
  batch?: { multicall?: boolean | MulticallBatchOptions }; // Optional: Batch settings
  ccipRead?:
    | {
        request?: (
          params: CcipRequestParameters
        ) => Promise<CcipRequestReturnType>;
      }
    | false; // Optional: CCIP Read config
  experimental_blockTag?: BlockTag; // Optional: Default block tag (default: 'latest')
  rpcSchema?: RpcSchema; // Optional: Typed JSON-RPC schema
  type?: string; // Optional: Client type
}
```

### Configuration Options

| Option            | Type                 | Required | Default               | Description                                       |
| ----------------- | -------------------- | -------- | --------------------- | ------------------------------------------------- |
| `transport`       | `Transport`          | ✅ Yes   | -                     | Transport configuration (HTTP, WebSocket, Custom) |
| `chain`           | `Chain`              | No       | -                     | Network configuration (mainnet/testnet)           |
| `account`         | `Account \| Address` | No       | -                     | Account for signing operations                    |
| `apiKey`          | `string`             | No       | -                     | API key for authenticated endpoints               |
| `rlToken`         | `string`             | No       | -                     | Rate limit token                                  |
| `key`             | `string`             | No       | -                     | Client key identifier                             |
| `name`            | `string`             | No       | -                     | Client name                                       |
| `pollingInterval` | `number`             | No       | `chain.blockTime / 3` | Polling interval in milliseconds                  |
| `cacheTime`       | `number`             | No       | `chain.blockTime / 3` | Cache time in milliseconds                        |
| `batch`           | `object`             | No       | -                     | Batch settings (multicall configuration)          |
| `ccipRead`        | `object \| false`    | No       | -                     | CCIP Read configuration                           |
| `rpcSchema`       | `RpcSchema`          | No       | -                     | Typed JSON-RPC schema                             |
| `type`            | `string`             | No       | -                     | Client type identifier                            |

## Usage Examples

### Public Client

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

// Read data from all chains
const pHeight = await client.pChain.getHeight();
const balance = await client.getBalance({ address: "0x..." });
```

### Wallet Client

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToWei } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Send transaction
const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
});
```

### Accessing Sub-Clients

```typescript
const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

// Chain clients
client.pChain; // Platform-Chain operations
client.xChain; // Exchange-Chain operations
client.cChain; // LUExchange-Chain operations

// API clients
client.admin; // Admin API
client.info; // Info API
client.health; // Health API
client.proposerVM.pChain; // ProposerVM API for P Chain
client.proposerVM.xChain; // ProposerVM API for X Chain
client.proposerVM.cChain; // ProposerVM API for C Chain
client.indexBlock.pChain; // Platform-Chain block index
client.indexBlock.cChain; // LUExchange-Chain block index
client.indexBlock.xChain; // Exchange-Chain block index
client.indexTx.xChain; // Exchange-Chain transaction index
```

## Next Steps

- **[Lux Client](clients/lux-client)** - Read-only operations
- **[Lux Wallet Client](clients/wallet-client)** - Transaction operations
- **[Chain-Specific Clients](clients/p-chain-client)** - P, X, and LUExchange-Chain clients
- **[API Clients](clients/api-clients)** - Admin, Info, Health, ProposerVM, and Index APIs


# Platform-Chain Client (/docs/tooling/avalanche-sdk/client/clients/p-chain-client)

---
title: Platform-Chain Client
---

## Overview

The Platform-Chain (Platform Chain) Client provides an interface for interacting with Lux's Platform Chain, which is responsible for coordinating validators, managing subnets, creating blockchains, and handling staking operations.

**When to use:** Use the Platform-Chain Client for validator operations, staking, subnet management, and blockchain creation.

## Installation & Setup

For setup instructions, see the [Getting Started](/lux-sdk/client-sdk/getting-started) guide.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const pChainClient = client.pChain;
```

Or create a standalone Platform-Chain client:

```typescript
import { createPChainClient } from "@lux-sdk/client";

const pChainClient = createPChainClient({
  chain: lux,
  transport: { type: "http" },
});
```

## Available Methods

The Platform-Chain Client provides methods for:

- **Balance Operations**: `getBalance`, `getUTXOs`
- **Validator Operations**: `getCurrentValidators`, `getValidatorsAt`, `sampleValidators`, `getL1Validator`
- **Staking Operations**: `getStake`, `getTotalStake`, `getMinStake`
- **Subnet Operations**: `getSubnet`, `getSubnets`, `getStakingAssetID`
- **Blockchain Operations**: `getBlockchains`, `getBlockchainStatus`, `validatedBy`, `validates`
- **Block Operations**: `getHeight`, `getBlock`, `getBlockByHeight`, `getProposedHeight`, `getTimestamp`
- **Transaction Operations**: `getTx`, `getTxStatus`, `issueTx`
- **Fee Operations**: `getFeeConfig`, `getFeeState`
- **Supply Operations**: `getCurrentSupply`
- **Reward Operations**: `getRewardUTXOs`

For complete method documentation with signatures, parameters, and examples, see the [Platform-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/p-chain).

## Common Use Cases

### Query Validators

```typescript
// Get current validators
const validators = await client.pChain.getCurrentValidators({});

console.log("Total validators:", validators.validators.length);

// Get validators at specific height
const validatorsAt = await client.pChain.getValidatorsAt({
  height: 1000001,
  subnetID: "11111111111111111111111111111111LpoYY",
});
```

### Query Staking Information

```typescript
// Get minimum stake requirements
const minStake = await client.pChain.getMinStake({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Min validator stake:", minStake.minValidatorStake);
console.log("Min delegator stake:", minStake.minDelegatorStake);

// Get total stake for a subnet
const totalStake = await client.pChain.getTotalStake({
  subnetID: "11111111111111111111111111111111LpoYY",
});

// Get stake for specific addresses
const stake = await client.pChain.getStake({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
  subnetID: "11111111111111111111111111111111LpoYY",
});
```

### Query Subnet Information

```typescript
// Get subnet information
const subnet = await client.pChain.getSubnet({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Is permissioned:", subnet.isPermissioned);
console.log("Control keys:", subnet.controlKeys);

// Get all blockchains in the network
const blockchains = await client.pChain.getBlockchains();

// Get blockchains validated by a subnet
const validatedBlockchains = await client.pChain.validates({
  subnetID: "11111111111111111111111111111111LpoYY",
});
```

### Query Balance and UTXOs

```typescript
// Get balance for addresses
const balance = await client.pChain.getBalance({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
});

console.log("Total balance:", balance.balance);
console.log("Unlocked:", balance.unlocked);

// Get UTXOs
const utxos = await client.pChain.getUTXOs({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
  limit: 100,
});
```

### Query Fee Information

```typescript
// Get fee configuration
const feeConfig = await client.pChain.getFeeConfig();
console.log("Fee weights:", feeConfig.weights);
console.log("Min price:", feeConfig.minPrice);

// Get current fee state
const feeState = await client.pChain.getFeeState();
console.log("Current fee price:", feeState.price);
console.log("Fee capacity:", feeState.capacity);
```

## Wallet Operations

For transaction operations (preparing and sending transactions), use the wallet client:

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");
const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Prepare and send base transaction
const baseTxn = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: [account.getXPAddress("P")],
      amount: 0.00001,
    },
  ],
});

const txID = await walletClient.sendXPTransaction(baseTxn);
console.log("Transaction sent:", txID);
```

For complete wallet operations documentation, see [Platform-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/p-chain-wallet).

## Next Steps

- **[Platform-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/p-chain)** - Complete method documentation
- **[Platform-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/p-chain-wallet)** - Transaction preparation and signing
- **[Wallet Client](/lux-sdk/client-sdk/clients/wallet-client)** - Complete wallet operations
- **[Exchange-Chain Client](/lux-sdk/client-sdk/clients/x-chain-client)** - Asset transfers
- **[LUExchange-Chain Client](/lux-sdk/client-sdk/clients/c-chain-client)** - EVM operations


# Lux Wallet Client (/docs/tooling/avalanche-sdk/client/clients/wallet-client)

---
title: Lux Wallet Client
---

## Overview

The Lux Wallet Client extends the Public Client with full transaction signing and sending capabilities. It enables cross-chain operations, atomic transactions, and comprehensive wallet management across all Lux chains.

**When to use:** Use the Wallet Client when you need to sign and send transactions, sign messages, or manage accounts.

## Installation & Setup

For setup instructions, see the [Getting Started](/lux-sdk/client-sdk/getting-started) guide.

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account, // Hoist the account, otherwise we can pass a custom provider for injected provider or pass a account for each method
  chain: lux,
  transport: { type: "http" },
});
```

## Available Wallet Operations

The Wallet Client provides access to:

```typescript
// Chain wallet operations
walletClient.pChain; // Platform-Chain wallet operations
walletClient.xChain; // Exchange-Chain wallet operations
walletClient.cChain; // LUExchange-Chain wallet operations

// Core wallet methods
walletClient.send(); // Send transactions
walletClient.sendXPTransaction(); // Send XP transactions
walletClient.signXPMessage(); // Sign XP messages
walletClient.signXPTransaction(); // Sign XP transactions
walletClient.waitForTxn(); // Wait for transaction confirmation
walletClient.getAccountPubKey(); // Get account public key
```

For complete method documentation, see:

- **[Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/wallet)** - Core wallet operations
- **[Platform-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/p-chain-wallet)** - Platform-Chain transactions
- **[Exchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/x-chain-wallet)** - Exchange-Chain transactions
- **[LUExchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/c-chain-wallet)** - LUExchange-Chain transactions

## Common Operations

### Send LUX on LUExchange-Chain

```typescript
import { luxToNanoLux } from "@lux-sdk/client/utils";

const hash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  value: luxToNanoLux(0.001), // 0.001 LUX
});

console.log("Transaction hash:", hash);
```

### Platform-Chain Wallet Operations

```typescript
// Prepare and send base transaction
const baseTxn = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: [account.getXPAddress("P")],
      amount: luxToNanoLux(0.00001),
    },
  ],
});

const txID = await walletClient.sendXPTransaction(baseTxn);
console.log("Platform-Chain transaction:", txID);
```

### Exchange-Chain Wallet Operations

```typescript
// Prepare and send base transaction
const xChainTx = await walletClient.xChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
      amount: luxToNanoLux(1), // 1 LUX
    },
  ],
});

const txID = await walletClient.sendXPTransaction(xChainTx);
console.log("Exchange-Chain transaction:", txID);
```

### Sign Messages

```typescript
// Sign XP message
const signedMessage = await walletClient.signXPMessage({
  message: "Hello Lux",
});

console.log("Signed message:", signedMessage);
```

### Wait for Transaction Confirmation

```typescript
try {
  await walletClient.waitForTxn({
    txID: "0x...",
    chainAlias: "P",
  });
  console.log("Transaction confirmed!");
} catch (error) {
  console.error("chain confirmation failed:", error);
}
```

## When to Use This Client

- ✅ Sending transactions
- ✅ Signing messages and transactions
- ✅ Cross-chain transfers
- ✅ Managing accounts
- ✅ All wallet operations

## Next Steps

- **[Wallet Methods Reference](/lux-sdk/client-sdk/methods/wallet-methods/wallet)** - Complete wallet method documentation
- **[Platform-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/p-chain-wallet)** - Platform-Chain transaction operations
- **[Exchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/x-chain-wallet)** - Exchange-Chain transaction operations
- **[LUExchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/c-chain-wallet)** - LUExchange-Chain transaction operations
- **[Account Management](/lux-sdk/client-sdk/accounts)** - Account types and management


# Exchange-Chain Client (/docs/tooling/avalanche-sdk/client/clients/x-chain-client)

---
title: Exchange-Chain Client
---

## Overview

The Exchange-Chain (Exchange Chain) Client provides an interface for interacting with Lux's Exchange Chain, which handles asset creation, trading, transfers, and UTXO management.

**When to use:** Use the Exchange-Chain Client for asset operations, UTXO management, and Exchange-Chain transaction queries.

## Installation & Setup

For setup instructions, see the [Getting Started](/lux-sdk/client-sdk/getting-started) guide.

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const xChainClient = client.xChain;
```

Or create a standalone Exchange-Chain client:

```typescript
import { createXChainClient } from "@lux-sdk/client";

const xChainClient = createXChainClient({
  chain: lux,
  transport: { type: "http" },
});
```

## Available Methods

The Exchange-Chain Client provides methods for:

- **Balance Operations**: `getBalance`, `getAllBalances`
- **Asset Operations**: `getAssetDescription`, `buildGenesis`
- **UTXO Operations**: `getUTXOs`
- **Block Operations**: `getHeight`, `getBlock`, `getBlockByHeight`
- **Transaction Operations**: `getTx`, `getTxStatus`, `getTxFee`, `issueTx`

For complete method documentation with signatures, parameters, and examples, see the [Exchange-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/x-chain).

## Common Use Cases

### Query Balances

```typescript
// Get balance for specific asset
const balance = await client.xChain.getBalance({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
  assetID: "LUX",
});

console.log("Balance:", balance.balance);

// Get all balances for all assets
const allBalances = await client.xChain.getAllBalances({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
});

console.log("All balances:", allBalances.balances);
```

### Query Asset Information

```typescript
// Get asset description
const asset = await client.xChain.getAssetDescription({
  assetID: "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
});

console.log("Asset name:", asset.name);
console.log("Asset symbol:", asset.symbol);
console.log("Denomination:", asset.denomination);
```

### Query UTXOs

```typescript
// Get UTXOs for address
const utxos = await client.xChain.getUTXOs({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
  sourceChain: "P", // Optional: specify source chain
  limit: 100,
});

console.log("Number of UTXOs:", utxos.utxos.length);

// Paginate through UTXOs if needed
if (utxos.endIndex) {
  const moreUtxos = await client.xChain.getUTXOs({
    addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
    startIndex: utxos.endIndex,
    limit: 100,
  });
}
```

### Query Transaction Information

```typescript
// Get transaction
const tx = await client.xChain.getTx({
  txID: "11111111111111111111111111111111LpoYY",
  encoding: "hex",
});

// Get transaction status
const status = await client.xChain.getTxStatus({
  txID: "11111111111111111111111111111111LpoYY",
});

console.log("Transaction status:", status.status);

// Get transaction fees
const txFee = await client.xChain.getTxFee();
console.log("Transaction fee:", txFee.txFee);
console.log("Create asset fee:", txFee.createAssetTxFee);
```

### Query Block Information

```typescript
// Get current height
const height = await client.xChain.getHeight();
console.log("Current Exchange-Chain height:", height);

// Get block by height
const block = await client.xChain.getBlockByHeight({
  height: Number(height),
  encoding: "hex",
});

// Get block by ID
const blockById = await client.xChain.getBlock({
  blockID: "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
  encoding: "hex",
});
```

## Wallet Operations

For transaction operations (preparing and sending transactions), use the wallet client:

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");
const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Prepare and send base transaction
const baseTxn = await walletClient.xChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
      amount: 1, // 1 LUX
    },
  ],
});

const txID = await walletClient.sendXPTransaction(baseTxn);
console.log("Transaction sent:", txID);
```

For complete wallet operations documentation, see [Exchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/x-chain-wallet).

## Next Steps

- **[Exchange-Chain Methods Reference](/lux-sdk/client-sdk/methods/public-methods/x-chain)** - Complete method documentation
- **[Exchange-Chain Wallet Methods](/lux-sdk/client-sdk/methods/wallet-methods/x-chain-wallet)** - Transaction preparation and signing
- **[Wallet Client](/lux-sdk/client-sdk/clients/wallet-client)** - Complete wallet operations
- **[Platform-Chain Client](/lux-sdk/client-sdk/clients/p-chain-client)** - Validator and staking operations
- **[LUExchange-Chain Client](/lux-sdk/client-sdk/clients/c-chain-client)** - EVM operations


# Utilities (/docs/tooling/avalanche-sdk/client/utils)

---
title: "Utilities"
icon: "tools"
---

## Overview

The Lux SDK provides utility functions for LUX unit conversion, CB58 encoding/decoding, transaction serialization, and UTXO operations. All viem utilities are also re-exported for EVM operations.

<Callout>
  **Note:** All utility functions are synchronous unless marked as `async`.
  Handle errors appropriately when working with blockchain data.
</Callout>

## Importing Utilities

Import utilities from `@lux-sdk/client/utils`:

```typescript
import {
  // LUX conversions
  luxToNanoLux,
  nanoLuxToLux,
  luxToWei,
  weiToLux,
  weiToNanoLux,
  nanoLuxToWei,
  // CB58 encoding
  CB58ToHex,
  hexToCB58,
  // Transaction serialization
  getTxFromBytes,
  getUnsignedTxFromBytes,
  // UTXO operations
  getUtxoFromBytes,
  getUtxosForAddress,
  buildUtxoBytes,
} from "@lux-sdk/client/utils";

// Viem utilities are also available
import { hexToBytes, bytesToHex, isAddress } from "@lux-sdk/client/utils";
```

## LUX Unit Conversion

Lux uses different units for different chains:

- **LUX**: Human-readable unit (1 LUX)
- **nanoLUX (nLUX)**: Smallest unit on Platform-Chain and Exchange-Chain and LUExchange-Chain atomics (1 LUX = 10^9 nLUX)
- **wei**: Used on LUExchange-Chain (1 LUX = 10^18 wei)

### luxToNanoLux

Converts LUX to nanoLUX for Platform-Chain/Exchange-Chain or LUExchange-Chain Atomic operations.

**Function Signature:**

```typescript
function luxToNanoLux(amount: number): bigint;
```

**Parameters:**

| Name     | Type     | Required | Description    |
| -------- | -------- | -------- | -------------- |
| `amount` | `number` | Yes      | Amount in LUX |

**Returns:**

| Type     | Description        |
| -------- | ------------------ |
| `bigint` | Amount in nanoLUX |

**Example:**

```typescript
import { luxToNanoLux } from "@lux-sdk/client/utils";

const nanoLux = luxToNanoLux(1.5);
console.log(nanoLux); // 1500000000n

// Use in Platform-Chain transaction
const tx = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["P-lux1..."],
      amount: Number(nanoLux),
    },
  ],
});
```

### nanoLuxToLux

Converts nanoLUX back to LUX for display purposes.

**Function Signature:**

```typescript
function nanoLuxToLux(amount: bigint): number;
```

**Parameters:**

| Name     | Type     | Required | Description        |
| -------- | -------- | -------- | ------------------ |
| `amount` | `bigint` | Yes      | Amount in nanoLUX |

**Returns:**

| Type     | Description    |
| -------- | -------------- |
| `number` | Amount in LUX |

**Example:**

```typescript
import { nanoLuxToLux } from "@lux-sdk/client/utils";

const balance = await walletClient.pChain.getBalance({
  addresses: ["P-lux1..."],
});

const lux = nanoLuxToLux(BigInt(balance.balance || 0));
console.log(`Balance: ${lux} LUX`);
```

### luxToWei

Converts LUX to wei for LUExchange-Chain operations.

**Function Signature:**

```typescript
function luxToWei(amount: number): bigint;
```

**Parameters:**

| Name     | Type     | Required | Description    |
| -------- | -------- | -------- | -------------- |
| `amount` | `number` | Yes      | Amount in LUX |

**Returns:**

| Type     | Description   |
| -------- | ------------- |
| `bigint` | Amount in wei |

**Example:**

```typescript
import { luxToWei } from "@lux-sdk/client/utils";

const wei = luxToWei(1.5);
console.log(wei); // 1500000000000000000n

// Use in LUExchange-Chain transaction
const txHash = await walletClient.cChain.sendTransaction({
  to: "0x...",
  value: wei,
});
```

### weiToLux

Converts wei back to LUX for display.

**Function Signature:**

```typescript
function weiToLux(amount: bigint): bigint;
```

**Parameters:**

| Name     | Type     | Required | Description   |
| -------- | -------- | -------- | ------------- |
| `amount` | `bigint` | Yes      | Amount in wei |

**Returns:**

| Type     | Description                |
| -------- | -------------------------- |
| `bigint` | Amount in LUX (as bigint) |

**Example:**

```typescript
import { weiToLux } from "@lux-sdk/client/utils";

const balance = await walletClient.cChain.getBalance({
  address: "0x...",
});

const lux = weiToLux(balance);
console.log(`Balance: ${lux} LUX`);
```

### weiToNanoLux

Converts wei to nanoLUX for cross-chain operations.

**Function Signature:**

```typescript
function weiToNanoLux(amount: bigint): bigint;
```

**Parameters:**

| Name     | Type     | Required | Description   |
| -------- | -------- | -------- | ------------- |
| `amount` | `bigint` | Yes      | Amount in wei |

**Returns:**

| Type     | Description        |
| -------- | ------------------ |
| `bigint` | Amount in nanoLUX |

**Example:**

```typescript
import { weiToNanoLux } from "@lux-sdk/client/utils";

const cChainBalance = await walletClient.cChain.getBalance({
  address: "0x...",
});

// Convert to nanoLUX for Platform-Chain transfer
const nanoLux = weiToNanoLux(cChainBalance);
```

### nanoLuxToWei

Converts nanoLUX to wei for cross-chain operations.

**Function Signature:**

```typescript
function nanoLuxToWei(amount: bigint): bigint;
```

**Parameters:**

| Name     | Type     | Required | Description        |
| -------- | -------- | -------- | ------------------ |
| `amount` | `bigint` | Yes      | Amount in nanoLUX |

**Returns:**

| Type     | Description   |
| -------- | ------------- |
| `bigint` | Amount in wei |

**Example:**

```typescript
import { nanoLuxToWei } from "@lux-sdk/client/utils";

const pChainBalance = await walletClient.pChain.getBalance({
  addresses: ["P-lux1..."],
});

// Convert to wei for LUExchange-Chain transfer
const wei = nanoLuxToWei(BigInt(pChainBalance.balance || 0));
```

## CB58 Encoding/Decoding

CB58 is Lux's base58 encoding format used for transaction IDs, asset IDs, and addresses.

### CB58ToHex

Converts CB58-encoded strings to hexadecimal format.

**Function Signature:**

```typescript
function CB58ToHex(cb58: string): Hex;
```

**Parameters:**

| Name   | Type     | Required | Description         |
| ------ | -------- | -------- | ------------------- |
| `cb58` | `string` | Yes      | CB58 encoded string |

**Returns:**

| Type  | Description                         |
| ----- | ----------------------------------- |
| `Hex` | Hexadecimal string with `0x` prefix |

**Example:**

```typescript
import { CB58ToHex } from "@lux-sdk/client/utils";

const txId = "mYxFK3CWs6iMFFaRx4wmVLDUtnktzm2o9Mhg9AG6JSzRijy5V";
const hex = CB58ToHex(txId);
console.log(hex); // 0x...

// Use with hex-based APIs
const tx = await client.pChain.getAtomicTx({ txID: hex });
```

### hexToCB58

Converts hexadecimal strings to CB58 format.

**Function Signature:**

```typescript
function hexToCB58(hex: Hex): string;
```

**Parameters:**

| Name  | Type  | Required | Description                         |
| ----- | ----- | -------- | ----------------------------------- |
| `hex` | `Hex` | Yes      | Hexadecimal string with `0x` prefix |

**Returns:**

| Type     | Description         |
| -------- | ------------------- |
| `string` | CB58 encoded string |

**Example:**

```typescript
import { hexToCB58 } from "@lux-sdk/client/utils";

const hex = "0x1234567890abcdef";
const cb58 = hexToCB58(hex);
console.log(cb58); // CB58 encoded string
```

## Transaction Serialization

### getTxFromBytes

Parses signed transaction bytes to extract the transaction and credentials.

**Function Signature:**

```typescript
function getTxFromBytes(
  txBytes: string,
  chainAlias: "P" | "X" | "C"
): [Common.Transaction, Credential[]];
```

**Parameters:**

| Name         | Type                | Required | Description                     |
| ------------ | ------------------- | -------- | ------------------------------- |
| `txBytes`    | `string`            | Yes      | Transaction bytes as hex string |
| `chainAlias` | `"P" \| "X" \| "C"` | Yes      | Chain alias                     |

**Returns:**

| Type                                 | Description                                        |
| ------------------------------------ | -------------------------------------------------- |
| `[Common.Transaction, Credential[]]` | Tuple containing transaction and credentials array |

**Example:**

```typescript
import { getTxFromBytes } from "@lux-sdk/client/utils";

const txHex = "0x1234567890abcdef...";
const [tx, credentials] = getTxFromBytes(txHex, "P");

console.log("Transaction ID:", tx.getId().toString());
console.log("Signatures:", credentials.length);
```

### getUnsignedTxFromBytes

Parses unsigned transaction bytes to get an unsigned transaction object.

**Function Signature:**

```typescript
function getUnsignedTxFromBytes(
  txBytes: string,
  chainAlias: "P" | "X" | "C"
): UnsignedTx;
```

**Parameters:**

| Name         | Type                | Required | Description                     |
| ------------ | ------------------- | -------- | ------------------------------- |
| `txBytes`    | `string`            | Yes      | Transaction bytes as hex string |
| `chainAlias` | `"P" \| "X" \| "C"` | Yes      | Chain alias                     |

**Returns:**

| Type         | Description                        |
| ------------ | ---------------------------------- |
| `UnsignedTx` | Parsed unsigned transaction object |

**Example:**

```typescript
import { getUnsignedTxFromBytes } from "@lux-sdk/client/utils";

const txHex = "0x1234567890abcdef...";
const unsignedTx = getUnsignedTxFromBytes(txHex, "P");

console.log("Transaction ID:", unsignedTx.txID);
console.log("Transaction bytes:", unsignedTx.toBytes());
```

## UTXO Operations

### getUtxoFromBytes

Parses UTXO bytes to get a UTXO object.

**Function Signature:**

```typescript
function getUtxoFromBytes(
  utxoBytesOrHex: string | Uint8Array,
  chainAlias: "P" | "X" | "C"
): Utxo;
```

**Parameters:**

| Name             | Type                   | Required | Description                            |
| ---------------- | ---------------------- | -------- | -------------------------------------- |
| `utxoBytesOrHex` | `string \| Uint8Array` | Yes      | UTXO bytes as hex string or Uint8Array |
| `chainAlias`     | `"P" \| "X" \| "C"`    | Yes      | Chain alias                            |

**Returns:**

| Type   | Description        |
| ------ | ------------------ |
| `Utxo` | Parsed UTXO object |

**Example:**

```typescript
import { getUtxoFromBytes } from "@lux-sdk/client/utils";

const utxoHex = "0x1234567890abcdef...";
const utxo = getUtxoFromBytes(utxoHex, "P");

console.log("UTXO ID:", utxo.utxoID);
console.log("Asset ID:", utxo.assetID);
console.log("Output:", utxo.output);
```

### getUtxosForAddress

Fetches all UTXOs for a given address on a specific chain. This function handles pagination automatically.

**Function Signature:**

```typescript
function getUtxosForAddress(
  client: LuxWalletCoreClient,
  params: {
    address: string;
    chainAlias: "P" | "X" | "C";
    sourceChain?: string;
  }
): Promise<Utxo[]>;
```

**Parameters:**

| Name     | Type                        | Required | Description                |
| -------- | --------------------------- | -------- | -------------------------- |
| `client` | `LuxWalletCoreClient` | Yes      | The wallet client instance |
| `params` | `object`                    | Yes      | Parameters object          |

**params object:**

| Name          | Type                | Required | Description                             |
| ------------- | ------------------- | -------- | --------------------------------------- |
| `address`     | `string`            | Yes      | Address to query                        |
| `chainAlias`  | `"P" \| "X" \| "C"` | Yes      | Chain alias                             |
| `sourceChain` | `string`            | No       | Source chain ID for import transactions |

**Returns:**

| Type              | Description           |
| ----------------- | --------------------- |
| `Promise<Utxo[]>` | Array of UTXO objects |

**Example:**

```typescript
import { getUtxosForAddress } from "@lux-sdk/client/utils";
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const walletClient = createLuxWalletClient({
  account: myAccount,
  chain: lux,
  transport: { type: "http" },
});

const utxos = await getUtxosForAddress(walletClient, {
  address: "P-lux1...",
  chainAlias: "P",
});

console.log(`Found ${utxos.length} UTXOs`);
```

### buildUtxoBytes

Builds UTXO bytes from parameters. Useful for reconstructing UTXOs or creating test data.

**Function Signature:**

```typescript
function buildUtxoBytes(
  txHash: string,
  outputIndex: number,
  assetId: string,
  amount: string,
  addresses: string[],
  locktime: string,
  threshold: number
): `0x${string}`;
```

**Parameters:**

| Name          | Type       | Required | Description                                 |
| ------------- | ---------- | -------- | ------------------------------------------- |
| `txHash`      | `string`   | Yes      | Transaction hash in CB58 format             |
| `outputIndex` | `number`   | Yes      | Output index in the transaction             |
| `assetId`     | `string`   | Yes      | Asset ID in CB58 format                     |
| `amount`      | `string`   | Yes      | Amount as string                            |
| `addresses`   | `string[]` | Yes      | Array of addresses that can spend this UTXO |
| `locktime`    | `string`   | Yes      | UNIX timestamp locktime in seconds          |
| `threshold`   | `number`   | Yes      | Signature threshold                         |

**Returns:**

| Type                | Description              |
| ------------------- | ------------------------ |
| `` `0x${string}` `` | UTXO bytes as hex string |

**Example:**

```typescript
import { buildUtxoBytes } from "@lux-sdk/client/utils";

const utxoBytes = buildUtxoBytes(
  "mYxFK3CWs6iMFFaRx4wmVLDUtnktzm2o9Mhg9AG6JSzRijy5V",
  0,
  "U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK",
  "111947",
  ["P-testnet1nv6w7m6egkwhkcvz96ze3qmzyk5gt6csqz7ejq"],
  "0",
  1
);

console.log("UTXO bytes:", utxoBytes);
```

## Viem Utilities

The SDK re-exports all utilities from viem for EVM operations. See the [viem utilities documentation](https://viem.sh/docs/utilities) for complete reference.

**Common Categories:**

- **Encoding/Decoding**: `bytesToHex`, `hexToBytes`, `stringToHex`
- **ABI Operations**: `encodeAbiParameters`, `decodeAbiParameters`, `parseAbiItem`
- **Address Operations**: `getAddress`, `isAddress`, `checksumAddress`
- **Number Operations**: `bytesToBigInt`, `hexToNumber`, `numberToHex`
- **Hash Operations**: `keccak256`, `sha256`, `ripemd160`
- **Signature Operations**: `recoverAddress`, `verifyMessage`

## Common Patterns

### Converting Between Units

```typescript
import {
  luxToNanoLux,
  nanoLuxToLux,
  luxToWei,
  weiToLux,
} from "@lux-sdk/client/utils";

// Platform-Chain: LUX → nanoLUX
const nanoLux = luxToNanoLux(1.5);

// LUExchange-Chain: LUX → wei
const wei = luxToWei(1.5);

// Display: nanoLUX → LUX
const lux = nanoLuxToLux(nanoLux);
```

### Working with Transaction IDs

```typescript
import { CB58ToHex, hexToCB58 } from "@lux-sdk/client/utils";

// Convert CB58 to hex for API calls
const txId = "mYxFK3CWs6iMFFaRx4wmVLDUtnktzm2o9Mhg9AG6JSzRijy5V";
const hex = CB58ToHex(txId);

// Convert hex back to CB58 for display
const cb58 = hexToCB58(hex);
```

### Parsing Transactions

```typescript
import { getTxFromBytes } from "@lux-sdk/client/utils";

const txHex = "0x...";
const [tx, credentials] = getTxFromBytes(txHex, "P");

// Access transaction details
const txId = tx.getId().toString();
const numSignatures = credentials.length;
```

## Next Steps

- **[Account Management](accounts)** - Working with accounts
- **[Transaction Signing](methods/wallet-methods/wallet)** - Signing and sending transactions
- **[Chain Clients](clients)** - Chain-specific operations
- **[Viem Documentation](https://viem.sh/docs/utilities)** - Complete viem utilities reference


# Interchain Messaging (/docs/tooling/avalanche-sdk/interchain/icm)

---
title: Interchain Messaging
icon: message-square
---

## Overview

Send arbitrary messages between Lux chains and subnets using the Teleporter protocol. Messages are encoded as strings and delivered cross-chain.

## Create Client

```typescript
import { createICMClient } from "@lux-sdk/interchain";
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { luxTestnet, dispatch } from "@lux-sdk/interchain/chains";

// Setup wallet
const account = privateKeyToLuxAccount("0x...");
const wallet = createLuxWalletClient({
  account,
  chain: luxTestnet,
  transport: { type: "http" },
});

const icm = createICMClient(wallet);
// Or with default chains
const icm = createICMClient(wallet, sourceChain, destinationChain);
```

<Callout type="warn">
  The wallet client's chain configuration must match the `sourceChain` used in
  your interchain operations. For example, if you're sending messages from Testnet
  testnet, ensure your wallet client is configured with the Testnet chain.
  Mismatched chains will result in an "invalid sender" error.
</Callout>

## Methods

<Cards>
  <Card title="sendMsg" href="/lux-sdk/interchain/icm/methods">
    Send a cross-chain message
  </Card>
</Cards>


# Methods (/docs/tooling/avalanche-sdk/interchain/icm/methods)

---
title: Methods
icon: code
---

## sendMsg

Sends a cross-chain message to the specified destination chain.

### Parameters

| Parameter                 | Type                                          | Required | Description                                  |
| ------------------------- | --------------------------------------------- | -------- | -------------------------------------------- |
| `message`                 | `string`                                      | Yes      | Message content to send                      |
| `sourceChain`             | `ChainConfig`                                 | Yes\*    | Source chain configuration                   |
| `destinationChain`        | `ChainConfig`                                 | Yes\*    | Destination chain configuration              |
| `recipientAddress`        | `0x${string}`                                 | No       | Recipient address (defaults to zero address) |
| `feeInfo`                 | `{ feeTokenAddress: string, amount: bigint }` | No       | Fee token and amount                         |
| `requiredGasLimit`        | `bigint`                                      | No       | Gas limit for execution (default: 100000)    |
| `allowedRelayerAddresses` | `string[]`                                    | No       | Allowed relayer addresses                    |

\* Required if not set in client constructor

### Returns

| Type              | Description      |
| ----------------- | ---------------- |
| `Promise<string>` | Transaction hash |

### Example

```typescript
import { createICMClient } from "@lux-sdk/interchain";
import { luxTestnet, dispatch } from "@lux-sdk/interchain/chains";

const icm = createICMClient(wallet);

// Simple message
const hash = await icm.sendMsg({
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  message: "Hello from Lux!",
});

// With options
const hash = await icm.sendMsg({
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  message: "Hello from Lux!",
  recipientAddress: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  feeInfo: {
    feeTokenAddress: "0x0000000000000000000000000000000000000000",
    amount: 0n,
  },
  requiredGasLimit: 200000n,
});
```


# Chain Configuration (/docs/tooling/avalanche-sdk/interchain/chains)

---
title: Chain Configuration
icon: link
---

## Overview

Chain configurations define the blockchain networks for interchain operations. Each chain includes network details and interchain contract addresses.

## Available Chains

### luxTestnet

Lux Testnet testnet configuration.

```typescript
import { luxTestnet } from "@lux-sdk/interchain/chains";
```

### dispatch

Dispatch subnet configuration.

```typescript
import { dispatch } from "@lux-sdk/interchain/chains";
```

## ChainConfig Type

```typescript
interface ChainConfig {
  id: number;
  name: string;
  network: string;
  nativeCurrency: {
    name: string;
    symbol: string;
    decimals: number;
  };
  rpcUrls: {
    default: {
      http: string[];
    };
  };
  blockchainId: string;
  interchainContracts: {
    teleporterRegistry: Address;
    teleporterManager: Address;
  };
}
```

## Using Chains

```typescript
import { createICMClient } from "@lux-sdk/interchain";
import { luxTestnet, dispatch } from "@lux-sdk/interchain/chains";

const icm = createICMClient(wallet, luxTestnet, dispatch);

// Or specify per call
await icm.sendMsg({
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  message: "Hello!",
});
```

## Custom Chains

You can define custom chains for interchain operations by extending the base chain configuration with interchain-specific properties. Custom chains are useful when working with custom subnets or L1 chains that support Teleporter.

### Defining a Custom Chain

Use `defineChain` from `@lux-sdk/client` to create a chain configuration, then cast it to `ChainConfig` to add interchain contract addresses:

```typescript
import { defineChain } from "@lux-sdk/client";
import type { ChainConfig } from "@lux-sdk/interchain/chains";

export const myCustomChain = defineChain({
  id: 12345, // Your chain ID
  name: "My Custom Chain",
  network: "my-custom-chain",
  nativeCurrency: {
    decimals: 18,
    name: "Token",
    symbol: "TKN",
  },
  rpcUrls: {
    default: {
      http: ["https://api.example.com/ext/bc/C/rpc"],
    },
  },
  blockExplorers: {
    default: {
      name: "Explorer",
      url: "https://explorer.example.com",
    },
  },
  // Interchain-specific properties
  blockchainId: "0x...", // Your blockchain ID (hex-encoded)
  interchainContracts: {
    teleporterRegistry: "0x...", // Teleporter registry contract address
    teleporterManager: "0x...", // Teleporter manager contract address
  },
}) as ChainConfig;
```

### Required Properties

| Property              | Type     | Description                                      |
| --------------------- | -------- | ------------------------------------------------ |
| `id`                  | `number` | Unique chain identifier (EVM chain ID)           |
| `name`                | `string` | Human-readable chain name                        |
| `network`             | `string` | Network identifier (used for wallet connections) |
| `nativeCurrency`      | `object` | Native token configuration                       |
| `rpcUrls`             | `object` | RPC endpoint URLs                                |
| `blockchainId`        | `string` | Lux blockchain ID (hex-encoded)            |
| `interchainContracts` | `object` | Teleporter contract addresses                    |

### Interchain Contracts

The `interchainContracts` object must include:

- **`teleporterRegistry`**: Address of the Teleporter registry contract on this chain
- **`teleporterManager`**: Address of the Teleporter manager contract on this chain

These contracts enable cross-chain messaging and token transfers. Ensure they are deployed and configured on your chain before using interchain operations.

### Example: Custom Subnet Chain

```typescript
import { defineChain } from "@lux-sdk/client";
import type { ChainConfig } from "@lux-sdk/interchain/chains";

export const mySubnet = defineChain({
  id: 54321,
  name: "My Subnet",
  network: "my-subnet",
  nativeCurrency: {
    decimals: 18,
    name: "Lux",
    symbol: "LUX",
  },
  rpcUrls: {
    default: {
      http: ["https://subnets.lux.network/mysubnet/mainnet/rpc"],
    },
  },
  blockExplorers: {
    default: {
      name: "Subnet Explorer",
      url: "https://subnets.lux.network/mysubnet",
    },
  },
  blockchainId: "0x1234567890abcdef1234567890abcdef12345678",
  interchainContracts: {
    teleporterRegistry: "0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228",
    teleporterManager: "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf",
  },
}) as ChainConfig;
```

### Using Custom Chains

Once defined, use your custom chain with ICM and ICTT clients:

```typescript
import { createICMClient } from "@lux-sdk/interchain";
import { myCustomChain } from "./chains/myCustomChain";
import { luxTestnet } from "@lux-sdk/interchain/chains";

const icm = createICMClient(wallet, luxTestnet, myCustomChain);

// Send message to custom chain
await icm.sendMsg({
  sourceChain: luxTestnet,
  destinationChain: myCustomChain,
  message: "Hello from Testnet to My Custom Chain!",
});
```

### Tips

- **Blockchain ID**: Use the hex-encoded blockchain ID from your chain's configuration. You can find this in your chain's genesis data or by querying the chain's info API.
- **Contract Addresses**: Ensure Teleporter contracts are deployed on your chain before using interchain operations. Contact your chain operator or refer to your chain's documentation for the correct addresses.
- **RPC URLs**: Provide reliable RPC endpoints. Consider using multiple endpoints for redundancy.
- **Testnet vs Mainnet**: Use the `testnet` property to mark testnet chains, which helps with wallet integrations and explorer links.

For more information on chain configuration, see the [Viem chains documentation](https://viem.sh/docs/chains/introduction).


# Building Warp Messages (/docs/tooling/avalanche-sdk/interchain/warp/building)

---
title: Building Warp Messages
icon: hammer
---

## Building Messages

Build unsigned Warp messages for signing and broadcasting.

## RegisterL1ValidatorMessage

### Methods

| Method       | Parameters                                             | Returns                      | Description       |
| ------------ | ------------------------------------------------------ | ---------------------------- | ----------------- |
| `fromValues` | `nodeID: string, publicKey: string, signature: string` | `RegisterL1ValidatorMessage` | Build from values |
| `toHex`      | -                                                      | `string`                     | Convert to hex    |

### Example

```typescript
import { RegisterL1ValidatorMessage } from "@lux-sdk/interchain/warp";

const msg = RegisterL1ValidatorMessage.fromValues(
  "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
  "0x...",
  "0x..."
);

const hex = msg.toHex();
```

## L1ValidatorWeightMessage

### Methods

| Method       | Parameters                                          | Returns                    | Description       |
| ------------ | --------------------------------------------------- | -------------------------- | ----------------- |
| `fromValues` | `nodeID: string, weight: bigint, startTime: bigint` | `L1ValidatorWeightMessage` | Build from values |
| `toHex`      | -                                                   | `string`                   | Convert to hex    |

### Example

```typescript
import { L1ValidatorWeightMessage } from "@lux-sdk/interchain/warp";

const msg = L1ValidatorWeightMessage.fromValues(
  "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
  4n,
  41n
);

const hex = msg.toHex();
```

## AddressedCall

Build AddressedCall payload from a message.

### Methods

| Method       | Parameters                                | Returns         | Description       |
| ------------ | ----------------------------------------- | --------------- | ----------------- |
| `fromValues` | `sourceAddress: Address, payload: string` | `AddressedCall` | Build from values |
| `toHex`      | -                                         | `string`        | Convert to hex    |

### Example

```typescript
import {
  AddressedCall,
  L1ValidatorWeightMessage,
} from "@lux-sdk/interchain/warp";

const msg = L1ValidatorWeightMessage.fromValues(
  "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
  4n,
  41n
);

const addressedCall = AddressedCall.fromValues(
  "0x35F884853114D298D7aA8607f4e7e0DB52205f07",
  msg.toHex()
);
```

## WarpUnsignedMessage

Build unsigned Warp message from AddressedCall.

### Methods

| Method       | Parameters                                                               | Returns               | Description       |
| ------------ | ------------------------------------------------------------------------ | --------------------- | ----------------- |
| `fromValues` | `networkID: number, sourceChainID: string, addressedCallPayload: string` | `WarpUnsignedMessage` | Build from values |
| `toHex`      | -                                                                        | `string`              | Convert to hex    |

### Example

```typescript
import {
  AddressedCall,
  L1ValidatorWeightMessage,
  WarpUnsignedMessage,
} from "@lux-sdk/interchain/warp";

// Build message
const msg = L1ValidatorWeightMessage.fromValues(
  "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
  4n,
  41n
);

// Build AddressedCall
const addressedCall = AddressedCall.fromValues(
  "0x35F884853114D298D7aA8607f4e7e0DB52205f07",
  msg.toHex()
);

// Build unsigned Warp message
const warpUnsignedMsg = WarpUnsignedMessage.fromValues(
  1,
  "251q44yFiimeVSHaQbBk69TzoeYqKu9VagGtLVqo92LphUxjmR",
  addressedCall.toHex()
);

const hex = warpUnsignedMsg.toHex();
```


# Warp Messages (/docs/tooling/avalanche-sdk/interchain/warp)

---
title: Warp Messages
icon: layers
---

## Overview

Warp messages enable cross-chain communication in Lux. Parse and build Warp protocol messages for validator registration, weight updates, and subnet conversions.

## Supported Message Types

- **RegisterL1ValidatorMessage** - Register L1 validators
- **L1ValidatorWeightMessage** - Update validator weights
- **L1ValidatorRegistrationMessage** - L1 validator registration
- **SubnetToL1ConversionMessage** - Subnet to L1 conversion

## Quick Start

```typescript
import {
  WarpMessage,
  RegisterL1ValidatorMessage,
} from "@lux-sdk/interchain/warp";

// Parse a signed Warp message
const signedWarpMsg = WarpMessage.fromHex(signedWarpMsgHex);

// Parse specific message type
const registerMsg = RegisterL1ValidatorMessage.fromHex(signedWarpMsgHex);
```

## Methods

<Cards>
  <Card title="Parsing" href="/lux-sdk/interchain/warp/parsing">
    Parse Warp messages
  </Card>
  <Card title="Building" href="/lux-sdk/interchain/warp/building">
    Build Warp messages
  </Card>
</Cards>


# Parsing Warp Messages (/docs/tooling/avalanche-sdk/interchain/warp/parsing)

---
title: Parsing Warp Messages
icon: search
---

## WarpMessage

Parse a signed Warp message from hex.

### Methods

| Method    | Parameters    | Returns       | Description               |
| --------- | ------------- | ------------- | ------------------------- |
| `fromHex` | `hex: string` | `WarpMessage` | Parse signed Warp message |

### Example

```typescript
import { WarpMessage } from "@lux-sdk/interchain/warp";

const signedWarpMsgHex = "0x...";
const warpMsg = WarpMessage.fromHex(signedWarpMsgHex);

// Access message properties
console.log(warpMsg.networkID);
console.log(warpMsg.sourceChainID);
console.log(warpMsg.addressedCallPayload);
console.log(warpMsg.signatures);
```

## RegisterL1ValidatorMessage

Parse a Register L1 Validator message.

### Methods

| Method    | Parameters    | Returns                      | Description    |
| --------- | ------------- | ---------------------------- | -------------- |
| `fromHex` | `hex: string` | `RegisterL1ValidatorMessage` | Parse from hex |

### Example

```typescript
import { RegisterL1ValidatorMessage } from "@lux-sdk/interchain/warp";

const msg = RegisterL1ValidatorMessage.fromHex(signedWarpMsgHex);
console.log(msg.nodeID);
console.log(msg.publicKey);
console.log(msg.signature);
```

## L1ValidatorWeightMessage

Parse an L1 Validator Weight message.

### Methods

| Method    | Parameters    | Returns                    | Description    |
| --------- | ------------- | -------------------------- | -------------- |
| `fromHex` | `hex: string` | `L1ValidatorWeightMessage` | Parse from hex |

### Example

```typescript
import { L1ValidatorWeightMessage } from "@lux-sdk/interchain/warp";

const msg = L1ValidatorWeightMessage.fromHex(signedWarpMsgHex);
console.log(msg.nodeID);
console.log(msg.weight);
console.log(msg.startTime);
```

## L1ValidatorRegistrationMessage

Parse an L1 Validator Registration message.

### Methods

| Method    | Parameters    | Returns                          | Description    |
| --------- | ------------- | -------------------------------- | -------------- |
| `fromHex` | `hex: string` | `L1ValidatorRegistrationMessage` | Parse from hex |

## SubnetToL1ConversionMessage

Parse a Subnet to L1 Conversion message.

### Methods

| Method    | Parameters    | Returns                       | Description    |
| --------- | ------------- | ----------------------------- | -------------- |
| `fromHex` | `hex: string` | `SubnetToL1ConversionMessage` | Parse from hex |

### Example

```typescript
import { SubnetToL1ConversionMessage } from "@lux-sdk/interchain/warp";

const msg = SubnetToL1ConversionMessage.fromHex(signedWarpMsgHex);
console.log(msg.subnetID);
console.log(msg.assetID);
console.log(msg.initialSupply);
```


# Deployment Methods (/docs/tooling/avalanche-sdk/interchain/ictt/deployment)

---
title: Deployment Methods
icon: package
---

## deployERC20Token

Deploys a new ERC20 token on the source chain.

### Parameters

| Parameter       | Type           | Required | Description                                              |
| --------------- | -------------- | -------- | -------------------------------------------------------- |
| `walletClient`  | `WalletClient` | Yes      | Wallet client for signing                                |
| `sourceChain`   | `ChainConfig`  | Yes\*    | Source chain configuration                               |
| `name`          | `string`       | Yes      | Token name                                               |
| `symbol`        | `string`       | Yes      | Token symbol                                             |
| `initialSupply` | `number`       | Yes      | Initial token supply                                     |
| `recipient`     | `Address`      | No       | Recipient of initial supply (defaults to wallet address) |

\* Required if not set in client constructor

### Returns

| Type                                                             | Description                           |
| ---------------------------------------------------------------- | ------------------------------------- |
| `Promise<{ txHash: 0x${string}, contractAddress: 0x${string} }>` | Transaction hash and contract address |

### Example

```typescript
const { txHash, contractAddress } = await ictt.deployERC20Token({
  walletClient: wallet,
  sourceChain: luxTestnet,
  name: "My Token",
  symbol: "MTK",
  initialSupply: 1000000,
});
```

## deployTokenHomeContract

Deploys a token home contract on the source chain.

### Parameters

| Parameter                  | Type           | Required | Description                |
| -------------------------- | -------------- | -------- | -------------------------- |
| `walletClient`             | `WalletClient` | Yes      | Wallet client for signing  |
| `sourceChain`              | `ChainConfig`  | Yes\*    | Source chain configuration |
| `erc20TokenAddress`        | `Address`      | Yes      | ERC20 token address        |
| `minimumTeleporterVersion` | `number`       | Yes      | Minimum Teleporter version |
| `tokenHomeCustomByteCode`  | `string`       | No       | Custom bytecode            |
| `tokenHomeCustomABI`       | `ABI`          | No       | Custom ABI                 |

### Returns

| Type                                                             | Description                           |
| ---------------------------------------------------------------- | ------------------------------------- |
| `Promise<{ txHash: 0x${string}, contractAddress: 0x${string} }>` | Transaction hash and contract address |

### Example

```typescript
const { txHash, contractAddress } = await ictt.deployTokenHomeContract({
  walletClient: wallet,
  sourceChain: luxTestnet,
  erc20TokenAddress: tokenAddress,
  minimumTeleporterVersion: 1,
});
```

## deployTokenRemoteContract

Deploys a token remote contract on the destination chain.

### Parameters

| Parameter                   | Type           | Required | Description                     |
| --------------------------- | -------------- | -------- | ------------------------------- |
| `walletClient`              | `WalletClient` | Yes      | Wallet client for signing       |
| `sourceChain`               | `ChainConfig`  | Yes\*    | Source chain configuration      |
| `destinationChain`          | `ChainConfig`  | Yes\*    | Destination chain configuration |
| `tokenHomeContract`         | `Address`      | Yes      | Token home contract address     |
| `tokenRemoteCustomByteCode` | `string`       | No       | Custom bytecode                 |
| `tokenRemoteCustomABI`      | `ABI`          | No       | Custom ABI                      |

### Returns

| Type                                                             | Description                           |
| ---------------------------------------------------------------- | ------------------------------------- |
| `Promise<{ txHash: 0x${string}, contractAddress: 0x${string} }>` | Transaction hash and contract address |

### Example

```typescript
const { txHash, contractAddress } = await ictt.deployTokenRemoteContract({
  walletClient: wallet,
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  tokenHomeContract: tokenHomeAddress,
});
```

## registerRemoteWithHome

Registers the token remote contract with the token home contract.

### Parameters

| Parameter             | Type           | Required | Description                     |
| --------------------- | -------------- | -------- | ------------------------------- |
| `walletClient`        | `WalletClient` | Yes      | Wallet client for signing       |
| `sourceChain`         | `ChainConfig`  | Yes\*    | Source chain configuration      |
| `destinationChain`    | `ChainConfig`  | Yes\*    | Destination chain configuration |
| `tokenRemoteContract` | `Address`      | Yes      | Token remote contract address   |
| `feeTokenAddress`     | `Address`      | No       | Fee token address               |
| `feeAmount`           | `number`       | No       | Fee amount                      |

### Returns

| Type                               | Description      |
| ---------------------------------- | ---------------- |
| `Promise<{ txHash: 0x${string} }>` | Transaction hash |

### Example

```typescript
const { txHash } = await ictt.registerRemoteWithHome({
  walletClient: wallet,
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  tokenRemoteContract: tokenRemoteAddress,
});
```


# Interchain Token Transfers (/docs/tooling/avalanche-sdk/interchain/ictt)

---
title: Interchain Token Transfers
icon: coins
---

## Overview

Transfer ERC20 tokens between Lux chains using the Teleporter protocol. Requires deploying token home and remote contracts for each token pair.

## Create Client

```typescript
import { createICTTClient } from "@lux-sdk/interchain";

const ictt = createICTTClient();
// Or with default chains
const ictt = createICTTClient(sourceChain, destinationChain);
```

## Workflow

1. **Deploy ERC20 Token** - Deploy your token on the source chain
2. **Deploy Token Home** - Deploy home contract on source chain
3. **Deploy Token Remote** - Deploy remote contract on destination chain
4. **Register Remote** - Register remote with home contract
5. **Approve Token** - Approve home contract to spend tokens
6. **Send Tokens** - Transfer tokens cross-chain

<Callout type="warn">
  The wallet client's chain configuration must match the `sourceChain` used in
  your interchain operations. For example, if you're sending messages from Testnet
  testnet, ensure your wallet client is configured with the Testnet chain.
  Mismatched chains will result in an "invalid sender" error.
</Callout>

## Methods

<Cards>
  <Card title="Deployment" href="/lux-sdk/interchain/ictt/deployment">
    Deploy tokens and contracts
  </Card>
  <Card title="Transfers" href="/lux-sdk/interchain/ictt/transfers">
    Transfer tokens cross-chain
  </Card>
</Cards>


# Transfer Methods (/docs/tooling/avalanche-sdk/interchain/ictt/transfers)

---
title: Transfer Methods
icon: arrow-right
---

## approveToken

Approves the token home contract to spend tokens on the source chain.

### Parameters

| Parameter           | Type           | Required | Description                       |
| ------------------- | -------------- | -------- | --------------------------------- |
| `walletClient`      | `WalletClient` | Yes      | Wallet client for signing         |
| `sourceChain`       | `ChainConfig`  | Yes\*    | Source chain configuration        |
| `tokenHomeContract` | `Address`      | Yes      | Token home contract address       |
| `tokenAddress`      | `Address`      | Yes      | ERC20 token address               |
| `amountInBaseUnit`  | `number`       | Yes      | Amount to approve (in base units) |

\* Required if not set in client constructor

### Returns

| Type                               | Description      |
| ---------------------------------- | ---------------- |
| `Promise<{ txHash: 0x${string} }>` | Transaction hash |

### Example

```typescript
const { txHash } = await ictt.approveToken({
  walletClient: wallet,
  sourceChain: luxTestnet,
  tokenHomeContract: tokenHomeAddress,
  tokenAddress: tokenAddress,
  amountInBaseUnit: 1000,
});
```

## sendToken

Sends tokens from the source chain to the destination chain.

### Parameters

| Parameter             | Type           | Required | Description                            |
| --------------------- | -------------- | -------- | -------------------------------------- |
| `walletClient`        | `WalletClient` | Yes      | Wallet client for signing              |
| `sourceChain`         | `ChainConfig`  | Yes\*    | Source chain configuration             |
| `destinationChain`    | `ChainConfig`  | Yes\*    | Destination chain configuration        |
| `tokenHomeContract`   | `Address`      | Yes      | Token home contract address            |
| `tokenRemoteContract` | `Address`      | Yes      | Token remote contract address          |
| `recipient`           | `Address`      | Yes      | Recipient address on destination chain |
| `amountInBaseUnit`    | `number`       | Yes      | Amount to send (in base units)         |
| `feeTokenAddress`     | `Address`      | No       | Fee token address                      |
| `feeAmount`           | `number`       | No       | Fee amount                             |

\* Required if not set in client constructor

### Returns

| Type                               | Description      |
| ---------------------------------- | ---------------- |
| `Promise<{ txHash: 0x${string} }>` | Transaction hash |

### Example

```typescript
const { txHash } = await ictt.sendToken({
  walletClient: wallet,
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  tokenHomeContract: tokenHomeAddress,
  tokenRemoteContract: tokenRemoteAddress,
  recipient: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amountInBaseUnit: 100,
});
```

## Complete Workflow

```typescript
import { createICTTClient } from "@lux-sdk/interchain";
import { luxTestnet, dispatch } from "@lux-sdk/interchain/chains";

const ictt = createICTTClient(luxTestnet, dispatch);

// 1. Deploy token
const { contractAddress: tokenAddress } = await ictt.deployERC20Token({
  walletClient: wallet,
  sourceChain: luxTestnet,
  name: "My Token",
  symbol: "MTK",
  initialSupply: 1000000,
});

// 2. Deploy home contract
const { contractAddress: tokenHomeAddress } =
  await ictt.deployTokenHomeContract({
    walletClient: wallet,
    sourceChain: luxTestnet,
    erc20TokenAddress: tokenAddress,
    minimumTeleporterVersion: 1,
  });

// 3. Deploy remote contract
const { contractAddress: tokenRemoteAddress } =
  await ictt.deployTokenRemoteContract({
    walletClient: wallet,
    sourceChain: luxTestnet,
    destinationChain: dispatch,
    tokenHomeContract: tokenHomeAddress,
  });

// 4. Register remote with home
await ictt.registerRemoteWithHome({
  walletClient: wallet,
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  tokenRemoteContract: tokenRemoteAddress,
});

// 5. Approve tokens
await ictt.approveToken({
  walletClient: wallet,
  sourceChain: luxTestnet,
  tokenHomeContract: tokenHomeAddress,
  tokenAddress: tokenAddress,
  amountInBaseUnit: 1000,
});

// 6. Send tokens
const { txHash } = await ictt.sendToken({
  walletClient: wallet,
  sourceChain: luxTestnet,
  destinationChain: dispatch,
  tokenHomeContract: tokenHomeAddress,
  tokenRemoteContract: tokenRemoteAddress,
  recipient: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amountInBaseUnit: 100,
});
```


# Network-Specific Addresses (/docs/tooling/avalanche-sdk/client/accounts/local/addresses)

---
title: "Network-Specific Addresses"
icon: "map-pin"
---

## Overview

Lux uses different address formats for each chain. EVM addresses work the same across networks, but XP addresses use network-specific HRPs (Human-Readable Prefixes).

## Address Formats

### EVM Addresses (LUExchange-Chain)

EVM addresses are the same across all networks:

```typescript
const evmAddress = account.getEVMAddress(); // 0x742d35Cc...
```

### XP Addresses (X/Platform-Chain)

XP addresses use network-specific HRPs:

```typescript
// Mainnet
const mainnetX = account.getXPAddress("X", "lux"); // X-lux1...
const mainnetP = account.getXPAddress("P", "lux"); // P-lux1...

// Testnet (Testnet)
const testnetX = account.getXPAddress("X", "testnet"); // X-testnet1...
const testnetP = account.getXPAddress("P", "testnet"); // P-testnet1...
```

## Network Configuration

```typescript
// Mainnet addresses
const mainnet = {
  evm: account.getEVMAddress(),
  xChain: account.getXPAddress("X", "lux"),
  pChain: account.getXPAddress("P", "lux"),
};

// Testnet addresses
const testnet = {
  evm: account.getEVMAddress(),
  xChain: account.getXPAddress("X", "testnet"),
  pChain: account.getXPAddress("P", "testnet"),
};
```

## Next Steps

- **[Account Utilities](accounts/local/utilities)** - Account validation and utilities
- **[Using Accounts with Clients](accounts/local/clients)** - Client integration patterns


# Using Accounts with Clients (/docs/tooling/avalanche-sdk/client/accounts/local/clients)

---
title: "Using Accounts with Clients"
icon: "link"
---

## Overview

Accounts work with both public clients (read-only) and wallet clients (transactions). You can hoist the account into the client or pass it to each method.

## Public Client (Read-Only)

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const account = privateKeyToLuxAccount("0x...");

// Read operations
const balance = await client.getBalance({ address: account.getEVMAddress() });
const height = await client.pChain.getHeight();
```

## Wallet Client (Transactions)

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { luxToWei } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

// Hoist account (recommended)
const walletClient = createLuxWalletClient({
  account, // Account is hoisted
  chain: lux,
  transport: { type: "http" },
});

// LUExchange-Chain transaction
const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
});

// X/Platform-Chain transaction
const xpTx = await walletClient.xChain.prepareBaseTxn({
  outputs: [{ addresses: [account.getXPAddress("X")], amount: 1 }],
});
await walletClient.sendXPTransaction(xpTx);
```

## Account Hoisting

You can hoist the account into the client (recommended) or pass it to each method:

```typescript
// Hoisted (recommended)
const walletClient = createLuxWalletClient({
  account, // No need to pass to each method
  chain: lux,
  transport: { type: "http" },
});
await walletClient.send({ to: "0x...", amount: 0.001 });

// Or pass per method
const walletClient = createLuxWalletClient({
  chain: lux,
  transport: { type: "http" },
});
await walletClient.send({ account, to: "0x...", amount: 0.001 });
```

## Cross-Chain Operations

Cross-chain transfers use the export/import pattern. Export from the source chain, wait for confirmation, then import to the destination chain.

[Learn more about cross-chain transfers →](methods/wallet-methods/wallet#cross-chain-transfers)

## Next Steps

- **[Wallet Operations](methods/wallet-methods/wallet)** - Learn how to send transactions
- **[Platform-Chain Operations](methods/public-methods/p-chain)** - Validator and staking operations
- **[Exchange-Chain Operations](methods/public-methods/x-chain)** - Asset transfers and UTXO operations
- **[LUExchange-Chain Operations](methods/public-methods/c-chain)** - EVM and smart contract operations


# HD Key Accounts (/docs/tooling/avalanche-sdk/client/accounts/local/hd-key)

---
title: "HD Key Accounts"
icon: "tree"
---

## Overview

HD Key Accounts create Lux accounts from hierarchical deterministic (HD) keys with custom derivation paths. This allows for advanced key management and multiple account generation from a single seed.

## Creating HD Key Accounts

### Basic Usage

```typescript
import { hdKeyToLuxAccount, HDKey } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const seed: Uint8Array = new Uint8Array(64); // Your seed
const hdKey: HDKey = HDKey.fromMasterSeed(seed);

const account: LuxAccount = hdKeyToLuxAccount(hdKey);
```

### Parameters

- **`hdKey: HDKey`** - The HD key instance (required)
- **`options?: HDKeyToLuxAccountOptions`** - Custom derivation path options (optional)

### Options

```typescript
interface HDKeyToLuxAccountOptions {
  accountIndex?: number; // Account index (default: 0)
  addressIndex?: number; // Address index (default: 0)
  changeIndex?: number; // Change index (default: 0)
  xpAccountIndex?: number; // XP account index (default: 0)
  xpAddressIndex?: number; // XP address index (default: 0)
  xpChangeIndex?: number; // XP change index (default: 0)
  path?: string; // Custom derivation path for EVM Account
  xpPath?: string; // Custom derivation path for XP Account
}
```

## Derivation Paths

### Default Derivation Paths

HD Key accounts use BIP-44 derivation paths to generate deterministic keys from a seed. By default, the SDK uses separate paths for EVM (LUExchange-Chain) and XP (X/Platform-Chain) accounts:

**EVM (LUExchange-Chain) Path:**

```
m/44'/60'/{accountIndex}'/{changeIndex}/{addressIndex}
```

**XP (X/Platform-Chain) Path:**

```
m/44'/60'/{xpAccountIndex}'/{xpChangeIndex}/{xpAddressIndex}
```

**Path Components:**

- `m` - Master key
- `44'` - BIP-44 purpose (hardened)
- `60'` - Coin type (hardened)
  - `60` is the standard Ethereum coin type (used for all Lux chains)
- `{accountIndex}'` - Account index (hardened, default: 0)
- `{changeIndex}` - Change index (default: 0)
  - `0` is typically used for external addresses
  - `1` is typically used for change addresses
- `{addressIndex}` - Address index (default: 0)

**Default Values:**
When no options are provided, both paths default to `m/44'/60'/0'/0/0` (EVM) and `m/44'/60'/0'/0/0` (XP).

### How Index Options Affect Paths

The following table shows how different index combinations affect the derivation paths:

| Option                             | EVM Path           | XP Path              | Notes                           |
| ---------------------------------- | ------------------ | -------------------- | ------------------------------- |
| Default (no options)               | `m/44'/60'/0'/0/0` | `m/44'/60'/0'/0/0` | Both use index 0                |
| `accountIndex: 1`                  | `m/44'/60'/1'/0/0` | `m/44'/60'/1'/0/0` | Both use account index 1        |
| `addressIndex: 2`                  | `m/44'/60'/0'/0/2` | `m/44'/60'/0'/0/2` | Both use address index 2        |
| `changeIndex: 1`                   | `m/44'/60'/0'/1/0` | `m/44'/60'/0'/1/0` | Both use change index 1         |
| `accountIndex: 1, addressIndex: 2` | `m/44'/60'/1'/0/2` | `m/44'/60'/1'/0/2` | Combined indices                |
| `xpAccountIndex: 2`                | `m/44'/60'/0'/0/0` | `m/44'/60'/2'/0/0` | XP uses different account index |
| `xpAddressIndex: 3`                | `m/44'/60'/0'/0/0` | `m/44'/60'/0'/0/3` | XP uses different address index |
| `xpChangeIndex: 1`                 | `m/44'/60'/0'/0/0` | `m/44'/60'/0'/1/0` | XP uses different change index  |

**Important Notes:**

- When you specify `accountIndex`, `addressIndex`, or `changeIndex`, they apply to EVM path.
- XP-specific options (`xpAccountIndex`, `xpAddressIndex`, `xpChangeIndex`) only affect the XP path, allowing you to use different indices for XP accounts while keeping EVM indices separate.

### Custom Path Override

<Callout type="warning">
  **Important Limitation**: When the `path` or `xpPath` option is provided, it
  overrides the EVM or XP derivation paths.
</Callout>

When you provide a custom `path` or `xpPath`, it completely replaces the default path calculation for EVM and XP accounts:

```typescript
import { hdKeyToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

// ⚠️ WARNING: This path will be used for EVM accounts
const account: LuxAccount = hdKeyToLuxAccount(hdKey, {
  path: "m/44'/60'/0'/0/0", // EVM will use this path
});

// ⚠️ WARNING: This path will be used for XP accounts
const account: LuxAccount = hdKeyToLuxAccount(hdKey, {
  xpPath: "m/44'/60'/0'/0/0", // XP Account will use this path
});

// The following options are IGNORED when path is provided:
// accountIndex, addressIndex, changeIndex
// xpAccountIndex, xpAddressIndex, xpChangeIndex
```

**When to Use Custom Paths:**

- When you need to match a specific wallet's derivation path
- When migrating from another wallet implementation
- When you need full control over the derivation path

**When NOT to Use Custom Paths:**

- When you want different paths for EVM and XP accounts (use index options instead)
- When you want to leverage the default BIP-44 compliant paths
- In most standard use cases

### Examples

```typescript
import { hdKeyToLuxAccount, HDKey } from "@lux-sdk/client/accounts";

const hdKey = HDKey.fromMasterSeed(seed);

// Default paths (EVM: m/44'/60'/0'/0/0, XP: m/44'/60'/0'/0/0)
const account = hdKeyToLuxAccount(hdKey);

// Different indices
const account1 = hdKeyToLuxAccount(hdKey, { accountIndex: 1 });
const account2 = hdKeyToLuxAccount(hdKey, { addressIndex: 1 });

// Separate EVM and XP indices
const account3 = hdKeyToLuxAccount(hdKey, {
  accountIndex: 0, // EVM
  xpAccountIndex: 2, // XP
});

// Custom path (⚠️ applies to both EVM and XP)
const account4 = hdKeyToLuxAccount(hdKey, {
  path: "m/44'/60'/0'/0/0",
});
```

## Multiple Accounts

Generate multiple accounts from the same HD key:

```typescript
import { hdKeyToLuxAccount, HDKey } from "@lux-sdk/client/accounts";

const hdKey = HDKey.fromMasterSeed(seed);

const account1 = hdKeyToLuxAccount(hdKey, { addressIndex: 0 });
const account2 = hdKeyToLuxAccount(hdKey, { addressIndex: 1 });
const account3 = hdKeyToLuxAccount(hdKey, { addressIndex: 2 });
```

## Using with Wallet Client

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
});
```

## Security

<Callout>
  **Never expose seeds in client-side code or commit them to version control.
  Use environment variables.**
</Callout>

```typescript
// ✅ Good
const seed = new Uint8Array(Buffer.from(process.env.SEED!, "hex"));
const hdKey = HDKey.fromMasterSeed(seed);

// ❌ Bad
const seed = new Uint8Array(64); // Hardcoded seed
```

## Next Steps

- **[Account Utilities](utilities)** - Account validation and utilities
- **[Using Accounts with Clients](clients)** - Client integration patterns


# Local Accounts (/docs/tooling/avalanche-sdk/client/accounts/local)

---
title: Local Accounts
icon: shield
description: Learn how to create and manage local accounts in the Lux Client SDK with private keys, mnemonics, and HD keys.
---

## Overview

Local accounts store keys on your machine and sign transactions before broadcasting. Use these for server-side apps, bots, or when you need full control.

<Callout>
  **Security:** Never expose private keys or mnemonics in client-side code or
  commit them to version control. Use environment variables.
</Callout>

## Quick Start

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);

console.log(account.getEVMAddress()); // 0x742d35Cc...
console.log(account.getXPAddress("X")); // X-lux1...
```

## Account Types

### Private Key

Simplest option—create an account directly from a private key.

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");
```

[Private Key Accounts →](local/private-key)

### Mnemonic

User-friendly option—create an account from a seed phrase.

```typescript
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";

const account = mnemonicsToLuxAccount("abandon abandon abandon...");
```

[Mnemonic Accounts →](local/mnemonic)

### HD Key

Advanced option—create accounts from HD keys with custom derivation paths.

```typescript
import { hdKeyToLuxAccount, HDKey } from "@lux-sdk/client/accounts";

const hdKey = HDKey.fromMasterSeed(seed);
const account = hdKeyToLuxAccount(hdKey, { accountIndex: 0 });
```

[HD Key Accounts →](local/hd-key)

## Instantiation

### Setup Wallet Client

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { luxToWei } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);

const walletClient = createLuxWalletClient({
  account, // Hoist account to avoid passing it to each method
  chain: lux,
  transport: { type: "http" },
});

// Use wallet methods
const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
});

// Use public methods
const balance = await walletClient.getBalance({
  address: account.getEVMAddress(),
});
```

## Account Generation

### Generate Private Key

```typescript
import {
  generatePrivateKey,
  privateKeyToLuxAccount,
} from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const privateKey: string = generatePrivateKey();
const account: LuxAccount = privateKeyToLuxAccount(privateKey);
```

### Generate Mnemonic

```typescript
import {
  generateMnemonic,
  mnemonicsToLuxAccount,
} from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const mnemonic: string = generateMnemonic();
const account: LuxAccount = mnemonicsToLuxAccount(mnemonic);
```

## Address Management

### Get All Addresses

```typescript
const addresses = {
  evm: account.getEVMAddress(),
  xChain: account.getXPAddress("X"),
  pChain: account.getXPAddress("P"),
};

console.log("EVM Address:", addresses.evm);
console.log("Exchange-Chain Address:", addresses.xChain);
console.log("Platform-Chain Address:", addresses.pChain);
```

<Callout>
  **Learn more:** For network-specific addresses and detailed address management
  examples, see [Network-Specific Addresses](local/addresses).
</Callout>

## Security

<Callout>
  **Never expose private keys or mnemonics in client-side code or commit them to
  version control. Always use environment variables.**
</Callout>

```typescript
// ✅ Good: Use environment variables
const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);

// ❌ Bad: Hardcoded private key
const account = privateKeyToLuxAccount("0x1234...");
```

## Learn More

- [Account Generation](#account-generation) - Create secure accounts
- [Address Management](#address-management) - Multi-network addresses
- [Using with Clients](local/clients) - Client integration
- [HD Key Accounts](local/hd-key) - Hierarchical deterministic accounts
- [Account Utilities](local/utilities) - Validation and helpers
- [Network-Specific Addresses](local/addresses) - Advanced address management


# Mnemonic Accounts (/docs/tooling/avalanche-sdk/client/accounts/local/mnemonic)

---
title: "Mnemonic Accounts"
icon: "seedling"
---

## Overview

Mnemonic Accounts create Lux accounts from mnemonic phrases (seed words). Mnemonics provide a human-readable way to backup and restore accounts, making them ideal for user-facing applications.

**Best for:**

- User-facing applications
- Mobile wallets
- Desktop wallets
- Applications requiring easy account recovery

## Creating Mnemonic Accounts

### Basic Usage

```typescript
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const mnemonic =
  "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
const account: LuxAccount = mnemonicsToLuxAccount(mnemonic);

console.log("EVM Address:", account.getEVMAddress());
console.log("Exchange-Chain Address:", account.getXPAddress("X"));
console.log("Platform-Chain Address:", account.getXPAddress("P"));
```

### Parameters

- **`mnemonic: string`** - The mnemonic phrase (required)
- **`options?: MnemonicToAccountOptions`** - Optional derivation path configuration

### Options Interface

```typescript
interface MnemonicToAccountOptions {
  accountIndex?: number; // Account index (default: 0)
  addressIndex?: number; // Address index (default: 0)
  changeIndex?: number; // Change index (default: 0)
  xpAccountIndex?: number; // XP account index (default: 0)
  xpAddressIndex?: number; // XP address index (default: 0)
  xpChangeIndex?: number; // XP change index (default: 0)
  path?: string; // Custom derivation path for EVM Account
  xpPath?: string; // Custom derivation path for XP Account
}
```

## Generating Mnemonics

### Generate Random Mnemonic

```typescript
import {
  generateMnemonic,
  mnemonicsToLuxAccount,
} from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const mnemonic: string = generateMnemonic();
console.log("Generated mnemonic:", mnemonic);

const account: LuxAccount = mnemonicsToLuxAccount(mnemonic);

console.log("EVM address:", account.getEVMAddress());
console.log("Exchange-Chain address:", account.getXPAddress("X"));
console.log("Platform-Chain address:", account.getXPAddress("P"));

// ⚠️ IMPORTANT: Store mnemonic securely
// Never log it in production or commit to version control
```

### Generate Mnemonic in Different Languages

```typescript
import {
  generateMnemonic,
  english,
  spanish,
  japanese,
} from "@lux-sdk/client/accounts";

// Generate mnemonic in different languages
const englishMnemonic = generateMnemonic(english);
const spanishMnemonic = generateMnemonic(spanish);
const japaneseMnemonic = generateMnemonic(japanese);
// Also available: french, italian, portuguese, czech, korean, simplifiedChinese, traditionalChinese
```

## Derivation Paths

### Default Derivation Paths

The Lux Client SDK uses different derivation paths for EVM and XP accounts:

```typescript
// EVM (LUExchange-Chain) derivation path
// Standard BIP44 path for Ethereum
const evmPath = "m/44'/60'/0'/0/0"; // m/44'/60'/{accountIndex}'/{changeIndex}/{addressIndex}

// XP (X/Platform-Chain) derivation path
// Standard BIP44 path for Lux (uses Ethereum coin type)
const xpPath = "m/44'/60'/0'/0/0"; // m/44'/60'/{xpAccountIndex}'/{xpChangeIndex}/{xpAddressIndex}
```

### Custom Derivation Paths

```typescript
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const mnemonic = "abandon abandon abandon...";

// Create account with custom derivation paths
const account: LuxAccount = mnemonicsToLuxAccount(mnemonic, {
  accountIndex: 0,
  addressIndex: 0,
  changeIndex: 0,
  path: "m/44'/60'/0'/0/0", // Custom path
});
```

### Multiple Accounts from Same Mnemonic

```typescript
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";

const mnemonic = "abandon abandon abandon...";

// Different account indices
const account0 = mnemonicsToLuxAccount(mnemonic, { accountIndex: 0 });
const account1 = mnemonicsToLuxAccount(mnemonic, { accountIndex: 1 });

// Different address indices
const addr0 = mnemonicsToLuxAccount(mnemonic, { addressIndex: 0 });
const addr1 = mnemonicsToLuxAccount(mnemonic, { addressIndex: 1 });
```

## Getting Addresses

```typescript
const account = mnemonicsToLuxAccount(mnemonic);

// All chain addresses
const evmAddress = account.getEVMAddress();
const xChainAddress = account.getXPAddress("X");
const pChainAddress = account.getXPAddress("P");

// Network-specific
const mainnet = account.getXPAddress("X", "lux");
const testnet = account.getXPAddress("X", "testnet");
```

## Using with Wallet Client

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import { mnemonicsToLuxAccount } from "@lux-sdk/client/accounts";

const account = mnemonicsToLuxAccount(process.env.MNEMONIC!);

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// LUExchange-Chain transaction
const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: 0.001,
});

// X/Platform-Chain transaction
const xpTx = await walletClient.xChain.prepareBaseTxn({
  outputs: [{ addresses: [account.getXPAddress("X")], amount: 1 }],
});
await walletClient.sendXPTransaction(xpTx);
```

## Security

<Callout>
  **Never expose mnemonics in client-side code or commit them to version
  control. Use environment variables.**
</Callout>

```typescript
// ✅ Good
const account = mnemonicsToLuxAccount(process.env.MNEMONIC!);

// ❌ Bad
const account = mnemonicsToLuxAccount("abandon abandon abandon...");
```

## Next Steps

- **[HD Key Accounts](accounts/local/hd-key)** - Learn about hierarchical deterministic accounts
- **[Account Utilities](accounts/local/utilities)** - Account validation and utilities
- **[Using Accounts with Clients](accounts/local/clients)** - Client integration patterns
- **[Network-Specific Addresses](accounts/local/addresses)** - Multi-network support


# Private Key Accounts (/docs/tooling/avalanche-sdk/client/accounts/local/private-key)

---
title: "Private Key Accounts"
icon: "key"
---

## Overview

Private Key Accounts provide the simplest way to create an Lux account from a single private key. They support both EVM (LUExchange-Chain) and X/P (Exchange-Chain/Platform-Chain) operations with unified address management.

**Best for:**

- Server-side applications
- Automated bots and services
- Testing and development
- Scripts and tools

<Callout>
  **Security:** Private keys must be kept secure. Never expose private keys in
  client-side code or commit them to version control. Use environment variables
  in production.
</Callout>

## Creating Private Key Accounts

### Basic Usage

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const privateKey = "0x1234...your_private_key_here";
const account: LuxAccount = privateKeyToLuxAccount(privateKey);

console.log("EVM Address:", account.getEVMAddress());
console.log("Exchange-Chain Address:", account.getXPAddress("X"));
console.log("Platform-Chain Address:", account.getXPAddress("P"));
```

### Working with Environment Variables

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);
```

## Generating Private Keys

### Generate Random Private Key

```typescript
import {
  generatePrivateKey,
  privateKeyToLuxAccount,
} from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const privateKey: string = generatePrivateKey();
console.log("Generated private key:", privateKey);

const account: LuxAccount = privateKeyToLuxAccount(privateKey);

console.log("EVM Address:", account.getEVMAddress());
console.log("Exchange-Chain Address:", account.getXPAddress("X"));
console.log("Platform-Chain Address:", account.getXPAddress("P"));
```

## Account Properties

### EVM Account

Each Lux account contains an EVM account for LUExchange-Chain operations:

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const account: LuxAccount = privateKeyToLuxAccount("0x...");

// Access EVM account properties
const evmAccount = account.evmAccount;

console.log("Address:", evmAccount.address);
console.log("Type:", evmAccount.type); // "local"
console.log("Source:", evmAccount.source); // "privateKey"

// Get public key (if available)
if (evmAccount.publicKey) {
  console.log("Public Key:", evmAccount.publicKey);
}
```

### XP Account

Each Lux account contains an XP account for Exchange-Chain and Platform-Chain operations:

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import type {
  LuxAccount,
  LocalXPAccount,
} from "@lux-sdk/client/accounts";

const account: LuxAccount = privateKeyToLuxAccount("0x...");

// Access XP account properties
if (account.xpAccount) {
  const xpAccount: LocalXPAccount = account.xpAccount;

  console.log("Public Key:", xpAccount.publicKey);
  console.log("Type:", xpAccount.type); // "local"
  console.log("Source:", xpAccount.source); // "privateKey"
}
```

## Address Management

### Get All Addresses

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const account: LuxAccount = privateKeyToLuxAccount("0x...");

// Get all addresses
const addresses = {
  evm: account.getEVMAddress(), // "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
  xChain: account.getXPAddress("X"), // "X-lux1..."
  pChain: account.getXPAddress("P"), // "P-lux1..."
  base: account.getXPAddress(), // "lux1..." (without chain prefix)
};

console.log("All Addresses:", addresses);
```

### Network-Specific Addresses

```typescript
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount } from "@lux-sdk/client/accounts";

const account: LuxAccount = privateKeyToLuxAccount("0x...");

// Mainnet addresses (default)
const mainnetAddresses = {
  evm: account.getEVMAddress(),
  xChain: account.getXPAddress("X", "lux"),
  pChain: account.getXPAddress("P", "lux"),
};

// Testnet (Testnet) addresses
const testnetAddresses = {
  evm: account.getEVMAddress(),
  xChain: account.getXPAddress("X", "testnet"),
  pChain: account.getXPAddress("P", "testnet"),
};

console.log("Mainnet:", mainnetAddresses);
console.log("Testnet:", testnetAddresses);
```

## Using with Wallet Client

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// LUExchange-Chain transaction
const txHash = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: 0.001,
});

// X/Platform-Chain transaction
const xpTx = await walletClient.xChain.prepareBaseTxn({
  outputs: [{ addresses: [account.getXPAddress("X")], amount: 1 }],
});
await walletClient.sendXPTransaction(xpTx);
```

## Message Signing

```typescript
import { signMessage } from "@lux-sdk/client/accounts";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";

const account = privateKeyToLuxAccount("0x...");

// EVM message signing
const evmSignature = await signMessage({
  account: account.evmAccount,
  message: "Hello Lux!",
});

// XP message signing
if (account.xpAccount) {
  const xpSignature = await account.xpAccount.signMessage("Hello Lux!");
  const isValid = account.xpAccount.verify("Hello Lux!", xpSignature);
}
```

## Security

<Callout>
  **Never expose private keys in client-side code or commit them to version
  control. Use environment variables.**
</Callout>

```typescript
// ✅ Good
const account = privateKeyToLuxAccount(process.env.PRIVATE_KEY!);

// ❌ Bad
const account = privateKeyToLuxAccount("0x1234...");
```

## Next Steps

- **[Mnemonic Accounts](mnemonic)** - Learn about mnemonic-based accounts
- **[HD Key Accounts](hd-key)** - Learn about hierarchical deterministic accounts
- **[Account Utilities](utilities)** - Account validation and utilities
- **[Network-Specific Addresses](addresses)** - Working with different network addresses


# Account Utilities (/docs/tooling/avalanche-sdk/client/accounts/local/utilities)

---
title: "Account Utilities"
icon: "hammer"
---

## Overview

Account utilities provide validation, parsing, and helper functions for working with Lux accounts and addresses.

## Account Validation

### Parse Lux Account

```typescript
function parseLuxAccount(
  account: Address | LuxAccount | undefined
): LuxAccount | undefined;
```

**Parameters:**

- `account` (`Address | LuxAccount | undefined`): The account or address to parse. Can be an EVM address string, an existing `LuxAccount`, or `undefined`.

**Returns:**

- `LuxAccount | undefined`: Returns an `LuxAccount` when an address or account is provided, or `undefined` when the input is `undefined`.

**Behavior:**

The function behaves differently based on the input type:

1. **When an address string is passed**: Returns an `LuxAccount` with only `evmAccount` populated. The `xpAccount` property will be `undefined` because an address string alone doesn't contain the private key information needed to derive XP account details.

2. **When an LuxAccount is passed**: Returns the account as-is without modification. This is useful for normalizing function parameters that accept both addresses and accounts.

3. **When undefined is passed**: Returns `undefined`. This allows for optional account parameters in functions.

**Limitations:**

- When parsing from an address string, the returned account will only have `evmAccount` populated. The `xpAccount` property will be `undefined`, which means:
  - You cannot perform Exchange-Chain or Platform-Chain operations that require signing (e.g., `account.xpAccount.signMessage()`)
  - You can still use the account for read-only operations or LUExchange-Chain (EVM) operations
  - To get XP account functionality, you need to create an account from a private key or mnemonic or use a custom provider

**Example:**

```typescript
import { parseLuxAccount } from "@lux-sdk/client/accounts";
import type { LuxAccount, Address } from "@lux-sdk/client/accounts";

// Parse from address string (only evmAccount populated)
const address: Address = "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6";
const account = parseLuxAccount(address);
// account.xpAccount is undefined - can only use for LUExchange-Chain operations

// Parse existing account (returns as-is)
const fullAccount: LuxAccount = /* ... */;
const normalized = parseLuxAccount(fullAccount); // Returns as-is

// Handle undefined
const optional = parseLuxAccount(undefined); // Returns undefined
```

## Address Utilities

### Private Key to XP Address

```typescript
function privateKeyToXPAddress(privateKey: string, hrp: string): XPAddress;
```

**Parameters:**

- `privateKey` (`string`): The private key with `0x` prefix.
- `hrp` (`string`): The human-readable prefix for the address. Use `"lux"` for mainnet or `"testnet"` for testnet.

**Returns:**

- `XPAddress`: The Bech32-encoded XP address as a string.

**Example:**

```typescript
import { privateKeyToXPAddress } from "@lux-sdk/client/accounts";

const mainnet = privateKeyToXPAddress("0x...", "lux");
const testnet = privateKeyToXPAddress("0x...", "testnet");
```

### Public Key to XP Address

```typescript
function publicKeyToXPAddress(publicKey: string, hrp: string): XPAddress;
```

**Parameters:**

- `publicKey` (`string`): The public key with `0x` prefix.
- `hrp` (`string`): The human-readable prefix for the address. Use `"lux"` for mainnet or `"testnet"` for testnet.

**Returns:**

- `XPAddress`: The Bech32-encoded XP address as a string.

**Example:**

```typescript
import { publicKeyToXPAddress } from "@lux-sdk/client/accounts";

const xpAddress = publicKeyToXPAddress("0x...", "lux");
```

### Private Key to XP Public Key

```typescript
function privateKeyToXPPublicKey(privateKey: string): string;
```

**Parameters:**

- `privateKey` (`string`): The private key with `0x` prefix.

**Returns:**

- `string`: The compressed public key in hex format with `0x` prefix.

**Example:**

```typescript
import {
  privateKeyToXPPublicKey,
  publicKeyToXPAddress,
} from "@lux-sdk/client/accounts";

const publicKey = privateKeyToXPPublicKey("0x...");
const xpAddress = publicKeyToXPAddress(publicKey, "lux");
```

## Message Signing

### XP Message Signing

```typescript
function xpSignMessage(message: string, privateKey: string): Promise<string>;
```

**Parameters:**

- `message` (`string`): The message to sign.
- `privateKey` (`string`): The private key with `0x` prefix to sign with.

**Returns:**

- `Promise<string>`: A promise that resolves to a base58-encoded signature string.

**Example:**

```typescript
import { xpSignMessage } from "@lux-sdk/client/accounts";

const signature = await xpSignMessage("Hello Lux!", "0x...");
// Returns base58-encoded signature (e.g., "2k5Jv...")
```

### XP Transaction Signing

```typescript
function xpSignTransaction(
  txHash: string | Uint8Array,
  privateKey: string | Uint8Array
): Promise<string>;
```

**Parameters:**

- `txHash` (`string | Uint8Array`): The transaction hash to sign. Can be a hex string with `0x` prefix or a `Uint8Array`.
- `privateKey` (`string | Uint8Array`): The private key to sign with. Can be a hex string with `0x` prefix or a `Uint8Array`.

**Returns:**

- `Promise<string>`: A promise that resolves to a hex-encoded signature string with `0x` prefix.

**Example:**

```typescript
import { xpSignTransaction } from "@lux-sdk/client/accounts";

const signature = await xpSignTransaction("0x...", "0x...");
// Returns hex-encoded signature (e.g., "0x1234...")
```

### Signature Verification

```typescript
function xpVerifySignature(
  signature: string,
  message: string,
  publicKey: string
): boolean;
```

**Parameters:**

- `signature` (`string`): The signature to verify in hex format with `0x` prefix.
- `message` (`string`): The message that was signed.
- `publicKey` (`string`): The public key to verify with in hex format with `0x` prefix.

**Returns:**

- `boolean`: `true` if the signature is valid, `false` otherwise.

**Note:** This function expects hex format signatures. For base58 signatures created with `xpSignMessage`, use `xpAccount.verify()` instead.

**Example:**

```typescript
import { xpVerifySignature } from "@lux-sdk/client/accounts";

const isValid = xpVerifySignature("0x...", "Hello Lux!", "0x...");

// For base58 signatures from xpSignMessage, use xpAccount.verify() instead
```

### Public Key Recovery

```typescript
function xpRecoverPublicKey(message: string, signature: string): string;
```

**Parameters:**

- `message` (`string`): The message that was signed.
- `signature` (`string`): The signature in hex format with `0x` prefix.

**Returns:**

- `string`: The recovered public key as a hex string with `0x` prefix.

**Example:**

```typescript
import { xpRecoverPublicKey } from "@lux-sdk/client/accounts";

const publicKey = xpRecoverPublicKey("Hello Lux!", "0x...");
```

## XP Account Creation

### Private Key to XP Account

```typescript
function privateKeyToXPAccount(privateKey: string): XPAccount;
```

**Parameters:**

- `privateKey` (`string`): The private key with `0x` prefix.

**Returns:**

- `XPAccount`: An XP account object with the following properties:
  - `publicKey` (`string`): The compressed public key in hex format.
  - `signMessage(message: string)` (`Promise<string>`): Signs a message and returns a base58-encoded signature.
  - `signTransaction(txHash: string | Uint8Array)` (`Promise<string>`): Signs a transaction hash and returns a hex-encoded signature.
  - `verify(message: string, signature: string)` (`boolean`): Verifies a message signature.
  - `type` (`"local"`): The account type.
  - `source` (`"privateKey"`): The account source.

**Note:** Creates an XP-only account from a private key. Lighter weight than `privateKeyToLuxAccount` since it skips EVM account initialization. Use this when you only need Exchange-Chain or Platform-Chain operations.

<Callout type="warning">
  **Limitations**: No EVM account—can't use for LUExchange-Chain operations. If you need
  both XP and EVM functionality, use `privateKeyToLuxAccount` instead.
</Callout>

**Example:**

```typescript
import { privateKeyToXPAccount } from "@lux-sdk/client/accounts";

const xpAccount = privateKeyToXPAccount("0x...");

// Sign message
const signature = await xpAccount.signMessage("Hello Lux!");
const isValid = xpAccount.verify("Hello Lux!", signature);

// Sign transaction
const txSignature = await xpAccount.signTransaction("0x...");
```

## Next Steps

- **[Using Accounts with Clients](accounts/local/clients)** - Client integration patterns
- **[Wallet Operations](methods/wallet-methods/wallet)** - Learn how to send transactions
- **[Account Management](accounts)** - Overview of account management


# JSON-RPC Accounts (/docs/tooling/avalanche-sdk/client/accounts/json-rpc)

---
title: JSON-RPC Accounts
icon: globe
description: Learn how to use JSON-RPC accounts with browser wallets like MetaMask and Core in the Lux Client SDK.
---

## Overview

A JSON-RPC Account is an Account whose signing keys are stored on an external Wallet. It **defers** signing of transactions & messages to the target Wallet over JSON-RPC. Examples of such wallets include Browser Extension Wallets (like MetaMask or Core) or Mobile Wallets over WalletConnect.

## Supported Wallets

### Core Browser Extension

Core is Lux's official browser extension wallet that provides native support for Lux networks (C/P/Exchange-Chains).

```typescript
import "@lux-sdk/client/window";
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

try {
  // Check if Core extension is available
  const provider = window.lux;
  if (!provider) {
    throw new Error(
      "Core extension not found. Please install Core. https://core.app"
    );
  }

  // Create wallet client with Core provider
  const walletClient = createLuxWalletClient({
    chain: lux,
    transport: {
      type: "custom",
      provider,
    },
  });
} catch (error) {
  console.error("Failed to initialize Core provider:", error);
}
```

### MetaMask

MetaMask can be used with Lux networks through custom network configuration for LUExchange-Chain evm operations.

```typescript
import "@lux-sdk/client/window";
import { createLuxWalletClient, custom } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

// Use MetaMask provider
const provider = window.ethereum;
if (!provider) {
  throw new Error("MetaMask not found. Please install MetaMask.");
}

const walletClient = createLuxWalletClient({
  chain: lux,
  transport: {
    type: "custom",
    provider,
  },
});
```

## Basic Usage

### 1. Request Account Connection

```typescript
try {
  // Request accounts from the wallet
  const accounts: string[] = await walletClient.requestAddresses();
  const address: string = accounts[0]; // Get the first account
  console.log("Connected address:", address);
} catch (error) {
  console.error("Failed to request addresses:", error);
}
```

### 2. Send Transactions

```typescript
try {
  // Send a transaction (will prompt user to sign)
  const txHash: string = await walletClient.send({
    to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    amount: 0.001,
  });
  console.log("Transaction hash:", txHash);
} catch (error) {
  console.error("Failed to send transaction:", error);
}
```

### 3. Switch Networks

```typescript
import { lux, luxTestnet } from "@lux-sdk/client/chains";

try {
  // Switch to Lux mainnet
  await walletClient.switchChain({
    id: lux.id,
  });
  console.log("Switched to Lux mainnet");

  // Switch to Testnet testnet
  await walletClient.switchChain({
    id: luxTestnet.id,
  });
  console.log("Switched to Testnet testnet");
} catch (error) {
  console.error("Failed to switch chain:", error);
}
```

## React Integration Example

Here's a complete React component for wallet connection using Core:

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { lux, luxTestnet } from "@lux-sdk/client/chains";
import { useState, useCallback } from "react";
import "@lux-sdk/client/window";

export function ConnectWallet() {
  const [connected, setConnected] = useState(false);
  const [address, setAddress] = useState<string | null>(null);
  const [chain, setChain] = useState<"mainnet" | "testnet">("testnet");

  const selectedChain = chain === "testnet" ? luxTestnet : lux;

  const connect = useCallback(async () => {
    try {
      const provider = window.lux;
      if (!provider) {
        throw new Error("Core extension not found. Please install Core.");
      }

      const walletClient = createLuxWalletClient({
        chain: selectedChain,
        transport: { type: "custom", provider },
      });

      const accounts = await walletClient.requestAddresses();
      const addr = accounts[0];

      setAddress(addr);
      setConnected(true);
    } catch (error) {
      console.error("Connection failed:", error);
    }
  }, [selectedChain]);

  const sendTransaction = useCallback(async () => {
    if (!connected || !address) return;

    try {
      const provider = (window as any).lux;
      const walletClient = createLuxWalletClient({
        chain: selectedChain,
        transport: { type: "custom", provider },
      });

      const txHash = await walletClient.send({
        to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
        amount: 0.001,
      });

      console.log("Transaction sent:", txHash);
    } catch (error) {
      console.error("Transaction failed:", error);
    }
  }, [connected, address, selectedChain]);

  return (
    <div>
      <h2>Wallet Connection</h2>

      {!connected ? (
        <button onClick={connect}>Connect Core Wallet</button>
      ) : (
        <div>
          <p>Connected: {address}</p>
          <p>Network: {selectedChain.name}</p>

          <div>
            <label>
              <input
                type="radio"
                value="testnet"
                checked={chain === "testnet"}
                onChange={(e) => setChain(e.target.value as "testnet")}
              />
              Testnet Testnet
            </label>
            <label>
              <input
                type="radio"
                value="mainnet"
                checked={chain === "mainnet"}
                onChange={(e) => setChain(e.target.value as "mainnet")}
              />
              Mainnet
            </label>
          </div>

          <button onClick={sendTransaction}>Send Transaction</button>
        </div>
      )}
    </div>
  );
}
```

## Cross-Chain Operations

JSON-RPC accounts support cross-chain operations through the Lux Client SDK:

```typescript
// Platform-Chain export transaction
const pChainExportTxn = await walletClient.pChain.prepareExportTxn({
  destinationChain: "C",
  fromAddress: address,
  exportedOutput: {
    addresses: [address],
    amount: luxToWei(0.001),
  },
});

const txHash = await walletClient.sendXPTransaction(pChainExportTxn);
```

## Best Practices

### 1. Check Provider Availability

```typescript
// Always check if the provider is available
if (typeof window !== "undefined" && window.lux) {
  // Core is available
} else if (typeof window !== "undefined" && window.ethereum) {
  // MetaMask is available
} else {
  // No wallet provider found
}
```

### 2. Handle Network Switching

```typescript
// Check if wallet is on the correct network
const currentChainId = await walletClient.getChainId();
if (currentChainId !== lux.id) {
  await walletClient.switchChain({ id: lux.id });
}
```

### 3. Graceful Error Handling

```typescript
const handleWalletError = (error: any) => {
  switch (error.code) {
    case 4001:
      return "User rejected the request";
    case -32002:
      return "Request already pending";
    case -32602:
      return "Invalid parameters";
    default:
      return error.message || "Unknown error occurred";
  }
};
```

## Troubleshooting

### Common Issues

**Provider Not Found**

```typescript
// Check if provider exists
if (!window.lux && !window.ethereum) {
  throw new Error("No wallet provider found. Please install Core or MetaMask.");
}
```

**Wrong Network**

```typescript
// Ensure wallet is on the correct network
const chainId = await walletClient.getChainId();
if (chainId !== lux.id) {
  await walletClient.switchChain({ id: lux.id });
}
```

**User Rejection**

```typescript
try {
  await walletClient.send({ to: address, amount: 0.001 });
} catch (error) {
  if (error.code === 4001) {
    console.log("User rejected transaction");
  }
}
```

## Next Steps

- **[Local Accounts](accounts/local)** - Learn about local account management
- **[Wallet Operations](methods/wallet-methods/wallet)** - Learn how to send transactions
- **[Cross-Chain Transfers](methods/wallet-methods/wallet#cross-chain-transfers)** - Moving assets between chains


# API Methods (/docs/tooling/avalanche-sdk/client/methods/public-methods/api)

---
title: API Methods
description: Complete reference for Admin, Info, Health, Index, and ProposerVM API methods
---

## Overview

The Lux Client SDK provides access to node-level API methods through specialized API clients. These include administrative operations, informational queries, health monitoring, indexed blockchain data access, and ProposerVM operations.

## Admin API Client

Provides administrative operations for managing node aliases, logging, and profiling.

**Access:** `client.admin`

### alias

Assign an API endpoint an alias.

**Function Signature:**

```typescript
function alias(params: AliasParameters): Promise<void>;

interface AliasParameters {
  endpoint: string;
  alias: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description            |
| ---------- | -------- | -------- | ---------------------- |
| `endpoint` | `string` | Yes      | API endpoint to alias  |
| `alias`    | `string` | Yes      | Alias for the endpoint |

**Returns:**

| Type            | Description     |
| --------------- | --------------- |
| `Promise<void>` | No return value |

**Example:**

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

await client.admin.alias({
  endpoint: "bc/X",
  alias: "myAlias",
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/admin-rpc#adminalias)

---

### aliasChain

Give a blockchain an alias.

**Function Signature:**

```typescript
function aliasChain(params: AliasChainParameters): Promise<void>;

interface AliasChainParameters {
  chain: string;
  alias: string;
}
```

**Parameters:**

| Name    | Type     | Required | Description              |
| ------- | -------- | -------- | ------------------------ |
| `chain` | `string` | Yes      | Blockchain ID to alias   |
| `alias` | `string` | Yes      | Alias for the blockchain |

**Returns:**

| Type            | Description     |
| --------------- | --------------- |
| `Promise<void>` | No return value |

**Example:**

```typescript
await client.admin.aliasChain({
  chain: "sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM",
  alias: "myBlockchainAlias",
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/admin-rpc#adminaliaschain)

---

### getChainAliases

Get the aliases of a chain.

**Function Signature:**

```typescript
function getChainAliases(params: GetChainAliasesParameters): Promise<string[]>;

interface GetChainAliasesParameters {
  chain: string;
}
```

**Parameters:**

| Name    | Type     | Required | Description            |
| ------- | -------- | -------- | ---------------------- |
| `chain` | `string` | Yes      | Blockchain ID to query |

**Returns:**

| Type                | Description                    |
| ------------------- | ------------------------------ |
| `Promise<string[]>` | Array of aliases for the chain |

**Example:**

```typescript
const aliases = await client.admin.getChainAliases({
  chain: "sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM",
});

console.log("Chain aliases:", aliases);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/admin-rpc#admingetchainaliases)

---

### Additional Admin API Methods

- **getLoggerLevel** - Get log and display levels of loggers
- **setLoggerLevel** - Set log and display levels of loggers
- **loadVMs** - Dynamically loads virtual machines
- **lockProfile** - Writes mutex statistics to `lock.profile`
- **memoryProfile** - Writes memory profile to `mem.profile`
- **startCPUProfiler** - Start CPU profiling
- **stopCPUProfiler** - Stop CPU profiler

See the [Admin API documentation](clients/api-clients#admin-api-client) for complete details.

---

## Info API Client

Provides node information and network statistics.

**Access:** `client.info`

### getNetworkID

Get the ID of the network this node is participating in.

**Function Signature:**

```typescript
function getNetworkID(): Promise<GetNetworkIDReturnType>;

interface GetNetworkIDReturnType {
  networkID: string;
}
```

**Returns:**

| Type                     | Description       |
| ------------------------ | ----------------- |
| `GetNetworkIDReturnType` | Network ID object |

**Return Object:**

| Property    | Type     | Description                                    |
| ----------- | -------- | ---------------------------------------------- |
| `networkID` | `string` | Network ID (1 for Mainnet, 5 for Testnet testnet) |

**Example:**

```typescript
const result = await client.info.getNetworkID();

if (result.networkID === "1") {
  console.log("Connected to Mainnet");
} else if (result.networkID === "5") {
  console.log("Connected to Testnet testnet");
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetnetworkid)

---

### getNetworkName

Get the name of the network this node is participating in.

**Function Signature:**

```typescript
function getNetworkName(): Promise<GetNetworkNameReturnType>;

interface GetNetworkNameReturnType {
  networkName: string;
}
```

**Returns:**

| Type                       | Description         |
| -------------------------- | ------------------- |
| `GetNetworkNameReturnType` | Network name object |

**Return Object:**

| Property      | Type     | Description                            |
| ------------- | -------- | -------------------------------------- |
| `networkName` | `string` | Network name (e.g., "mainnet", "testnet") |

**Example:**

```typescript
const result = await client.info.getNetworkName();
console.log("Network:", result.networkName);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetnetworkname)

---

### getNodeVersion

Get the version of this node.

**Function Signature:**

```typescript
function getNodeVersion(): Promise<GetNodeVersionReturnType>;

interface GetNodeVersionReturnType {
  version: string;
  databaseVersion: string;
  gitCommit: string;
  vmVersions: Map<string, string>;
  rpcProtocolVersion: string;
}
```

**Returns:**

| Type                       | Description         |
| -------------------------- | ------------------- |
| `GetNodeVersionReturnType` | Node version object |

**Return Object:**

| Property             | Type                  | Description                            |
| -------------------- | --------------------- | -------------------------------------- |
| `version`            | `string`              | Node version (e.g., "lux/1.9.4") |
| `databaseVersion`    | `string`              | Database version                       |
| `gitCommit`          | `string`              | Git commit hash                        |
| `vmVersions`         | `Map<string, string>` | Map of VM IDs to their versions        |
| `rpcProtocolVersion` | `string`              | RPC protocol version                   |

**Example:**

```typescript
const version = await client.info.getNodeVersion();
console.log("Node version:", version.version);
console.log("Database version:", version.databaseVersion);
console.log("VM versions:", Object.fromEntries(version.vmVersions));
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetnodeversion)

---

### getNodeID

Get the node ID, BLS key, and proof of possession.

**Function Signature:**

```typescript
function getNodeID(): Promise<GetNodeIDReturnType>;

interface GetNodeIDReturnType {
  nodeID: string;
  nodePOP: {
    publicKey: string;
    proofOfPossession: string;
  };
}
```

**Returns:**

| Type                  | Description    |
| --------------------- | -------------- |
| `GetNodeIDReturnType` | Node ID object |

**Return Object:**

| Property                    | Type     | Description                                     |
| --------------------------- | -------- | ----------------------------------------------- |
| `nodeID`                    | `string` | Unique identifier of the node                   |
| `nodePOP.publicKey`         | `string` | 48 byte hex representation of the BLS key       |
| `nodePOP.proofOfPossession` | `string` | 96 byte hex representation of the BLS signature |

**Example:**

```typescript
const nodeID = await client.info.getNodeID();
console.log("Node ID:", nodeID.nodeID);
console.log("BLS Public Key:", nodeID.nodePOP.publicKey);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetnodeid)

---

### getNodeIP

Get the IP address of the node.

**Function Signature:**

```typescript
function getNodeIP(): Promise<GetNodeIPReturnType>;

interface GetNodeIPReturnType {
  ip: string;
}
```

**Returns:**

| Type                  | Description    |
| --------------------- | -------------- |
| `GetNodeIPReturnType` | Node IP object |

**Return Object:**

| Property | Type     | Description            |
| -------- | -------- | ---------------------- |
| `ip`     | `string` | IP address of the node |

**Example:**

```typescript
const result = await client.info.getNodeIP();
console.log("Node IP:", result.ip);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetnodeip)

---

### getBlockchainID

Get blockchain ID from alias.

**Function Signature:**

```typescript
function getBlockchainID(
  params: GetBlockchainIDParameters
): Promise<GetBlockchainIDReturnType>;

interface GetBlockchainIDParameters {
  alias: string;
}

interface GetBlockchainIDReturnType {
  blockchainID: string;
}
```

**Parameters:**

| Name    | Type     | Required | Description                       |
| ------- | -------- | -------- | --------------------------------- |
| `alias` | `string` | Yes      | Blockchain alias (e.g., "X", "P") |

**Returns:**

| Type                        | Description          |
| --------------------------- | -------------------- |
| `GetBlockchainIDReturnType` | Blockchain ID object |

**Return Object:**

| Property       | Type     | Description          |
| -------------- | -------- | -------------------- |
| `blockchainID` | `string` | ID of the blockchain |

**Example:**

```typescript
const result = await client.info.getBlockchainID({ alias: "X" });
console.log("Exchange-Chain ID:", result.blockchainID);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetblockchainid)

---

### getTxFee

Get transaction fees for various operations.

**Function Signature:**

```typescript
function getTxFee(): Promise<GetTxFeeReturnType>;

interface GetTxFeeReturnType {
  txFee: bigint;
  createAssetTxFee: bigint;
  createSubnetTxFee: bigint;
  transformSubnetTxFee: bigint;
  createBlockchainTxFee: bigint;
  addPrimaryNetworkValidatorFee: bigint;
  addPrimaryNetworkDelegatorFee: bigint;
  addSubnetValidatorFee: bigint;
  addSubnetDelegatorFee: bigint;
}
```

**Returns:**

| Type                 | Description             |
| -------------------- | ----------------------- |
| `GetTxFeeReturnType` | Transaction fees object |

**Return Object:**

| Property                        | Type     | Description                                |
| ------------------------------- | -------- | ------------------------------------------ |
| `txFee`                         | `bigint` | Base transaction fee                       |
| `createAssetTxFee`              | `bigint` | Fee for creating an asset                  |
| `createSubnetTxFee`             | `bigint` | Fee for creating a subnet                  |
| `transformSubnetTxFee`          | `bigint` | Fee for transforming a subnet              |
| `createBlockchainTxFee`         | `bigint` | Fee for creating a blockchain              |
| `addPrimaryNetworkValidatorFee` | `bigint` | Fee for adding a primary network validator |
| `addPrimaryNetworkDelegatorFee` | `bigint` | Fee for adding a primary network delegator |
| `addSubnetValidatorFee`         | `bigint` | Fee for adding a subnet validator          |
| `addSubnetDelegatorFee`         | `bigint` | Fee for adding a subnet delegator          |

**Example:**

```typescript
const fees = await client.info.getTxFee();
console.log("Base transaction fee:", fees.txFee);
console.log("Create asset fee:", fees.createAssetTxFee);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogettxfee)

---

### getVMs

Get supported virtual machines.

**Function Signature:**

```typescript
function getVMs(): Promise<GetVMsReturnType>;

interface GetVMsReturnType {
  vms: {
    [key: string]: string[];
  };
}
```

**Returns:**

| Type               | Description |
| ------------------ | ----------- |
| `GetVMsReturnType` | VMs object  |

**Return Object:**

| Property | Type                          | Description                    |
| -------- | ----------------------------- | ------------------------------ |
| `vms`    | `{ [key: string]: string[] }` | Map of VM IDs to their aliases |

**Example:**

```typescript
const vms = await client.info.getVMs();
console.log("Supported VMs:", vms.vms);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infogetvms)

---

### isBootstrapped

Check whether a given chain is done bootstrapping.

**Function Signature:**

```typescript
function isBootstrapped(
  params: IsBootstrappedParameters
): Promise<IsBootstrappedReturnType>;

interface IsBootstrappedParameters {
  chain: string;
}

interface IsBootstrappedReturnType {
  isBootstrapped: boolean;
}
```

**Parameters:**

| Name    | Type     | Required | Description                   |
| ------- | -------- | -------- | ----------------------------- |
| `chain` | `string` | Yes      | Chain ID or alias (e.g., "X") |

**Returns:**

| Type                       | Description         |
| -------------------------- | ------------------- |
| `IsBootstrappedReturnType` | Bootstrapped status |

**Return Object:**

| Property         | Type      | Description                             |
| ---------------- | --------- | --------------------------------------- |
| `isBootstrapped` | `boolean` | Whether the chain is done bootstrapping |

**Example:**

```typescript
const result = await client.info.isBootstrapped({ chain: "X" });

if (result.isBootstrapped) {
  console.log("Exchange-Chain is bootstrapped");
} else {
  console.log("Exchange-Chain is still bootstrapping");
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infoisbootstrapped)

---

### peers

Get peer information.

**Function Signature:**

```typescript
function peers(params: PeersParameters): Promise<PeersReturnType>;

interface PeersParameters {
  nodeIDs?: string[];
}

interface PeersReturnType {
  numPeers: number;
  peers: {
    ip: string;
    publicIP: string;
    nodeID: string;
    version: string;
    lastSent: string;
    lastReceived: string;
    benched: string[];
    observedUptime: number;
  }[];
}
```

**Parameters:**

| Name      | Type       | Required | Description                          |
| --------- | ---------- | -------- | ------------------------------------ |
| `nodeIDs` | `string[]` | No       | Optional array of node IDs to filter |

**Returns:**

| Type              | Description  |
| ----------------- | ------------ |
| `PeersReturnType` | Peers object |

**Return Object:**

| Property   | Type     | Description                       |
| ---------- | -------- | --------------------------------- |
| `numPeers` | `number` | Number of connected peers         |
| `peers`    | `array`  | Array of peer information objects |

**Peer Object:**

| Property         | Type       | Description                                        |
| ---------------- | ---------- | -------------------------------------------------- |
| `ip`             | `string`   | Remote IP of the peer                              |
| `publicIP`       | `string`   | Public IP of the peer                              |
| `nodeID`         | `string`   | Prefixed Node ID of the peer                       |
| `version`        | `string`   | Version the peer is running                        |
| `lastSent`       | `string`   | Timestamp of last message sent to the peer         |
| `lastReceived`   | `string`   | Timestamp of last message received from the peer   |
| `benched`        | `string[]` | Array of chain IDs the peer is benched on          |
| `observedUptime` | `number`   | Node's primary network uptime observed by the peer |

**Example:**

```typescript
const peers = await client.info.peers();
console.log("Number of peers:", peers.numPeers);
console.log("Peer details:", peers.peers);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infopeers)

---

### uptime

Get node uptime statistics.

**Function Signature:**

```typescript
function uptime(): Promise<UptimeReturnType>;

interface UptimeReturnType {
  rewardingStakePercentage: number;
  weightedAveragePercentage: number;
}
```

**Returns:**

| Type               | Description   |
| ------------------ | ------------- |
| `UptimeReturnType` | Uptime object |

**Return Object:**

| Property                    | Type     | Description                                                             |
| --------------------------- | -------- | ----------------------------------------------------------------------- |
| `rewardingStakePercentage`  | `number` | Percent of stake which thinks this node is above the uptime requirement |
| `weightedAveragePercentage` | `number` | Stake-weighted average of all observed uptimes for this node            |

**Example:**

```typescript
const uptime = await client.info.uptime();
console.log("Rewarding stake percentage:", uptime.rewardingStakePercentage);
console.log("Weighted average percentage:", uptime.weightedAveragePercentage);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infouptime)

---

### upgrades

Get upgrade history.

**Function Signature:**

```typescript
function upgrades(): Promise<UpgradesReturnType>;

interface UpgradesReturnType {
  apricotPhase1Time: string;
  apricotPhase2Time: string;
  apricotPhase3Time: string;
  apricotPhase4Time: string;
  apricotPhase4MinPChainHeight: number;
  apricotPhase5Time: string;
  apricotPhasePre6Time: string;
  apricotPhase6Time: string;
  apricotPhasePost6Time: string;
  banffTime: string;
  cortinaTime: string;
  cortinaXChainStopVertexID: string;
  durangoTime: string;
  etnaTime: string;
  fortunaTime?: string;
}
```

**Returns:**

| Type                 | Description     |
| -------------------- | --------------- |
| `UpgradesReturnType` | Upgrades object |

**Return Object:**

| Property                       | Type      | Description                                |
| ------------------------------ | --------- | ------------------------------------------ |
| `apricotPhase1Time`            | `string`  | Timestamp of Apricot Phase 1 upgrade       |
| `apricotPhase2Time`            | `string`  | Timestamp of Apricot Phase 2 upgrade       |
| `apricotPhase3Time`            | `string`  | Timestamp of Apricot Phase 3 upgrade       |
| `apricotPhase4Time`            | `string`  | Timestamp of Apricot Phase 4 upgrade       |
| `apricotPhase4MinPChainHeight` | `number`  | Minimum Platform-Chain height for Apricot Phase 4 |
| `apricotPhase5Time`            | `string`  | Timestamp of Apricot Phase 5 upgrade       |
| `apricotPhasePre6Time`         | `string`  | Timestamp of Apricot Phase Pre-6 upgrade   |
| `apricotPhase6Time`            | `string`  | Timestamp of Apricot Phase 6 upgrade       |
| `apricotPhasePost6Time`        | `string`  | Timestamp of Apricot Phase Post-6 upgrade  |
| `banffTime`                    | `string`  | Timestamp of Banff upgrade                 |
| `cortinaTime`                  | `string`  | Timestamp of Cortina upgrade               |
| `cortinaXChainStopVertexID`    | `string`  | Exchange-Chain stop vertex ID for Cortina upgrade |
| `durangoTime`                  | `string`  | Timestamp of Durango upgrade               |
| `etnaTime`                     | `string`  | Timestamp of Etna upgrade                  |
| `fortunaTime`                  | `string?` | Timestamp of Fortuna upgrade (optional)    |

**Example:**

```typescript
const upgrades = await client.info.upgrades();
console.log("Apricot Phase 1:", upgrades.apricotPhase1Time);
console.log("Banff upgrade:", upgrades.banffTime);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infoupgrades)

---

### acps

Get peer preferences for Lux Community Proposals.

**Function Signature:**

```typescript
function acps(): Promise<AcpsReturnType>;

interface AcpsReturnType {
  acps: Map<
    number,
    {
      supportWeight: bigint;
      supporters: Set<string>;
      objectWeight: bigint;
      objectors: Set<string>;
      abstainWeight: bigint;
    }
  >;
}
```

**Returns:**

| Type             | Description |
| ---------------- | ----------- |
| `AcpsReturnType` | LPs object |

**Return Object:**

| Property | Type  | Description                              |
| -------- | ----- | ---------------------------------------- |
| `acps`   | `Map` | Map of LP IDs to their peer preferences |

**LP Object:**

| Property        | Type          | Description                             |
| --------------- | ------------- | --------------------------------------- |
| `supportWeight` | `bigint`      | Weight of stake supporting the LP      |
| `supporters`    | `Set<string>` | Set of node IDs supporting the LP      |
| `objectWeight`  | `bigint`      | Weight of stake objecting to the LP    |
| `objectors`     | `Set<string>` | Set of node IDs objecting to the LP    |
| `abstainWeight` | `bigint`      | Weight of stake abstaining from the LP |

**Example:**

```typescript
const acps = await client.info.acps();
console.log("LP preferences:", acps.acps);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/info-rpc#infoacps)

---

## Health API Client

Provides health monitoring for the node.

**Access:** `client.health`

### health

Get health check results for the node.

**Function Signature:**

```typescript
function health(params: HealthParameters): Promise<HealthReturnType>;

interface HealthParameters {
  tags?: string[];
}

interface HealthReturnType {
  healthy: boolean;
  checks: {
    C: ChainHealthCheck;
    P: ChainHealthCheck;
    X: ChainHealthCheck;
    bootstrapped: {
      message: any[];
      timestamp: string;
      duration: number;
    };
    database: {
      timestamp: string;
      duration: number;
    };
    diskspace: {
      message: {
        availableDiskBytes: number;
      };
      timestamp: string;
      duration: number;
    };
    network: {
      message: {
        connectedPeers: number;
        sendFailRate: number;
        timeSinceLastMsgReceived: string;
        timeSinceLastMsgSent: string;
      };
      timestamp: string;
      duration: number;
    };
    router: {
      message: {
        longestRunningRequest: string;
        outstandingRequests: number;
      };
      timestamp: string;
      duration: number;
    };
  };
}

type ChainHealthCheck = {
  message: {
    engine: {
      consensus: {
        lastAcceptedHeight: number;
        lastAcceptedID: string;
        longestProcessingBlock: string;
        processingBlocks: number;
      };
      vm: null;
    };
    networking: {
      percentConnected: number;
    };
  };
  timestamp: string;
  duration: number;
};
```

**Parameters:**

| Name   | Type       | Required | Description                           |
| ------ | ---------- | -------- | ------------------------------------- |
| `tags` | `string[]` | No       | Optional tags to filter health checks |

**Returns:**

| Type               | Description          |
| ------------------ | -------------------- |
| `HealthReturnType` | Health check results |

**Return Object:**

| Property  | Type      | Description                             |
| --------- | --------- | --------------------------------------- |
| `healthy` | `boolean` | Overall health status of the node       |
| `checks`  | `object`  | Health check results for each component |

**Example:**

```typescript
const healthStatus = await client.health.health({
  tags: ["11111111111111111111111111111111LpoYY"],
});

console.log("Node healthy:", healthStatus.healthy);
console.log("LUExchange-Chain health:", healthStatus.checks.C);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/health-rpc#healthhealth)

---

### liveness

Get liveness check indicating if the node is alive and can handle requests.

**Function Signature:**

```typescript
function liveness(): Promise<LivenessReturnType>;

interface LivenessReturnType {
  checks: object;
  healthy: boolean;
}
```

**Returns:**

| Type                 | Description           |
| -------------------- | --------------------- |
| `LivenessReturnType` | Liveness check result |

**Return Object:**

| Property  | Type      | Description                                            |
| --------- | --------- | ------------------------------------------------------ |
| `checks`  | `object`  | Liveness check details                                 |
| `healthy` | `boolean` | Indicates if the node is alive and can handle requests |

**Example:**

```typescript
const livenessStatus = await client.health.liveness();

if (livenessStatus.healthy) {
  console.log("Node is alive and responding");
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/health-rpc#healthliveness)

---

### readiness

Get readiness check indicating if the node has finished initializing.

**Function Signature:**

```typescript
function readiness(params: ReadinessParameters): Promise<ReadinessReturnType>;

interface ReadinessParameters {
  tags?: string[];
}

interface ReadinessReturnType {
  checks: {
    [key: string]: {
      message: {
        timestamp: string;
        duration: number;
        contiguousFailures: number;
        timeOfFirstFailure: string | null;
      };
      healthy: boolean;
    };
  };
  healthy: boolean;
}
```

**Parameters:**

| Name   | Type       | Required | Description                              |
| ------ | ---------- | -------- | ---------------------------------------- |
| `tags` | `string[]` | No       | Optional tags to filter readiness checks |

**Returns:**

| Type                  | Description            |
| --------------------- | ---------------------- |
| `ReadinessReturnType` | Readiness check result |

**Return Object:**

| Property  | Type      | Description                                |
| --------- | --------- | ------------------------------------------ |
| `checks`  | `object`  | Readiness check results for each component |
| `healthy` | `boolean` | Overall readiness status of the node       |

**Example:**

```typescript
const readinessStatus = await client.health.readiness({
  tags: ["11111111111111111111111111111111LpoYY"],
});

if (readinessStatus.healthy) {
  console.log("Node is ready to handle requests");
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/health-rpc#healthreadiness)

---

## Index API Clients

Provides indexed blockchain data queries for fast container lookups.

**Access:**

- `client.indexBlock.pChain` - Platform-Chain block index
- `client.indexBlock.cChain` - LUExchange-Chain block index
- `client.indexBlock.xChain` - Exchange-Chain block index
- `client.indexTx.xChain` - Exchange-Chain transaction index

### getContainerByIndex

Get container by its index.

**Function Signature:**

```typescript
function getContainerByIndex(
  params: GetContainerByIndexParameters
): Promise<GetContainerByIndexReturnType>;

interface GetContainerByIndexParameters {
  index: number;
  encoding: "hex";
}

interface GetContainerByIndexReturnType {
  id: string;
  bytes: string;
  timestamp: string;
  encoding: "hex";
  index: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description                                     |
| ---------- | -------- | -------- | ----------------------------------------------- |
| `index`    | `number` | Yes      | Container index (first container is at index 0) |
| `encoding` | `"hex"`  | Yes      | Encoding format (only "hex" is supported)       |

**Returns:**

| Type                            | Description      |
| ------------------------------- | ---------------- |
| `GetContainerByIndexReturnType` | Container object |

**Return Object:**

| Property    | Type     | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `id`        | `string` | Container's ID                                    |
| `bytes`     | `string` | Byte representation of the container              |
| `timestamp` | `string` | Time at which this node accepted the container    |
| `encoding`  | `"hex"`  | Encoding format used                              |
| `index`     | `string` | How many containers were accepted before this one |

**Example:**

```typescript
const container = await client.indexBlock.pChain.getContainerByIndex({
  index: 12345,
  encoding: "hex",
});

console.log("Container ID:", container.id);
console.log("Container bytes:", container.bytes);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/index-rpc#indexgetcontainerbyindex)

---

### getContainerByID

Get container by its ID.

**Function Signature:**

```typescript
function getContainerByID(
  params: GetContainerByIDParameters
): Promise<GetContainerByIDReturnType>;

interface GetContainerByIDParameters {
  id: string;
  encoding: "hex";
}

interface GetContainerByIDReturnType {
  id: string;
  bytes: string;
  timestamp: string;
  encoding: "hex";
  index: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description                               |
| ---------- | -------- | -------- | ----------------------------------------- |
| `id`       | `string` | Yes      | Container's ID                            |
| `encoding` | `"hex"`  | Yes      | Encoding format (only "hex" is supported) |

**Returns:**

| Type                         | Description      |
| ---------------------------- | ---------------- |
| `GetContainerByIDReturnType` | Container object |

**Return Object:**

| Property    | Type     | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `id`        | `string` | Container's ID                                    |
| `bytes`     | `string` | Byte representation of the container              |
| `timestamp` | `string` | Time at which this node accepted the container    |
| `encoding`  | `"hex"`  | Encoding format used                              |
| `index`     | `string` | How many containers were accepted before this one |

**Example:**

```typescript
const container = await client.indexBlock.cChain.getContainerByID({
  id: "0x123...",
  encoding: "hex",
});

console.log("Container index:", container.index);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/index-rpc#indexgetcontainerbyid)

---

### getContainerRange

Get range of containers by index.

**Function Signature:**

```typescript
function getContainerRange(
  params: GetContainerRangeParameters
): Promise<GetContainerRangeReturnType>;

interface GetContainerRangeParameters {
  startIndex: number;
  endIndex: number;
  encoding: "hex";
}

interface GetContainerRangeReturnType {
  containers: Array<{
    id: string;
    bytes: string;
    timestamp: string;
    encoding: "hex";
    index: string;
  }>;
}
```

**Parameters:**

| Name         | Type     | Required | Description                                         |
| ------------ | -------- | -------- | --------------------------------------------------- |
| `startIndex` | `number` | Yes      | Index of the first container to retrieve            |
| `endIndex`   | `number` | Yes      | Index of the last container to retrieve (inclusive) |
| `encoding`   | `"hex"`  | Yes      | Encoding format (only "hex" is supported)           |

**Returns:**

| Type                          | Description            |
| ----------------------------- | ---------------------- |
| `GetContainerRangeReturnType` | Container range object |

**Return Object:**

| Property     | Type    | Description                |
| ------------ | ------- | -------------------------- |
| `containers` | `array` | Array of container details |

**Container Object:**

| Property    | Type     | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `id`        | `string` | Container's ID                                    |
| `bytes`     | `string` | Byte representation of the container              |
| `timestamp` | `string` | Time at which this node accepted the container    |
| `encoding`  | `"hex"`  | Encoding format used                              |
| `index`     | `string` | How many containers were accepted before this one |

**Example:**

```typescript
const range = await client.indexBlock.xChain.getContainerRange({
  startIndex: 1000,
  endIndex: 1010,
  encoding: "hex",
});

console.log("Containers:", range.containers.length);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/index-rpc#indexgetcontainerrange)

---

### getIndex

Get container index by ID.

**Function Signature:**

```typescript
function getIndex(params: GetIndexParameters): Promise<GetIndexReturnType>;

interface GetIndexParameters {
  id: string;
  encoding: "hex";
}

interface GetIndexReturnType {
  index: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description                               |
| ---------- | -------- | -------- | ----------------------------------------- |
| `id`       | `string` | Yes      | Container's ID                            |
| `encoding` | `"hex"`  | Yes      | Encoding format (only "hex" is supported) |

**Returns:**

| Type                 | Description  |
| -------------------- | ------------ |
| `GetIndexReturnType` | Index object |

**Return Object:**

| Property | Type     | Description                                            |
| -------- | -------- | ------------------------------------------------------ |
| `index`  | `string` | Index of the container (first container is at index 0) |

**Example:**

```typescript
const result = await client.indexTx.xChain.getIndex({
  id: "0x123...",
  encoding: "hex",
});

console.log("Container index:", result.index);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/index-rpc#indexgetindex)

---

### getLastAccepted

Get last accepted container.

**Function Signature:**

```typescript
function getLastAccepted(
  params: GetLastAcceptedParameters
): Promise<GetLastAcceptedReturnType>;

interface GetLastAcceptedParameters {
  encoding: "hex";
}

interface GetLastAcceptedReturnType {
  id: string;
  bytes: string;
  timestamp: string;
  encoding: "hex";
  index: string;
}
```

**Parameters:**

| Name       | Type    | Required | Description                               |
| ---------- | ------- | -------- | ----------------------------------------- |
| `encoding` | `"hex"` | Yes      | Encoding format (only "hex" is supported) |

**Returns:**

| Type                        | Description                    |
| --------------------------- | ------------------------------ |
| `GetLastAcceptedReturnType` | Last accepted container object |

**Return Object:**

| Property    | Type     | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `id`        | `string` | Container's ID                                    |
| `bytes`     | `string` | Byte representation of the container              |
| `timestamp` | `string` | Time at which this node accepted the container    |
| `encoding`  | `"hex"`  | Encoding format used                              |
| `index`     | `string` | How many containers were accepted before this one |

**Example:**

```typescript
const lastAccepted = await client.indexBlock.pChain.getLastAccepted({
  encoding: "hex",
});

console.log("Last accepted container ID:", lastAccepted.id);
console.log("Last accepted index:", lastAccepted.index);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/index-rpc#indexgetlastaccepted)

---

### isAccepted

Check if container is accepted in the index.

**Function Signature:**

```typescript
function isAccepted(
  params: IsAcceptedParameters
): Promise<IsAcceptedReturnType>;

interface IsAcceptedParameters {
  id: string;
  encoding: "hex";
}

interface IsAcceptedReturnType {
  isAccepted: boolean;
}
```

**Parameters:**

| Name       | Type     | Required | Description                               |
| ---------- | -------- | -------- | ----------------------------------------- |
| `id`       | `string` | Yes      | Container's ID                            |
| `encoding` | `"hex"`  | Yes      | Encoding format (only "hex" is supported) |

**Returns:**

| Type                   | Description              |
| ---------------------- | ------------------------ |
| `IsAcceptedReturnType` | Acceptance status object |

**Return Object:**

| Property     | Type      | Description                            |
| ------------ | --------- | -------------------------------------- |
| `isAccepted` | `boolean` | Whether the container is in this index |

**Example:**

```typescript
const result = await client.indexBlock.cChain.isAccepted({
  id: "0x123...",
  encoding: "hex",
});

if (result.isAccepted) {
  console.log("Container is accepted");
} else {
  console.log("Container is not accepted");
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/other/index-rpc#indexisaccepted)

---

## ProposerVM API Client

Provides ProposerVM operations for each chain. ProposerVM is responsible for proposing blocks and managing consensus.

**Access:**

- `client.proposerVM.pChain` - Platform-Chain ProposerVM
- `client.proposerVM.xChain` - Exchange-Chain ProposerVM
- `client.proposerVM.cChain` - LUExchange-Chain ProposerVM

### getProposedHeight

Get the current proposed height for the chain.

**Function Signature:**

```typescript
function getProposedHeight(): Promise<GetProposedHeightReturnType>;

interface GetProposedHeightReturnType {
  height: string;
}
```

**Returns:**

| Type                          | Description            |
| ----------------------------- | ---------------------- |
| `GetProposedHeightReturnType` | Proposed height object |

**Return Object:**

| Property | Type     | Description                            |
| -------- | -------- | -------------------------------------- |
| `height` | `string` | This node's current proposer VM height |

**Example:**

```typescript
const pChainHeight = await client.proposerVM.pChain.getProposedHeight();
console.log("Platform-Chain proposed height:", pChainHeight.height);

const xChainHeight = await client.proposerVM.xChain.getProposedHeight();
console.log("Exchange-Chain proposed height:", xChainHeight.height);

const cChainHeight = await client.proposerVM.cChain.getProposedHeight();
console.log("LUExchange-Chain proposed height:", cChainHeight.height);
```

**Related:**

- [API Reference](https://build.lux.network/docs/api-reference/proposervm-api#proposervmgetproposedheight)

---

### getCurrentEpoch

Get the current epoch information.

**Function Signature:**

```typescript
function getCurrentEpoch(): Promise<GetCurrentEpochReturnType>;

interface GetCurrentEpochReturnType {
  number: string;
  startTime: string;
  pChainHeight: string;
}
```

**Returns:**

| Type                        | Description          |
| --------------------------- | -------------------- |
| `GetCurrentEpochReturnType` | Current epoch object |

**Return Object:**

| Property       | Type     | Description                                   |
| -------------- | -------- | --------------------------------------------- |
| `number`       | `string` | The current epoch number                      |
| `startTime`    | `string` | The epoch start time (Unix timestamp)         |
| `pChainHeight` | `string` | The Platform-Chain height at the start of this epoch |

**Example:**

```typescript
const epoch = await client.proposerVM.pChain.getCurrentEpoch();
console.log("Current epoch:", epoch.number);
console.log("Epoch start time:", epoch.startTime);
console.log("Platform-Chain height at epoch start:", epoch.pChainHeight);
```

**Related:**

- [API Reference](https://build.lux.network/docs/api-reference/proposervm-api#proposervmgetcurrentepoch)

---

## Next Steps

- **[API Clients Documentation](clients/api-clients)** - Detailed API client reference
- **[Main Clients](clients)** - Client architecture overview
- **[Getting Started](getting-started)** - Quick start guide


# LUExchange-Chain Methods (/docs/tooling/avalanche-sdk/client/methods/public-methods/c-chain)

---
title: LUExchange-Chain Methods
description: Complete reference for LUExchange-Chain (Contract Chain) methods and EVM compatibility
---

## Overview

The LUExchange-Chain (Contract Chain) is Lux's instance of the Ethereum Virtual Machine (EVM), providing full Ethereum compatibility with additional Lux-specific features like cross-chain atomic transactions and UTXO management.

**Note:** The Lux Client SDK fully extends [viem](https://viem.sh), meaning all standard EVM methods are also available. See the [viem documentation](https://viem.sh/docs) for complete EVM method reference.

## Atomic Transaction Operations

### getAtomicTx

Get an atomic transaction by its ID. Atomic transactions enable cross-chain transfers between the LUExchange-Chain and other Lux chains (Platform-Chain, Exchange-Chain).

**Function Signature:**

```typescript
function getAtomicTx(
  params: GetAtomicTxParameters
): Promise<GetAtomicTxReturnType>;

interface GetAtomicTxParameters {
  txID: string;
  encoding?: "hex";
}

interface GetAtomicTxReturnType {
  tx: string;
  blockHeight: string;
  encoding: "hex";
}
```

**Parameters:**

| Name       | Type     | Required | Description                                             |
| ---------- | -------- | -------- | ------------------------------------------------------- |
| `txID`     | `string` | Yes      | Transaction ID in CB58 format                           |
| `encoding` | `"hex"`  | No       | Encoding format for the transaction (defaults to "hex") |

**Returns:**

| Type                    | Description               |
| ----------------------- | ------------------------- |
| `GetAtomicTxReturnType` | Atomic transaction object |

**Return Object:**

| Property      | Type     | Description                                    |
| ------------- | -------- | ---------------------------------------------- |
| `tx`          | `string` | Transaction bytes in hex format                |
| `blockHeight` | `string` | Height of the block containing the transaction |
| `encoding`    | `"hex"`  | Encoding format used                           |

**Example:**

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const atomicTx = await client.cChain.getAtomicTx({
  txID: "2QouvMUbQ6oy7yQ9tLvL3L8tGQG2QK1wJ1q1wJ1q1wJ1q1wJ1q1wJ1q1wJ1",
});

console.log("Transaction:", atomicTx.tx);
console.log("Block height:", atomicTx.blockHeight);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#luxgetatomictx)
- [getAtomicTxStatus](#getatomictxstatus) - Get transaction status

---

### getAtomicTxStatus

Get the status of an atomic transaction. Returns the current processing state and block information.

**Function Signature:**

```typescript
function getAtomicTxStatus(
  params: GetAtomicTxStatusParameters
): Promise<GetAtomicTxStatusReturnType>;

interface GetAtomicTxStatusParameters {
  txID: string;
}

interface GetAtomicTxStatusReturnType {
  status: CChainAtomicTxStatus;
  blockHeight: string;
}

type CChainAtomicTxStatus = "Accepted" | "Processing" | "Dropped" | "Unknown";
```

**Parameters:**

| Name   | Type     | Required | Description                   |
| ------ | -------- | -------- | ----------------------------- |
| `txID` | `string` | Yes      | Transaction ID in CB58 format |

**Returns:**

| Type                          | Description               |
| ----------------------------- | ------------------------- |
| `GetAtomicTxStatusReturnType` | Transaction status object |

**Return Object:**

| Property      | Type                   | Description                                                           |
| ------------- | ---------------------- | --------------------------------------------------------------------- |
| `status`      | `CChainAtomicTxStatus` | Transaction status: "Accepted", "Processing", "Dropped", or "Unknown" |
| `blockHeight` | `string`               | Height of the block containing the transaction (if accepted)          |

**Status Values:**

- **Accepted**: Transaction is (or will be) accepted by every node
- **Processing**: Transaction is being voted on by this node
- **Dropped**: Transaction was dropped by this node because it thought the transaction invalid
- **Unknown**: Transaction hasn't been seen by this node

**Example:**

```typescript
const status = await client.cChain.getAtomicTxStatus({
  txID: "2QouvMUbQ6oy7yQ9tLvL3L8tGQG2QK1wJ1q1wJ1q1wJ1q1wJ1q1wJ1q1wJ1",
});

console.log("Status:", status.status);
if (status.status === "Accepted") {
  console.log("Block height:", status.blockHeight);
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#luxgetatomictxstatus)
- [getAtomicTx](#getatomictx) - Get transaction details

---

## UTXO Operations

### getUTXOs

Get the UTXOs (Unspent Transaction Outputs) for a set of addresses. UTXOs represent unspent native LUX on the LUExchange-Chain from imported transactions.

**Function Signature:**

```typescript
function getUTXOs(params: GetUTXOsParameters): Promise<GetUTXOsReturnType>;

interface GetUTXOsParameters {
  addresses: string[];
  limit?: number;
  startIndex?: {
    address: string;
    utxo: string;
  };
  sourceChain?: string;
  encoding?: "hex";
}

interface GetUTXOsReturnType {
  numFetched: number;
  utxos: string[];
  endIndex: {
    address: string;
    utxo: string;
  };
}
```

**Parameters:**

| Name          | Type                                | Required | Description                                  |
| ------------- | ----------------------------------- | -------- | -------------------------------------------- |
| `addresses`   | `string[]`                          | Yes      | Array of LUExchange-Chain addresses                   |
| `limit`       | `number`                            | No       | Maximum number of UTXOs to return (max 1024) |
| `startIndex`  | `{ address: string; utxo: string }` | No       | Pagination cursor for next page              |
| `sourceChain` | `string`                            | No       | Source chain ID for filtering UTXOs          |
| `encoding`    | `"hex"`                             | No       | Encoding format for returned UTXOs           |

**Returns:**

| Type                 | Description               |
| -------------------- | ------------------------- |
| `GetUTXOsReturnType` | UTXO data with pagination |

**Return Object:**

| Property     | Type                                | Description                              |
| ------------ | ----------------------------------- | ---------------------------------------- |
| `numFetched` | `number`                            | Number of UTXOs fetched in this response |
| `utxos`      | `string[]`                          | Array of UTXO bytes (hex encoded)        |
| `endIndex`   | `{ address: string; utxo: string }` | Pagination cursor for fetching next page |

**Example:**

```typescript
// Get UTXOs from Exchange-Chain
const utxos = await client.cChain.getUTXOs({
  addresses: ["0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"],
  limit: 100,
  sourceChain: "X",
});

console.log("Number of UTXOs:", utxos.numFetched);
console.log("UTXOs:", utxos.utxos);

// Get next page if needed
if (utxos.endIndex) {
  const moreUTXOs = await client.cChain.getUTXOs({
    addresses: ["0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"],
    startIndex: utxos.endIndex,
    limit: 100,
  });
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#luxgetutxos)
- [LUExchange-Chain Wallet Methods](../wallet-methods/c-chain-wallet) - Atomic transaction operations

---

## Transaction Operations

### issueTx

Issue a transaction to the LUExchange-Chain. Submits a signed transaction for processing.

**Function Signature:**

```typescript
function issueTx(params: IssueTxParameters): Promise<IssueTxReturnType>;

interface IssueTxParameters {
  tx: string;
  encoding: "hex";
}

interface IssueTxReturnType {
  txID: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `tx`       | `string` | Yes      | Transaction bytes in hex format |
| `encoding` | `"hex"`  | Yes      | Encoding format (must be "hex") |

**Returns:**

| Type                | Description           |
| ------------------- | --------------------- |
| `IssueTxReturnType` | Transaction ID object |

**Return Object:**

| Property | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `txID`   | `string` | Transaction ID in CB58 format |

**Example:**

```typescript
const txID = await client.cChain.issueTx({
  tx: "0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0...",
  encoding: "hex",
});

console.log("Transaction ID:", txID.txID);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#luxissuetx)

---

## Admin Operations

These methods are available for node administration and debugging. They require admin access to the node.

### setLogLevel

Set the log level for the LUExchange-Chain node.

**Function Signature:**

```typescript
function setLogLevel(params: SetLogLevelParameters): Promise<void>;

interface SetLogLevelParameters {
  level: string;
}
```

**Parameters:**

| Name    | Type     | Required | Description                                        |
| ------- | -------- | -------- | -------------------------------------------------- |
| `level` | `string` | Yes      | Log level (e.g., "debug", "info", "warn", "error") |

**Returns:**

| Type   | Description                            |
| ------ | -------------------------------------- |
| `void` | Promise resolves when log level is set |

**Example:**

```typescript
await client.cChain.setLogLevel({
  level: "info",
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#adminsetloglevel)

---

### startCPUProfiler

Start the CPU profiler for performance analysis.

**Function Signature:**

```typescript
function startCPUProfiler(): Promise<void>;
```

**Parameters:**

No parameters required.

**Returns:**

| Type   | Description                               |
| ------ | ----------------------------------------- |
| `void` | Promise resolves when profiler is started |

**Example:**

```typescript
await client.cChain.startCPUProfiler();
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#adminstartcpuprofiler)
- [stopCPUProfiler](#stopcpuprofiler) - Stop the CPU profiler

---

### stopCPUProfiler

Stop the CPU profiler.

**Function Signature:**

```typescript
function stopCPUProfiler(): Promise<void>;
```

**Parameters:**

No parameters required.

**Returns:**

| Type   | Description                               |
| ------ | ----------------------------------------- |
| `void` | Promise resolves when profiler is stopped |

**Example:**

```typescript
await client.cChain.stopCPUProfiler();
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#adminstopcpuprofiler)
- [startCPUProfiler](#startcpuprofiler) - Start the CPU profiler

---

### memoryProfile

Get the memory profile of the LUExchange-Chain node.

**Function Signature:**

```typescript
function memoryProfile(): Promise<void>;
```

**Parameters:**

No parameters required.

**Returns:**

| Type   | Description                                       |
| ------ | ------------------------------------------------- |
| `void` | Promise resolves when memory profile is retrieved |

**Example:**

```typescript
await client.cChain.memoryProfile();
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#adminmemoryprofile)

---

### lockProfile

Lock the profile to prevent modifications.

**Function Signature:**

```typescript
function lockProfile(): Promise<void>;
```

**Parameters:**

No parameters required.

**Returns:**

| Type   | Description                             |
| ------ | --------------------------------------- |
| `void` | Promise resolves when profile is locked |

**Example:**

```typescript
await client.cChain.lockProfile();
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#adminlockprofile)

---

## Standard EVM Methods

The LUExchange-Chain client extends viem's Public Client, providing access to all standard Ethereum methods. Here are some commonly used methods:

### Block Operations

```typescript
// Get block number
const blockNumber = await client.getBlockNumber();

// Get block by number
const block = await client.getBlock({
  blockNumber: 12345n,
});

// Get block by hash
const blockByHash = await client.getBlock({
  blockHash: "0x...",
});
```

### Balance Operations

```typescript
// Get balance
const balance = await client.getBalance({
  address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
});

// Get balance with block number
const balanceAtBlock = await client.getBalance({
  address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  blockNumber: 12345n,
});
```

### Transaction Operations

```typescript
// Get transaction
const tx = await client.getTransaction({
  hash: "0x...",
});

// Get transaction receipt
const receipt = await client.getTransactionReceipt({
  hash: "0x...",
});

// Get transaction count (nonce)
const nonce = await client.getTransactionCount({
  address: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
});
```

### Gas Operations

```typescript
// Get gas price
const gasPrice = await client.getGasPrice();

// Get max priority fee per gas
const maxPriorityFee = await client.maxPriorityFeePerGas();

// Estimate gas
const estimatedGas = await client.estimateGas({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  value: parseEther("0.001"),
});
```

### Contract Operations

```typescript
// Read contract
const result = await client.readContract({
  address: "0x...",
  abi: [...],
  functionName: "balanceOf",
  args: [address],
});

// Simulate contract
const { request } = await client.simulateContract({
  address: "0x...",
  abi: [...],
  functionName: "transfer",
  args: [to, amount],
});
```

**For complete EVM method reference, see:** [Viem Documentation](https://viem.sh/docs)

---

## Next Steps

- **[LUExchange-Chain Wallet Methods](../wallet-methods/c-chain-wallet)** - Atomic transaction operations
- **[Wallet Client](../../clients/wallet-client)** - Complete wallet operations
- **[Account Management](../../accounts)** - Account types and management
- **[Viem Documentation](https://viem.sh/docs)** - Complete EVM method reference


# Platform-Chain Methods (/docs/tooling/avalanche-sdk/client/methods/public-methods/p-chain)

---
title: Platform-Chain Methods
description: Complete reference for Platform-Chain (Platform Chain) methods
---

## Overview

The Platform-Chain (Platform Chain) is Lux's coordinating chain responsible for managing validators, delegators, subnets, and blockchains. This reference covers all read-only Platform-Chain operations available through the Lux Client SDK.

## Balance Operations

### getBalance

Get the balance of LUX controlled by a given address.

**Function Signature:**

```typescript
function getBalance(
  params: GetBalanceParameters
): Promise<GetBalanceReturnType>;

interface GetBalanceParameters {
  addresses: string[];
}

interface GetBalanceReturnType {
  balance: bigint;
  unlocked: bigint;
  lockedStakeable: bigint;
  lockedNotStakeable: bigint;
  utxoIDs: {
    txID: string;
    outputIndex: number;
  }[];
}
```

**Parameters:**

| Name        | Type       | Required | Description                         |
| ----------- | ---------- | -------- | ----------------------------------- |
| `addresses` | `string[]` | Yes      | Array of Platform-Chain addresses to query |

**Returns:**

| Type                   | Description                |
| ---------------------- | -------------------------- |
| `GetBalanceReturnType` | Balance information object |

**Return Object:**

| Property             | Type     | Description                                 |
| -------------------- | -------- | ------------------------------------------- |
| `balance`            | `bigint` | Total balance                               |
| `unlocked`           | `bigint` | Unlocked balance                            |
| `lockedStakeable`    | `bigint` | Locked and stakeable balance                |
| `lockedNotStakeable` | `bigint` | Locked but not stakeable balance            |
| `utxoIDs`            | `array`  | Array of UTXO IDs referencing the addresses |

**Example:**

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const balance = await client.pChain.getBalance({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
});

console.log("Total balance:", balance.balance);
console.log("Unlocked:", balance.unlocked);
console.log("Locked stakeable:", balance.lockedStakeable);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetbalance)
- [getUTXOs](#getutxos) - Get UTXOs for addresses

---

### getUTXOs

Get the UTXOs (Unspent Transaction Outputs) controlled by a set of addresses.

**Function Signature:**

```typescript
function getUTXOs(params: GetUTXOsParameters): Promise<GetUTXOsReturnType>;

interface GetUTXOsParameters {
  addresses: string[];
  sourceChain?: string;
  limit?: number;
  startIndex?: {
    address: string;
    utxo: string;
  };
  encoding?: "hex";
}

interface GetUTXOsReturnType {
  numFetched: number;
  utxos: string[];
  endIndex: {
    address: string;
    utxo: string;
  };
  sourceChain?: string;
  encoding: "hex";
}
```

**Parameters:**

| Name          | Type                                | Required | Description                                     |
| ------------- | ----------------------------------- | -------- | ----------------------------------------------- |
| `addresses`   | `string[]`                          | Yes      | Array of Platform-Chain addresses                      |
| `sourceChain` | `string`                            | No       | Source chain ID (e.g., "X" for Exchange-Chain)         |
| `limit`       | `number`                            | No       | Maximum number of UTXOs to return               |
| `startIndex`  | `{ address: string; utxo: string }` | No       | Pagination cursor for next page                 |
| `encoding`    | `"hex"`                             | No       | Encoding format (can only be "hex" if provided) |

**Returns:**

| Type                 | Description               |
| -------------------- | ------------------------- |
| `GetUTXOsReturnType` | UTXO data with pagination |

**Return Object:**

| Property      | Type                                | Description                              |
| ------------- | ----------------------------------- | ---------------------------------------- |
| `numFetched`  | `number`                            | Number of UTXOs fetched in this response |
| `utxos`       | `string[]`                          | Array of UTXO bytes (hex encoded)        |
| `endIndex`    | `{ address: string; utxo: string }` | Pagination cursor for fetching next page |
| `sourceChain` | `string`                            | Source chain ID (if specified)           |
| `encoding`    | `"hex"`                             | Encoding format used                     |

**Example:**

```typescript
// Get first page
const utxos = await client.pChain.getUTXOs({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
  limit: 100,
});

console.log("Fetched UTXOs:", utxos.numFetched);
console.log("UTXOs:", utxos.utxos);

// Get next page if needed
if (utxos.endIndex) {
  const moreUTXOs = await client.pChain.getUTXOs({
    addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
    startIndex: utxos.endIndex,
    limit: 100,
  });
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetutxos)
- [getBalance](#getbalance) - Get balance summary

---

## Validator Operations

### getCurrentValidators

Get the current validators of the specified Subnet.

**Function Signature:**

```typescript
function getCurrentValidators(
  params: GetCurrentValidatorsParameters
): Promise<GetCurrentValidatorsReturnType>;

interface GetCurrentValidatorsParameters {
  subnetID?: string | Buffer;
  nodeIDs?: string[];
}

interface GetCurrentValidatorsReturnType {
  validators: Array<{
    accruedDelegateeReward: string;
    txID: string;
    startTime: string;
    endTime?: string;
    stakeAmount: string;
    nodeID: string;
    weight: string;
    validationRewardOwner?: {
      locktime: string;
      threshold: string;
      addresses: string[];
    };
    delegationRewardOwner?: {
      locktime: string;
      threshold: string;
      addresses: string[];
    };
    signer?: {
      publicKey: string;
      proofOfPosession: string;
    };
    delegatorCount?: string;
    delegatorWeight?: string;
    potentialReward?: string;
    delegationFee?: string;
    uptime?: string;
    connected?: boolean;
    delegators?: Array<{
      txID: string;
      startTime: string;
      endTime: string;
      stakeAmount: string;
      nodeID: string;
      rewardOwner: {
        locktime: string;
        threshold: string;
        addresses: string[];
      };
      potentialReward: string;
    }>;
  }>;
}
```

**Parameters:**

| Name       | Type               | Required | Description                             |
| ---------- | ------------------ | -------- | --------------------------------------- |
| `subnetID` | `string \| Buffer` | No       | Subnet ID (defaults to Primary Network) |
| `nodeIDs`  | `string[]`         | No       | Specific NodeIDs to query               |

**Returns:**

| Type                             | Description            |
| -------------------------------- | ---------------------- |
| `GetCurrentValidatorsReturnType` | Validators list object |

**Return Object:**

| Property     | Type    | Description                                 |
| ------------ | ------- | ------------------------------------------- |
| `validators` | `array` | List of validators for the specified Subnet |

**Note:** Many fields in the validator object are omitted if `subnetID` is not the Primary Network. The `delegators` field is only included when `nodeIDs` specifies a single NodeID.

**Example:**

```typescript
// Get all validators on Primary Network
const validators = await client.pChain.getCurrentValidators({});

console.log("Total validators:", validators.validators.length);

// Get validators for specific subnet
const subnetValidators = await client.pChain.getCurrentValidators({
  subnetID: "11111111111111111111111111111111LpoYY",
});

// Get specific validators
const specificValidators = await client.pChain.getCurrentValidators({
  subnetID: "11111111111111111111111111111111LpoYY",
  nodeIDs: ["NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg"],
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetcurrentvalidators)
- [getValidatorsAt](#getvalidatorsat) - Get validators at specific height
- [getAllValidatorsAt](#getallvalidatorsat) - Get all validators at height
- [sampleValidators](#samplevalidators) - Sample validators

---

### getValidatorsAt

Get the validators at a specific height.

**Function Signature:**

```typescript
function getValidatorsAt(
  params: GetValidatorsAtParameters
): Promise<GetValidatorsAtReturnType>;

interface GetValidatorsAtParameters {
  height: number;
  subnetID?: string;
}

interface GetValidatorsAtReturnType {
  validators: Record<string, number>;
}
```

**Parameters:**

| Name       | Type     | Required | Description                             |
| ---------- | -------- | -------- | --------------------------------------- |
| `height`   | `number` | Yes      | Block height to query                   |
| `subnetID` | `string` | No       | Subnet ID (defaults to Primary Network) |

**Returns:**

| Type                        | Description           |
| --------------------------- | --------------------- |
| `GetValidatorsAtReturnType` | Validators map object |

**Return Object:**

| Property     | Type                     | Description                                 |
| ------------ | ------------------------ | ------------------------------------------- |
| `validators` | `Record<string, number>` | Map of validator IDs to their stake amounts |

**Example:**

```typescript
const validators = await client.pChain.getValidatorsAt({
  height: 1000001,
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Validators at height:", validators.validators);
```

**Links:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetvalidatorsat)
- [Related: getCurrentValidators](#getcurrentvalidators) - Get current validators
- [Related: getAllValidatorsAt](#getallvalidatorsat) - Get all validators at height
- [Related: getHeight](#getheight) - Get current height

---

### getAllValidatorsAt

Get all validators at a specific height across all Subnets and the Primary Network.

**Function Signature:**

```typescript
function getAllValidatorsAt(
  params: GetAllValidatorsAtParameters
): Promise<GetAllValidatorsAtReturnType>;

interface GetAllValidatorsAtParameters {
  height: number | "proposed";
}

interface GetAllValidatorsAtReturnType {
  validatorSets: Record<
    string,
    {
      validators: Array<{
        publicKey: string;
        weight: string;
        nodeIDs: string[];
      }>;
      totalWeight: string;
    }
  >;
}
```

**Parameters:**

| Name     | Type                   | Required | Description                                        |
| -------- | ---------------------- | -------- | -------------------------------------------------- |
| `height` | `number \| "proposed"` | Yes      | Platform-Chain height or "proposed" for proposervm height |

**Returns:**

| Type                           | Description           |
| ------------------------------ | --------------------- |
| `GetAllValidatorsAtReturnType` | Validator sets object |

**Return Object:**

| Property        | Type     | Description                                      |
| --------------- | -------- | ------------------------------------------------ |
| `validatorSets` | `object` | Map of Subnet IDs to their validator information |

**Note:** The public API (api.lux.network) only supports height within 1000 blocks from the Platform-Chain tip.

**Example:**

```typescript
// Get all validators at specific height
const validators = await client.pChain.getAllValidatorsAt({
  height: 1000001,
});

// Get validators at proposed height
const proposedValidators = await client.pChain.getAllValidatorsAt({
  height: "proposed",
});

console.log("Subnet IDs:", Object.keys(validators.validatorSets));
Object.entries(validators.validatorSets).forEach(([subnetID, set]) => {
  console.log(`Subnet ${subnetID}:`);
  console.log(`  Total weight: ${set.totalWeight}`);
  console.log(`  Validators: ${set.validators.length}`);
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetallvalidatorsat)
- [getCurrentValidators](#getcurrentvalidators) - Get current validators
- [getValidatorsAt](#getvalidatorsat) - Get validators at height for specific subnet

---

### sampleValidators

Sample validators from the specified Subnet.

**Function Signature:**

```typescript
function sampleValidators(
  params: SampleValidatorsParameters
): Promise<SampleValidatorsReturnType>;

interface SampleValidatorsParameters {
  samplingSize: number;
  subnetID?: string;
  pChainHeight?: number;
}

interface SampleValidatorsReturnType {
  validators: string[];
}
```

**Parameters:**

| Name           | Type     | Required | Description                             |
| -------------- | -------- | -------- | --------------------------------------- |
| `samplingSize` | `number` | Yes      | Number of validators to sample          |
| `subnetID`     | `string` | No       | Subnet ID (defaults to Primary Network) |
| `pChainHeight` | `number` | No       | Block height (defaults to current)      |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `SampleValidatorsReturnType` | Sampled validators object |

**Return Object:**

| Property     | Type       | Description                        |
| ------------ | ---------- | ---------------------------------- |
| `validators` | `string[]` | Array of sampled validator NodeIDs |

**Example:**

```typescript
const sampled = await client.pChain.sampleValidators({
  samplingSize: 5,
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Sampled validators:", sampled.validators);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformsamplevalidators)
- [getCurrentValidators](#getcurrentvalidators) - Get all current validators

---

## Block Operations

### getHeight

Get the height of the last accepted block.

**Function Signature:**

```typescript
function getHeight(): Promise<GetHeightReturnType>;

interface GetHeightReturnType {
  height: number;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                  | Description   |
| --------------------- | ------------- |
| `GetHeightReturnType` | Height object |

**Return Object:**

| Property | Type     | Description                  |
| -------- | -------- | ---------------------------- |
| `height` | `number` | Current Platform-Chain block height |

**Example:**

```typescript
const height = await client.pChain.getHeight();
console.log("Current Platform-Chain height:", height.height);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetheight)
- [getBlockByHeight](#getblockbyheight) - Get block by height
- [getProposedHeight](#getproposedheight) - Get proposed height

---

### getBlockByHeight

Get a block by its height.

**Function Signature:**

```typescript
function getBlockByHeight(
  params: GetBlockByHeightParameters
): Promise<GetBlockByHeightReturnType>;

interface GetBlockByHeightParameters {
  height: number;
  encoding?: "hex" | "json";
}

interface GetBlockByHeightReturnType {
  encoding: "hex" | "json";
  block: string | object;
}
```

**Parameters:**

| Name       | Type              | Required | Description                         |
| ---------- | ----------------- | -------- | ----------------------------------- |
| `height`   | `number`          | Yes      | Block height                        |
| `encoding` | `"hex" \| "json"` | No       | Encoding format (defaults to "hex") |

**Returns:**

| Type                         | Description       |
| ---------------------------- | ----------------- |
| `GetBlockByHeightReturnType` | Block data object |

**Return Object:**

| Property   | Type               | Description                                 |
| ---------- | ------------------ | ------------------------------------------- |
| `encoding` | `"hex" \| "json"`  | Encoding format used                        |
| `block`    | `string \| object` | Block data in the specified encoding format |

**Example:**

```typescript
const block = await client.pChain.getBlockByHeight({
  height: 12345,
  encoding: "hex",
});

console.log("Block data:", block.block);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetblockbyheight)
- [getBlock](#getblock) - Get block by ID
- [getHeight](#getheight) - Get current height

---

### getBlock

Get a block by its ID.

**Function Signature:**

```typescript
function getBlock(params: GetBlockParameters): Promise<GetBlockReturnType>;

interface GetBlockParameters {
  blockId: string;
  encoding?: "hex" | "json";
}

interface GetBlockReturnType {
  encoding: "hex" | "json";
  block: string | object;
}
```

**Parameters:**

| Name       | Type              | Required | Description                         |
| ---------- | ----------------- | -------- | ----------------------------------- |
| `blockId`  | `string`          | Yes      | Block ID in CB58 format             |
| `encoding` | `"hex" \| "json"` | No       | Encoding format (defaults to "hex") |

**Returns:**

| Type                 | Description       |
| -------------------- | ----------------- |
| `GetBlockReturnType` | Block data object |

**Return Object:**

| Property   | Type               | Description                                 |
| ---------- | ------------------ | ------------------------------------------- |
| `encoding` | `"hex" \| "json"`  | Encoding format used                        |
| `block`    | `string \| object` | Block data in the specified encoding format |

**Example:**

```typescript
const block = await client.pChain.getBlock({
  blockId: "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
  encoding: "hex",
});

console.log("Block:", block.block);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetblock)
- [getBlockByHeight](#getblockbyheight) - Get block by height

---

## Staking Operations

### getStake

Get the stake amount for a set of addresses.

**Function Signature:**

```typescript
function getStake(params: GetStakeParameters): Promise<GetStakeReturnType>;

interface GetStakeParameters {
  addresses: string[];
  subnetID: string;
}

interface GetStakeReturnType {
  stakeAmount: bigint;
}
```

**Parameters:**

| Name        | Type       | Required | Description       |
| ----------- | ---------- | -------- | ----------------- |
| `addresses` | `string[]` | Yes      | Platform-Chain addresses |
| `subnetID`  | `string`   | Yes      | Subnet ID         |

**Returns:**

| Type                 | Description         |
| -------------------- | ------------------- |
| `GetStakeReturnType` | Stake amount object |

**Return Object:**

| Property      | Type     | Description                          |
| ------------- | -------- | ------------------------------------ |
| `stakeAmount` | `bigint` | Total stake amount for the addresses |

**Example:**

```typescript
const stake = await client.pChain.getStake({
  addresses: ["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Stake amount:", stake.stakeAmount);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetstake)
- [getTotalStake](#gettotalstake) - Get total subnet stake
- [getMinStake](#getminstake) - Get minimum stake requirements

---

### getTotalStake

Get the total amount of stake for a Subnet.

**Function Signature:**

```typescript
function getTotalStake(
  params: GetTotalStakeParameters
): Promise<GetTotalStakeReturnType>;

interface GetTotalStakeParameters {
  subnetID: string;
}

interface GetTotalStakeReturnType {
  stake: bigint;
  weight: bigint;
}
```

**Parameters:**

| Name       | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `subnetID` | `string` | Yes      | Subnet ID   |

**Returns:**

| Type                      | Description        |
| ------------------------- | ------------------ |
| `GetTotalStakeReturnType` | Total stake object |

**Return Object:**

| Property | Type     | Description                       |
| -------- | -------- | --------------------------------- |
| `stake`  | `bigint` | Total stake amount for the subnet |
| `weight` | `bigint` | Total weight for the subnet       |

**Example:**

```typescript
const totalStake = await client.pChain.getTotalStake({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Total stake:", totalStake.stake);
console.log("Total weight:", totalStake.weight);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgettotalstake)
- [getStake](#getstake) - Get stake for addresses
- [getMinStake](#getminstake) - Get minimum stake

---

### getMinStake

Get the minimum stake required to validate or delegate.

**Function Signature:**

```typescript
function getMinStake(
  params: GetMinStakeParameters
): Promise<GetMinStakeReturnType>;

interface GetMinStakeParameters {
  subnetID: string;
}

interface GetMinStakeReturnType {
  minValidatorStake: bigint;
  minDelegatorStake: bigint;
}
```

**Parameters:**

| Name       | Type     | Required | Description |
| ---------- | -------- | -------- | ----------- |
| `subnetID` | `string` | Yes      | Subnet ID   |

**Returns:**

| Type                    | Description          |
| ----------------------- | -------------------- |
| `GetMinStakeReturnType` | Minimum stake object |

**Return Object:**

| Property            | Type     | Description                                  |
| ------------------- | -------- | -------------------------------------------- |
| `minValidatorStake` | `bigint` | Minimum stake required to become a validator |
| `minDelegatorStake` | `bigint` | Minimum stake required to delegate           |

**Example:**

```typescript
const minStake = await client.pChain.getMinStake({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Min validator stake:", minStake.minValidatorStake);
console.log("Min delegator stake:", minStake.minDelegatorStake);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetminstake)
- [getTotalStake](#gettotalstake) - Get total subnet stake

---

## Subnet Operations

### getSubnet

Get information about a subnet.

**Function Signature:**

```typescript
function getSubnet(params: GetSubnetParameters): Promise<GetSubnetReturnType>;

interface GetSubnetParameters {
  subnetID: string;
}

interface GetSubnetReturnType {
  isPermissioned: boolean;
  controlKeys: string[];
  threshold: string;
  locktime: string;
  subnetTransformationTxID: string;
  conversionID: string;
  managerChainID: string;
  managerAddress: string | null;
}
```

**Parameters:**

| Name       | Type     | Required | Description          |
| ---------- | -------- | -------- | -------------------- |
| `subnetID` | `string` | Yes      | The ID of the subnet |

**Returns:**

| Type                  | Description               |
| --------------------- | ------------------------- |
| `GetSubnetReturnType` | Subnet information object |

**Return Object:**

| Property                   | Type             | Description                          |
| -------------------------- | ---------------- | ------------------------------------ |
| `isPermissioned`           | `boolean`        | Whether the subnet is permissioned   |
| `controlKeys`              | `string[]`       | Control keys for the subnet          |
| `threshold`                | `string`         | Signature threshold                  |
| `locktime`                 | `string`         | Locktime for the subnet              |
| `subnetTransformationTxID` | `string`         | Subnet transformation transaction ID |
| `conversionID`             | `string`         | Conversion ID                        |
| `managerChainID`           | `string`         | Manager chain ID                     |
| `managerAddress`           | `string \| null` | Manager address (null if not set)    |

**Example:**

```typescript
const subnet = await client.pChain.getSubnet({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Is permissioned:", subnet.isPermissioned);
console.log("Control keys:", subnet.controlKeys);
console.log("Threshold:", subnet.threshold);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetsubnet)
- [getSubnets](#getsubnets) - Get multiple subnets

---

### getSubnets

Get information about multiple subnets.

**Function Signature:**

```typescript
function getSubnets(
  params: GetSubnetsParameters
): Promise<GetSubnetsReturnType>;

interface GetSubnetsParameters {
  ids: string[];
}

interface GetSubnetsReturnType {
  subnets: {
    id: string;
    controlKeys: string[];
    threshold: string;
  }[];
}
```

**Parameters:**

| Name  | Type       | Required | Description                  |
| ----- | ---------- | -------- | ---------------------------- |
| `ids` | `string[]` | Yes      | Array of subnet IDs to query |

**Returns:**

| Type                   | Description                |
| ---------------------- | -------------------------- |
| `GetSubnetsReturnType` | Subnets information object |

**Return Object:**

| Property  | Type    | Description                         |
| --------- | ------- | ----------------------------------- |
| `subnets` | `array` | Array of subnet information objects |

**Example:**

```typescript
const subnets = await client.pChain.getSubnets({
  ids: [
    "11111111111111111111111111111111LpoYY",
    "SubnetID-11111111111111111111111111111111LpoYY",
  ],
});

console.log("Number of subnets:", subnets.subnets.length);
subnets.subnets.forEach((subnet) => {
  console.log("Subnet ID:", subnet.id);
  console.log("Control keys:", subnet.controlKeys);
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetsubnets)
- [getSubnet](#getsubnet) - Get single subnet

---

### getStakingAssetID

Get the staking asset ID for a subnet.

**Function Signature:**

```typescript
function getStakingAssetID(
  params: GetStakingAssetIDParameters
): Promise<GetStakingAssetIDReturnType>;

interface GetStakingAssetIDParameters {
  subnetID: string;
}

interface GetStakingAssetIDReturnType {
  assetID: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description          |
| ---------- | -------- | -------- | -------------------- |
| `subnetID` | `string` | Yes      | The ID of the subnet |

**Returns:**

| Type                          | Description             |
| ----------------------------- | ----------------------- |
| `GetStakingAssetIDReturnType` | Staking asset ID object |

**Return Object:**

| Property  | Type     | Description                             |
| --------- | -------- | --------------------------------------- |
| `assetID` | `string` | Asset ID used for staking on the subnet |

**Example:**

```typescript
const stakingAsset = await client.pChain.getStakingAssetID({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Staking asset ID:", stakingAsset.assetID);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetstakingassetid)
- [getSubnet](#getsubnet) - Get subnet information

---

## Blockchain Operations

### getBlockchains

Get all the blockchains that exist (excluding the Platform-Chain).

**Function Signature:**

```typescript
function getBlockchains(): Promise<GetBlockchainsReturnType>;

interface GetBlockchainsReturnType {
  blockchains: {
    id: string;
    name: string;
    subnetID: string;
    vmID: string;
  }[];
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                       | Description             |
| -------------------------- | ----------------------- |
| `GetBlockchainsReturnType` | Blockchains list object |

**Return Object:**

| Property      | Type    | Description                             |
| ------------- | ------- | --------------------------------------- |
| `blockchains` | `array` | Array of blockchain information objects |

**Example:**

```typescript
const blockchains = await client.pChain.getBlockchains();

console.log("Number of blockchains:", blockchains.blockchains.length);

blockchains.blockchains.forEach((blockchain) => {
  console.log("Blockchain:", blockchain.name);
  console.log("  ID:", blockchain.id);
  console.log("  Subnet ID:", blockchain.subnetID);
  console.log("  VM ID:", blockchain.vmID);
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetblockchains)
- [getBlockchainStatus](#getblockchainstatus) - Get blockchain status

---

### getBlockchainStatus

Get the status of a blockchain.

**Function Signature:**

```typescript
function getBlockchainStatus(
  params: GetBlockchainStatusParameters
): Promise<GetBlockchainStatusReturnType>;

interface GetBlockchainStatusParameters {
  blockchainId: string;
}

interface GetBlockchainStatusReturnType {
  status: "Validating" | "Created" | "Preferred" | "Syncing" | "Unknown";
}
```

**Parameters:**

| Name           | Type     | Required | Description              |
| -------------- | -------- | -------- | ------------------------ |
| `blockchainId` | `string` | Yes      | The ID of the blockchain |

**Returns:**

| Type                            | Description              |
| ------------------------------- | ------------------------ |
| `GetBlockchainStatusReturnType` | Blockchain status object |

**Return Object:**

| Property | Type     | Description                                                                      |
| -------- | -------- | -------------------------------------------------------------------------------- |
| `status` | `string` | Blockchain status: "Validating", "Created", "Preferred", "Syncing", or "Unknown" |

**Status Values:**

- **Validating**: The blockchain is being validated by this node
- **Created**: The blockchain exists but isn't being validated by this node
- **Preferred**: The blockchain was proposed to be created and is likely to be created, but the transaction isn't yet accepted
- **Syncing**: This node is participating in the blockchain as a non-validating node
- **Unknown**: The blockchain either wasn't proposed or the proposal isn't preferred

**Example:**

```typescript
const status = await client.pChain.getBlockchainStatus({
  blockchainId: "11111111111111111111111111111111LpoYY",
});

console.log("Blockchain status:", status.status);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetblockchainstatus)
- [getBlockchains](#getblockchains) - Get all blockchains

---

## Transaction Operations

### getTx

Get a transaction by its ID.

**Function Signature:**

```typescript
function getTx(params: GetTxParameters): Promise<GetTxReturnType>;

interface GetTxParameters {
  txID: string;
  encoding?: "hex" | "json";
}

interface GetTxReturnType {
  encoding: "hex" | "json";
  tx: string | object;
}
```

**Parameters:**

| Name       | Type              | Required | Description                         |
| ---------- | ----------------- | -------- | ----------------------------------- |
| `txID`     | `string`          | Yes      | Transaction ID in CB58 format       |
| `encoding` | `"hex" \| "json"` | No       | Encoding format (defaults to "hex") |

**Returns:**

| Type              | Description             |
| ----------------- | ----------------------- |
| `GetTxReturnType` | Transaction data object |

**Return Object:**

| Property   | Type               | Description                                       |
| ---------- | ------------------ | ------------------------------------------------- |
| `encoding` | `"hex" \| "json"`  | Encoding format used                              |
| `tx`       | `string \| object` | Transaction data in the specified encoding format |

**Example:**

```typescript
const tx = await client.pChain.getTx({
  txID: "11111111111111111111111111111111LpoYY",
  encoding: "hex",
});

console.log("Transaction:", tx);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgettx)
- [getTxStatus](#gettxstatus) - Get transaction status
- [issueTx](#issuetx) - Issue a transaction

---

### getTxStatus

Get the status of a transaction.

**Function Signature:**

```typescript
function getTxStatus(
  params: GetTxStatusParameters
): Promise<GetTxStatusReturnType>;

interface GetTxStatusParameters {
  txID: string;
}

interface GetTxStatusReturnType {
  status: "Committed" | "Pending" | "Dropped" | "Unknown";
  reason?: string;
}
```

**Parameters:**

| Name   | Type     | Required | Description                   |
| ------ | -------- | -------- | ----------------------------- |
| `txID` | `string` | Yes      | Transaction ID in CB58 format |

**Returns:**

| Type                    | Description               |
| ----------------------- | ------------------------- |
| `GetTxStatusReturnType` | Transaction status object |

**Return Object:**

| Property | Type     | Description                                                         |
| -------- | -------- | ------------------------------------------------------------------- |
| `status` | `string` | Transaction status: "Committed", "Pending", "Dropped", or "Unknown" |
| `reason` | `string` | Optional reason for the status (if dropped)                         |

**Status Values:**

- **Committed**: The transaction is (or will be) accepted by every node
- **Pending**: The transaction is being voted on by this node
- **Dropped**: The transaction will never be accepted by any node in the network
- **Unknown**: The transaction hasn't been seen by this node

**Example:**

```typescript
const txStatus = await client.pChain.getTxStatus({
  txID: "11111111111111111111111111111111LpoYY",
});

console.log("Transaction status:", txStatus.status);
if (txStatus.reason) {
  console.log("Reason:", txStatus.reason);
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgettxstatus)
- [getTx](#gettx) - Get transaction details
- [issueTx](#issuetx) - Issue a transaction

---

### issueTx

Issue a transaction to the Platform Chain.

**Function Signature:**

```typescript
function issueTx(params: IssueTxParameters): Promise<IssueTxReturnType>;

interface IssueTxParameters {
  tx: string;
  encoding: "hex";
}

interface IssueTxReturnType {
  txID: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `tx`       | `string` | Yes      | Transaction bytes in hex format |
| `encoding` | `"hex"`  | Yes      | Encoding format (must be "hex") |

**Returns:**

| Type                | Description           |
| ------------------- | --------------------- |
| `IssueTxReturnType` | Transaction ID object |

**Return Object:**

| Property | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `txID`   | `string` | Transaction ID in CB58 format |

**Example:**

```typescript
const txID = await client.pChain.issueTx({
  tx: "0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0...",
  encoding: "hex",
});

console.log("Transaction issued:", txID.txID);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformissuetx)
- [getTx](#gettx) - Get transaction details
- [getTxStatus](#gettxstatus) - Get transaction status

---

## Block Operations

### getProposedHeight

Get the proposed height of the Platform-Chain.

**Function Signature:**

```typescript
function getProposedHeight(): Promise<GetProposedHeightReturnType>;

interface GetProposedHeightReturnType {
  height: number;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                          | Description            |
| ----------------------------- | ---------------------- |
| `GetProposedHeightReturnType` | Proposed height object |

**Return Object:**

| Property | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `height` | `number` | Proposed Platform-Chain block height |

**Example:**

```typescript
const proposedHeight = await client.pChain.getProposedHeight();
console.log("Proposed height:", proposedHeight.height);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetproposedheight)
- [getHeight](#getheight) - Get current accepted height

---

### getTimestamp

Get the current timestamp of the Platform-Chain.

**Function Signature:**

```typescript
function getTimestamp(): Promise<GetTimestampReturnType>;

interface GetTimestampReturnType {
  timestamp: string;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                     | Description      |
| ------------------------ | ---------------- |
| `GetTimestampReturnType` | Timestamp object |

**Return Object:**

| Property    | Type     | Description                          |
| ----------- | -------- | ------------------------------------ |
| `timestamp` | `string` | Current timestamp in ISO 8601 format |

**Example:**

```typescript
const timestamp = await client.pChain.getTimestamp();
console.log("Current timestamp:", timestamp.timestamp);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgettimestamp)
- [getHeight](#getheight) - Get current height

---

## Fee Operations

### getFeeConfig

Get the fee configuration for the Platform-Chain.

**Function Signature:**

```typescript
function getFeeConfig(): Promise<GetFeeConfigReturnType>;

interface GetFeeConfigReturnType {
  weights: [
    bandwidth: number,
    dbRead: number,
    dbWrite: number,
    compute: number,
  ];
  maxCapacity: bigint;
  maxPerSecond: bigint;
  targetPerSecond: bigint;
  minPrice: bigint;
  excessConversionConstant: bigint;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                     | Description              |
| ------------------------ | ------------------------ |
| `GetFeeConfigReturnType` | Fee configuration object |

**Return Object:**

| Property                   | Type     | Description                                        |
| -------------------------- | -------- | -------------------------------------------------- |
| `weights`                  | `array`  | Fee weights: [bandwidth, dbRead, dbWrite, compute] |
| `maxCapacity`              | `bigint` | Maximum capacity                                   |
| `maxPerSecond`             | `bigint` | Maximum per second                                 |
| `targetPerSecond`          | `bigint` | Target per second                                  |
| `minPrice`                 | `bigint` | Minimum price                                      |
| `excessConversionConstant` | `bigint` | Excess conversion constant                         |

**Example:**

```typescript
const feeConfig = await client.pChain.getFeeConfig();

console.log("Fee weights:", feeConfig.weights);
console.log("Max capacity:", feeConfig.maxCapacity);
console.log("Target per second:", feeConfig.targetPerSecond);
console.log("Min price:", feeConfig.minPrice);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetfeeconfig)
- [getFeeState](#getfeestate) - Get current fee state

---

### getFeeState

Get the current fee state of the Platform-Chain.

**Function Signature:**

```typescript
function getFeeState(): Promise<GetFeeStateReturnType>;

interface GetFeeStateReturnType {
  capacity: bigint;
  excess: bigint;
  price: bigint;
  timestamp: string;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                    | Description      |
| ----------------------- | ---------------- |
| `GetFeeStateReturnType` | Fee state object |

**Return Object:**

| Property    | Type     | Description                |
| ----------- | -------- | -------------------------- |
| `capacity`  | `bigint` | Current fee capacity       |
| `excess`    | `bigint` | Current fee excess         |
| `price`     | `bigint` | Current fee price          |
| `timestamp` | `string` | Timestamp of the fee state |

**Example:**

```typescript
const feeState = await client.pChain.getFeeState();

console.log("Fee capacity:", feeState.capacity);
console.log("Fee excess:", feeState.excess);
console.log("Fee price:", feeState.price);
console.log("Timestamp:", feeState.timestamp);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetfeestate)
- [getFeeConfig](#getfeeconfig) - Get fee configuration

---

## Supply Operations

### getCurrentSupply

Get the current supply of LUX tokens.

**Function Signature:**

```typescript
function getCurrentSupply(
  params?: GetCurrentSupplyParameters
): Promise<GetCurrentSupplyReturnType>;

interface GetCurrentSupplyParameters {
  subnetId?: string;
}

interface GetCurrentSupplyReturnType {
  supply: bigint;
}
```

**Parameters:**

| Name       | Type     | Required | Description                                        |
| ---------- | -------- | -------- | -------------------------------------------------- |
| `subnetId` | `string` | No       | Subnet ID (defaults to Primary Network if omitted) |

**Returns:**

| Type                         | Description   |
| ---------------------------- | ------------- |
| `GetCurrentSupplyReturnType` | Supply object |

**Return Object:**

| Property | Type     | Description                                    |
| -------- | -------- | ---------------------------------------------- |
| `supply` | `bigint` | Upper bound on the number of tokens that exist |

**Example:**

```typescript
// Get Primary Network supply
const supply = await client.pChain.getCurrentSupply();
console.log("Primary Network supply:", supply.supply);

// Get subnet-specific supply
const subnetSupply = await client.pChain.getCurrentSupply({
  subnetId: "11111111111111111111111111111111LpoYY",
});
console.log("Subnet supply:", subnetSupply.supply);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetcurrentsupply)
- [getBalance](#getbalance) - Get address balance

---

## Reward Operations

### getRewardUTXOs

Get the reward UTXOs for a transaction.

**Function Signature:**

```typescript
function getRewardUTXOs(
  params: GetRewardUTXOsParameters
): Promise<GetRewardUTXOsReturnType>;

interface GetRewardUTXOsParameters {
  txID: string;
  encoding?: "hex";
}

interface GetRewardUTXOsReturnType {
  numFetched: number;
  utxos: string[];
  encoding: "hex";
}
```

**Parameters:**

| Name       | Type     | Required | Description                         |
| ---------- | -------- | -------- | ----------------------------------- |
| `txID`     | `string` | Yes      | Transaction ID in CB58 format       |
| `encoding` | `"hex"`  | No       | Encoding format (defaults to "hex") |

**Returns:**

| Type                       | Description         |
| -------------------------- | ------------------- |
| `GetRewardUTXOsReturnType` | Reward UTXOs object |

**Return Object:**

| Property     | Type       | Description                              |
| ------------ | ---------- | ---------------------------------------- |
| `numFetched` | `number`   | Number of reward UTXOs fetched           |
| `utxos`      | `string[]` | Array of reward UTXO bytes (hex encoded) |
| `encoding`   | `"hex"`    | Encoding format used                     |

**Example:**

```typescript
const rewardUTXOs = await client.pChain.getRewardUTXOs({
  txID: "11111111111111111111111111111111LpoYY",
  encoding: "hex",
});

console.log("Reward UTXOs fetched:", rewardUTXOs.numFetched);
console.log("UTXOs:", rewardUTXOs.utxos);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetrewardutxos)
- [getUTXOs](#getutxos) - Get UTXOs for addresses

---

## L1 Validator Operations

### getL1Validator

Get information about an L1 validator.

**Function Signature:**

```typescript
function getL1Validator(
  params: GetL1ValidatorParameters
): Promise<GetL1ValidatorReturnType>;

interface GetL1ValidatorParameters {
  validationID: string;
}

interface GetL1ValidatorReturnType {
  subnetID: string;
  nodeID: string;
  publicKey: string;
  remainingBalanceOwner: {
    addresses: string[];
    locktime: string;
    threshold: string;
  };
  deactivationOwner: {
    addresses: string[];
    locktime: string;
    threshold: string;
  };
  startTime: bigint;
  weight: bigint;
  minNonce?: bigint;
  balance?: bigint;
  height?: bigint;
}
```

**Parameters:**

| Name           | Type     | Required | Description                                             |
| -------------- | -------- | -------- | ------------------------------------------------------- |
| `validationID` | `string` | Yes      | The ID for L1 subnet validator registration transaction |

**Returns:**

| Type                       | Description                     |
| -------------------------- | ------------------------------- |
| `GetL1ValidatorReturnType` | L1 validator information object |

**Return Object:**

| Property                | Type     | Description                                   |
| ----------------------- | -------- | --------------------------------------------- |
| `subnetID`              | `string` | L1 subnet ID this validator is validating     |
| `nodeID`                | `string` | Node ID of the validator                      |
| `publicKey`             | `string` | Compressed BLS public key of the validator    |
| `remainingBalanceOwner` | `object` | Owner that will receive any withdrawn balance |
| `deactivationOwner`     | `object` | Owner that can withdraw the balance           |
| `startTime`             | `bigint` | Unix timestamp when validator was added       |
| `weight`                | `bigint` | Weight used for consensus voting and ICM      |
| `minNonce`              | `bigint` | Minimum nonce for SetL1ValidatorWeightTx      |
| `balance`               | `bigint` | Current remaining balance for continuous fee  |
| `height`                | `bigint` | Height of the last accepted block             |

**Example:**

```typescript
const validator = await client.pChain.getL1Validator({
  validationID: "11111111111111111111111111111111LpoYY",
});

console.log("Subnet ID:", validator.subnetID);
console.log("Node ID:", validator.nodeID);
console.log("Weight:", validator.weight);
console.log("Start time:", validator.startTime);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformgetl1validator)
- [getCurrentValidators](#getcurrentvalidators) - Get current validators

---

## Chain Validation

### validatedBy

Get the subnet that validates a given blockchain.

**Function Signature:**

```typescript
function validatedBy(
  params: ValidatedByParameters
): Promise<ValidatedByReturnType>;

interface ValidatedByParameters {
  blockchainID: string;
}

interface ValidatedByReturnType {
  subnetID: string;
}
```

**Parameters:**

| Name           | Type     | Required | Description         |
| -------------- | -------- | -------- | ------------------- |
| `blockchainID` | `string` | Yes      | The blockchain's ID |

**Returns:**

| Type                    | Description      |
| ----------------------- | ---------------- |
| `ValidatedByReturnType` | Subnet ID object |

**Return Object:**

| Property   | Type     | Description                                    |
| ---------- | -------- | ---------------------------------------------- |
| `subnetID` | `string` | ID of the subnet that validates the blockchain |

**Example:**

```typescript
const validatedBy = await client.pChain.validatedBy({
  blockchainID: "11111111111111111111111111111111LpoYY",
});

console.log("Validated by subnet:", validatedBy.subnetID);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformvalidatedby)
- [validates](#validates) - Get blockchains validated by subnet

---

### validates

Get the IDs of the blockchains a subnet validates.

**Function Signature:**

```typescript
function validates(params: ValidatesParameters): Promise<ValidatesReturnType>;

interface ValidatesParameters {
  subnetID: string;
}

interface ValidatesReturnType {
  blockchainIDs: string[];
}
```

**Parameters:**

| Name       | Type     | Required | Description     |
| ---------- | -------- | -------- | --------------- |
| `subnetID` | `string` | Yes      | The subnet's ID |

**Returns:**

| Type                  | Description           |
| --------------------- | --------------------- |
| `ValidatesReturnType` | Blockchain IDs object |

**Return Object:**

| Property        | Type       | Description                                     |
| --------------- | ---------- | ----------------------------------------------- |
| `blockchainIDs` | `string[]` | Array of blockchain IDs validated by the subnet |

**Example:**

```typescript
const validates = await client.pChain.validates({
  subnetID: "11111111111111111111111111111111LpoYY",
});

console.log("Number of blockchains:", validates.blockchainIDs.length);
validates.blockchainIDs.forEach((blockchainID) => {
  console.log("Blockchain ID:", blockchainID);
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/p-chain#platformvalidates)
- [validatedBy](#validatedby) - Get subnet validating blockchain

## Next Steps

- **[Platform-Chain Wallet Methods](../wallet-methods/p-chain-wallet)** - Transaction preparation and signing
- **[Wallet Client](../../clients/wallet-client)** - Complete wallet operations
- **[Account Management](../../accounts)** - Account types and management


# Public Methods (/docs/tooling/avalanche-sdk/client/methods/public-methods/public)

---
title: Public Methods
description: Complete reference for Lux-specific public client methods
---

## Overview

The Lux Client extends viem's Public Client with Lux-specific methods for querying fee information, chain configuration, and active rules. These methods are available on both the main Lux Client and the LUExchange-Chain client.

## Fee Operations

### baseFee

Get the base fee for the next block on the LUExchange-Chain.

**Function Signature:**

```typescript
function baseFee(): Promise<string>;
```

**Parameters:**

No parameters required.

**Returns:**

| Type     | Description                                                    |
| -------- | -------------------------------------------------------------- |
| `string` | Base fee for the next block as hex string (e.g., "0x3b9aca00") |

**Example:**

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const baseFee = await client.baseFee();
console.log("Base fee:", baseFee); // "0x3b9aca00"
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#eth_basefee)
- [maxPriorityFeePerGas](#maxpriorityfeepergas) - Get max priority fee per gas

---

### maxPriorityFeePerGas

Get the maximum priority fee per gas for the next block.

**Function Signature:**

```typescript
function maxPriorityFeePerGas(): Promise<string>;
```

**Parameters:**

No parameters required.

**Returns:**

| Type     | Description                                                     |
| -------- | --------------------------------------------------------------- |
| `string` | Maximum priority fee per gas as hex string (e.g., "0x3b9aca00") |

**Example:**

```typescript
const maxPriorityFee = await client.maxPriorityFeePerGas();
console.log("Max priority fee per gas:", maxPriorityFee);

// Use in EIP-1559 transaction
const txHash = await walletClient.sendTransaction({
  to: "0x...",
  value: luxToWei(1),
  maxFeePerGas: baseFee + maxPriorityFee,
  maxPriorityFeePerGas: maxPriorityFee,
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#eth_maxpriorityfeepergas)
- [baseFee](#basefee) - Get base fee

---

### feeConfig

Get the fee configuration for a specific block. Returns fee settings and when they were last changed.

**Function Signature:**

```typescript
function feeConfig(params: FeeConfigParameters): Promise<FeeConfigReturnType>;

interface FeeConfigParameters {
  blk?: string; // Block number or hash, defaults to "latest"
}

interface FeeConfigReturnType {
  feeConfig: {
    [key: string]: string;
  };
  lastChangedAt: string;
}
```

**Parameters:**

| Name  | Type     | Required | Description                                             |
| ----- | -------- | -------- | ------------------------------------------------------- |
| `blk` | `string` | No       | Block number or hash (hex string), defaults to "latest" |

**Returns:**

| Type                  | Description              |
| --------------------- | ------------------------ |
| `FeeConfigReturnType` | Fee configuration object |

**Return Object:**

| Property        | Type     | Description                                |
| --------------- | -------- | ------------------------------------------ |
| `feeConfig`     | `object` | Fee configuration key-value pairs          |
| `lastChangedAt` | `string` | Timestamp when fee config was last changed |

**Example:**

```typescript
// Get fee config for latest block
const feeConfig = await client.feeConfig({});
console.log("Fee config:", feeConfig.feeConfig);
console.log("Last changed:", feeConfig.lastChangedAt);

// Get fee config for specific block
const blockFeeConfig = await client.feeConfig({ blk: "0x123456" });
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/subnet-evm#eth_feeconfig)
- [baseFee](#basefee) - Get base fee

---

## Chain Configuration

### getChainConfig

Get the chain configuration for the LUExchange-Chain, including fork blocks and Lux-specific upgrade timestamps.

**Function Signature:**

```typescript
function getChainConfig(): Promise<GetChainConfigReturnType>;

interface GetChainConfigReturnType {
  chainId: number;
  homesteadBlock: number;
  daoForkBlock: number;
  daoForkSupport: boolean;
  eip150Block: number;
  eip150Hash: string;
  eip155Block: number;
  eip158Block: number;
  byzantiumBlock: number;
  constantinopleBlock: number;
  petersburgBlock: number;
  istanbulBlock: number;
  muirGlacierBlock: number;
  apricotPhase1BlockTimestamp: number;
  apricotPhase2BlockTimestamp: number;
  apricotPhase3BlockTimestamp: number;
  apricotPhase4BlockTimestamp: number;
  apricotPhase5BlockTimestamp: number;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                       | Description                |
| -------------------------- | -------------------------- |
| `GetChainConfigReturnType` | Chain configuration object |

**Return Object:**

| Property                      | Type      | Description                       |
| ----------------------------- | --------- | --------------------------------- |
| `chainId`                     | `number`  | Chain ID                          |
| `homesteadBlock`              | `number`  | Homestead fork block              |
| `daoForkBlock`                | `number`  | DAO fork block                    |
| `daoForkSupport`              | `boolean` | DAO fork support flag             |
| `eip150Block`                 | `number`  | EIP-150 fork block                |
| `eip150Hash`                  | `string`  | EIP-150 fork hash                 |
| `eip155Block`                 | `number`  | EIP-155 fork block                |
| `eip158Block`                 | `number`  | EIP-158 fork block                |
| `byzantiumBlock`              | `number`  | Byzantium fork block              |
| `constantinopleBlock`         | `number`  | Constantinople fork block         |
| `petersburgBlock`             | `number`  | Petersburg fork block             |
| `istanbulBlock`               | `number`  | Istanbul fork block               |
| `muirGlacierBlock`            | `number`  | Muir Glacier fork block           |
| `apricotPhase1BlockTimestamp` | `number`  | Apricot Phase 1 upgrade timestamp |
| `apricotPhase2BlockTimestamp` | `number`  | Apricot Phase 2 upgrade timestamp |
| `apricotPhase3BlockTimestamp` | `number`  | Apricot Phase 3 upgrade timestamp |
| `apricotPhase4BlockTimestamp` | `number`  | Apricot Phase 4 upgrade timestamp |
| `apricotPhase5BlockTimestamp` | `number`  | Apricot Phase 5 upgrade timestamp |

**Example:**

```typescript
const chainConfig = await client.getChainConfig();
console.log("Chain ID:", chainConfig.chainId);
console.log("Apricot Phase 1:", chainConfig.apricotPhase1BlockTimestamp);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/c-chain#eth_getchainconfig)

---

## Active Rules

### getActiveRulesAt

Get the active rules (EIPs, precompiles) at a specific timestamp. Useful for determining which features are enabled at a given time.

**Function Signature:**

```typescript
function getActiveRulesAt(
  params: GetActiveRulesAtParameters
): Promise<GetActiveRulesAtReturnType>;

interface GetActiveRulesAtParameters {
  timestamp: string; // Unix timestamp as hex string or "latest"
}

interface GetActiveRulesAtReturnType {
  ethRules: Map<string, true>;
  luxRules: Map<string, true>;
  precompiles: Map<string, object>;
}
```

**Parameters:**

| Name        | Type     | Required | Description                                                     |
| ----------- | -------- | -------- | --------------------------------------------------------------- |
| `timestamp` | `string` | Yes      | Unix timestamp as hex string (e.g., "0x1234567890") or "latest" |

**Returns:**

| Type                         | Description         |
| ---------------------------- | ------------------- |
| `GetActiveRulesAtReturnType` | Active rules object |

**Return Object:**

| Property         | Type                  | Description                                  |
| ---------------- | --------------------- | -------------------------------------------- |
| `ethRules`       | `Map<string, true>`   | Active Ethereum rules (EIPs)                 |
| `luxRules` | `Map<string, true>`   | Active Lux-specific rules              |
| `precompiles`    | `Map<string, object>` | Active precompiles with their configurations |

**Example:**

```typescript
// Get active rules at current time
const activeRules = await client.getActiveRulesAt({
  timestamp: "latest",
});

console.log("Ethereum rules:", Array.from(activeRules.ethRules.keys()));
console.log("Lux rules:", Array.from(activeRules.luxRules.keys()));
console.log("Precompiles:", Array.from(activeRules.precompiles.keys()));

// Get active rules at specific timestamp
const historicalRules = await client.getActiveRulesAt({
  timestamp: "0x1234567890",
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/subnet-evm#eth_getactiverulesat)

---

## Viem Integration

The Lux Client extends viem's Public Client, providing access to all standard Ethereum RPC methods. For complete method reference, see:

- **[viem Documentation](https://viem.sh/docs)** - Complete EVM method reference
- **[viem Actions](https://viem.sh/docs/actions/public)** - Public client actions
- **[viem Utilities](https://viem.sh/docs/utilities)** - Utility functions

## Next Steps

- **[LUExchange-Chain Methods](c-chain)** - LUExchange-Chain-specific methods
- **[Wallet Client](../clients/wallet-client)** - Transaction operations
- **[Account Management](../../accounts)** - Account types and management


# Exchange-Chain Methods (/docs/tooling/avalanche-sdk/client/methods/public-methods/x-chain)

---
title: Exchange-Chain Methods
description: Complete reference for Exchange-Chain (Exchange Chain) methods
---

## Overview

The Exchange-Chain (Exchange Chain) is Lux's DAG-based chain designed for creating and trading digital smart assets. It handles asset creation, transfers, UTXO management, and provides the foundation for the Lux ecosystem. This reference covers all read-only Exchange-Chain operations available through the Lux Client SDK.

## Balance Operations

### getBalance

Get the balance of a specific asset controlled by a given address.

**Function Signature:**

```typescript
function getBalance(
  params: GetBalanceParameters
): Promise<GetBalanceReturnType>;

interface GetBalanceParameters {
  address: string;
  assetID: string;
}

interface GetBalanceReturnType {
  balance: bigint;
  utxoIDs: {
    txID: string;
    outputIndex: number;
  }[];
}
```

**Parameters:**

| Name      | Type     | Required | Description              |
| --------- | -------- | -------- | ------------------------ |
| `address` | `string` | Yes      | Exchange-Chain address to query |
| `assetID` | `string` | Yes      | Asset ID to query        |

**Returns:**

| Type                   | Description                |
| ---------------------- | -------------------------- |
| `GetBalanceReturnType` | Balance information object |

**Return Object:**

| Property  | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `balance` | `bigint` | Balance amount for the specified asset    |
| `utxoIDs` | `array`  | Array of UTXO IDs referencing the address |

**Example:**

```typescript
import { createLuxClient } from "@lux-sdk/client";
import { lux } from "@lux-sdk/client/chains";

const client = createLuxClient({
  chain: lux,
  transport: { type: "http" },
});

const balance = await client.xChain.getBalance({
  address: "X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
  assetID: "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", // LUX
});

console.log("Balance:", balance.balance);
console.log("UTXO IDs:", balance.utxoIDs);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetbalance)
- [getAllBalances](#getallbalances) - Get balances for all assets
- [getUTXOs](#getutxos) - Get UTXOs for addresses

---

### getAllBalances

Get the balances of all assets controlled by given addresses.

**Function Signature:**

```typescript
function getAllBalances(
  params: GetAllBalancesParameters
): Promise<GetAllBalancesReturnType>;

interface GetAllBalancesParameters {
  addresses: string[];
}

interface GetAllBalancesReturnType {
  balances: Array<{
    assetID: string;
    balance: bigint;
  }>;
}
```

**Parameters:**

| Name        | Type       | Required | Description                         |
| ----------- | ---------- | -------- | ----------------------------------- |
| `addresses` | `string[]` | Yes      | Array of Exchange-Chain addresses to query |

**Returns:**

| Type                       | Description           |
| -------------------------- | --------------------- |
| `GetAllBalancesReturnType` | Balances array object |

**Return Object:**

| Property   | Type    | Description                                       |
| ---------- | ------- | ------------------------------------------------- |
| `balances` | `array` | Array of balance objects with assetID and balance |

**Example:**

```typescript
const allBalances = await client.xChain.getAllBalances({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
});

// Iterate over all assets
allBalances.balances.forEach(({ assetID, balance }) => {
  console.log(`Asset ${assetID}: ${balance}`);
});
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetallbalances)
- [getBalance](#getbalance) - Get balance for specific asset
- [getAssetDescription](#getassetdescription) - Get asset information

---

## Asset Operations

### getAssetDescription

Get information about an asset.

**Function Signature:**

```typescript
function getAssetDescription(
  params: GetAssetDescriptionParameters
): Promise<GetAssetDescriptionReturnType>;

interface GetAssetDescriptionParameters {
  assetID: string;
}

interface GetAssetDescriptionReturnType {
  assetID: string;
  name: string;
  symbol: string;
  denomination: number;
}
```

**Parameters:**

| Name      | Type     | Required | Description |
| --------- | -------- | -------- | ----------- |
| `assetID` | `string` | Yes      | Asset ID    |

**Returns:**

| Type                            | Description              |
| ------------------------------- | ------------------------ |
| `GetAssetDescriptionReturnType` | Asset information object |

**Return Object:**

| Property       | Type     | Description                                   |
| -------------- | -------- | --------------------------------------------- |
| `assetID`      | `string` | Asset ID                                      |
| `name`         | `string` | Asset name                                    |
| `symbol`       | `string` | Asset symbol                                  |
| `denomination` | `number` | Asset denomination (number of decimal places) |

**Example:**

```typescript
const asset = await client.xChain.getAssetDescription({
  assetID: "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
});

console.log("Asset name:", asset.name);
console.log("Asset symbol:", asset.symbol);
console.log("Denomination:", asset.denomination);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetassetdescription)
- [getBalance](#getbalance) - Get balance for this asset

---

## Block Operations

### getHeight

Get the current block height of the Exchange-Chain.

**Function Signature:**

```typescript
function getHeight(): Promise<GetHeightReturnType>;

interface GetHeightReturnType {
  height: number;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                  | Description   |
| --------------------- | ------------- |
| `GetHeightReturnType` | Height object |

**Return Object:**

| Property | Type     | Description                  |
| -------- | -------- | ---------------------------- |
| `height` | `number` | Current Exchange-Chain block height |

**Example:**

```typescript
const height = await client.xChain.getHeight();
console.log("Current Exchange-Chain height:", height.height);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetheight)
- [getBlockByHeight](#getblockbyheight) - Get block at height

---

### getBlockByHeight

Get a block by its height.

**Function Signature:**

```typescript
function getBlockByHeight(
  params: GetBlockByHeightParameters
): Promise<GetBlockByHeightReturnType>;

interface GetBlockByHeightParameters {
  height: number;
  encoding?: "hex" | "json";
}

interface GetBlockByHeightReturnType {
  encoding: "hex" | "json";
  block: string | object;
}
```

**Parameters:**

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `height`   | `number`          | Yes      | Block height                         |
| `encoding` | `"hex" \| "json"` | No       | Encoding format (defaults to "json") |

**Returns:**

| Type                         | Description       |
| ---------------------------- | ----------------- |
| `GetBlockByHeightReturnType` | Block data object |

**Return Object:**

| Property   | Type               | Description                                 |
| ---------- | ------------------ | ------------------------------------------- |
| `encoding` | `"hex" \| "json"`  | Encoding format used                        |
| `block`    | `string \| object` | Block data in the specified encoding format |

**Example:**

```typescript
const block = await client.xChain.getBlockByHeight({
  height: 12345,
  encoding: "hex",
});

console.log("Block data:", block.block);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetblockbyheight)
- [getBlock](#getblock) - Get block by ID
- [getHeight](#getheight) - Get current height

---

### getBlock

Get a block by its ID.

**Function Signature:**

```typescript
function getBlock(params: GetBlockParameters): Promise<GetBlockReturnType>;

interface GetBlockParameters {
  blockId: string;
  encoding?: "hex" | "json";
}

interface GetBlockReturnType {
  encoding: "hex" | "json";
  block: string | object;
}
```

**Parameters:**

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `blockId`  | `string`          | Yes      | Block ID in CB58 format              |
| `encoding` | `"hex" \| "json"` | No       | Encoding format (defaults to "json") |

**Returns:**

| Type                 | Description       |
| -------------------- | ----------------- |
| `GetBlockReturnType` | Block data object |

**Return Object:**

| Property   | Type               | Description                                 |
| ---------- | ------------------ | ------------------------------------------- |
| `encoding` | `"hex" \| "json"`  | Encoding format used                        |
| `block`    | `string \| object` | Block data in the specified encoding format |

**Example:**

```typescript
const block = await client.xChain.getBlock({
  blockId: "block-id-in-cb58-format",
  encoding: "hex",
});

console.log("Block:", block.block);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetblock)
- [getBlockByHeight](#getblockbyheight) - Get block by height

---

## Transaction Operations

### getTx

Get a transaction by its ID.

**Function Signature:**

```typescript
function getTx(params: GetTxParameters): Promise<GetTxReturnType>;

interface GetTxParameters {
  txID: string;
  encoding?: "hex" | "json";
}

interface GetTxReturnType {
  encoding: "hex" | "json";
  tx: string | object;
}
```

**Parameters:**

| Name       | Type              | Required | Description                          |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `txID`     | `string`          | Yes      | Transaction ID in CB58 format        |
| `encoding` | `"hex" \| "json"` | No       | Encoding format (defaults to "json") |

**Returns:**

| Type              | Description             |
| ----------------- | ----------------------- |
| `GetTxReturnType` | Transaction data object |

**Return Object:**

| Property   | Type               | Description                                       |
| ---------- | ------------------ | ------------------------------------------------- |
| `encoding` | `"hex" \| "json"`  | Encoding format used                              |
| `tx`       | `string \| object` | Transaction data in the specified encoding format |

**Example:**

```typescript
const tx = await client.xChain.getTx({
  txID: "transaction-id",
  encoding: "hex",
});

console.log("Transaction:", tx.tx);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgettx)
- [getTxStatus](#gettxstatus) - Get transaction status
- [issueTx](#issuetx) - Submit transaction

---

### getTxStatus

Get the status of a transaction.

**Function Signature:**

```typescript
function getTxStatus(
  params: GetTxStatusParameters
): Promise<GetTxStatusReturnType>;

interface GetTxStatusParameters {
  txID: string;
  includeReason?: boolean | true;
}

interface GetTxStatusReturnType {
  status: "Accepted" | "Processing" | "Rejected" | "Unknown";
  reason?: string;
}
```

**Parameters:**

| Name            | Type              | Required | Description                                  |
| --------------- | ----------------- | -------- | -------------------------------------------- |
| `txID`          | `string`          | Yes      | Transaction ID in CB58 format                |
| `includeReason` | `boolean \| true` | No       | Whether to include the reason for the status |

**Returns:**

| Type                    | Description               |
| ----------------------- | ------------------------- |
| `GetTxStatusReturnType` | Transaction status object |

**Return Object:**

| Property | Type     | Description                                                            |
| -------- | -------- | ---------------------------------------------------------------------- |
| `status` | `string` | Transaction status: "Accepted", "Processing", "Rejected", or "Unknown" |
| `reason` | `string` | Optional reason for the status (if rejected)                           |

**Status Values:**

- **Accepted**: Transaction has been accepted and included in a block
- **Processing**: Transaction is being processed
- **Rejected**: Transaction was rejected
- **Unknown**: Transaction status cannot be determined

**Example:**

```typescript
const status = await client.xChain.getTxStatus({
  txID: "transaction-id",
});

if (status.status === "Accepted") {
  console.log("Transaction accepted!");
} else if (status.status === "Rejected") {
  console.log("Transaction rejected");
  if (status.reason) {
    console.log("Reason:", status.reason);
  }
} else {
  console.log("Transaction status:", status.status);
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgettxstatus)
- [getTx](#gettx) - Get transaction details

---

### getTxFee

Get the transaction fee for the Exchange-Chain.

**Function Signature:**

```typescript
function getTxFee(): Promise<GetTxFeeReturnType>;

interface GetTxFeeReturnType {
  txFee: number;
  createAssetTxFee: number;
}
```

**Parameters:**

No parameters required.

**Returns:**

| Type                 | Description            |
| -------------------- | ---------------------- |
| `GetTxFeeReturnType` | Transaction fee object |

**Return Object:**

| Property           | Type     | Description                  |
| ------------------ | -------- | ---------------------------- |
| `txFee`            | `number` | Standard transaction fee     |
| `createAssetTxFee` | `number` | Fee for creating a new asset |

**Example:**

```typescript
const fees = await client.xChain.getTxFee();

console.log("Standard transaction fee:", fees.txFee);
console.log("Create asset fee:", fees.createAssetTxFee);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgettxfee)

---

## UTXO Operations

### getUTXOs

Get the UTXOs controlled by a set of addresses.

**Function Signature:**

```typescript
function getUTXOs(params: GetUTXOsParameters): Promise<GetUTXOsReturnType>;

interface GetUTXOsParameters {
  addresses: string[];
  sourceChain?: string;
  limit?: number;
  startIndex?: {
    address: string;
    utxo: string;
  };
  encoding?: "hex";
}

interface GetUTXOsReturnType {
  numFetched: number;
  utxos: string[];
  endIndex: {
    address: string;
    utxo: string;
  };
  sourceChain?: string;
  encoding: "hex";
}
```

**Parameters:**

| Name          | Type                                | Required | Description                                     |
| ------------- | ----------------------------------- | -------- | ----------------------------------------------- |
| `addresses`   | `string[]`                          | Yes      | Array of Exchange-Chain addresses                      |
| `sourceChain` | `string`                            | No       | Source chain ID (e.g., "P" for Platform-Chain)         |
| `limit`       | `number`                            | No       | Maximum number of UTXOs to return               |
| `startIndex`  | `{ address: string; utxo: string }` | No       | Pagination cursor for next page                 |
| `encoding`    | `"hex"`                             | No       | Encoding format (can only be "hex" if provided) |

**Returns:**

| Type                 | Description               |
| -------------------- | ------------------------- |
| `GetUTXOsReturnType` | UTXO data with pagination |

**Return Object:**

| Property      | Type                                | Description                              |
| ------------- | ----------------------------------- | ---------------------------------------- |
| `numFetched`  | `number`                            | Number of UTXOs fetched in this response |
| `utxos`       | `string[]`                          | Array of UTXO bytes (hex encoded)        |
| `endIndex`    | `{ address: string; utxo: string }` | Pagination cursor for fetching next page |
| `sourceChain` | `string`                            | Source chain ID (if specified)           |
| `encoding`    | `"hex"`                             | Encoding format used                     |

**Example:**

```typescript
// Get first page
const utxos = await client.xChain.getUTXOs({
  addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
  limit: 100,
});

console.log("Number of UTXOs:", utxos.numFetched);

// Get next page if needed
if (utxos.endIndex) {
  const moreUTXOs = await client.xChain.getUTXOs({
    addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
    startIndex: utxos.endIndex,
    limit: 100,
  });
}
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetutxos)
- [getBalance](#getbalance) - Get balance summary

---

## Transaction Submission

### issueTx

Issue a transaction to the Exchange-Chain.

**Function Signature:**

```typescript
function issueTx(params: IssueTxParameters): Promise<IssueTxReturnType>;

interface IssueTxParameters {
  tx: string;
  encoding: "hex";
}

interface IssueTxReturnType {
  txID: string;
}
```

**Parameters:**

| Name       | Type     | Required | Description                     |
| ---------- | -------- | -------- | ------------------------------- |
| `tx`       | `string` | Yes      | Transaction bytes in hex format |
| `encoding` | `"hex"`  | Yes      | Encoding format (must be "hex") |

**Returns:**

| Type                | Description           |
| ------------------- | --------------------- |
| `IssueTxReturnType` | Transaction ID object |

**Return Object:**

| Property | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `txID`   | `string` | Transaction ID in CB58 format |

**Example:**

```typescript
const txID = await client.xChain.issueTx({
  tx: "0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0...",
  encoding: "hex",
});

console.log("Transaction ID:", txID.txID);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmissuetx)
- [getTxStatus](#gettxstatus) - Check transaction status

---

## Genesis Operations

### buildGenesis

Build a genesis block for a custom blockchain.

**Function Signature:**

```typescript
function buildGenesis(
  params: BuildGenesisParameters
): Promise<BuildGenesisReturnType>;

interface BuildGenesisParameters {
  networkID: number;
  genesisData: {
    name: string;
    symbol: string;
    denomination: number;
    initialState: {
      fixedCap: {
        amount: number;
        addresses: string[];
      };
    };
  };
  encoding: "hex";
}

interface BuildGenesisReturnType {
  bytes: string;
  encoding: "hex";
}
```

**Parameters:**

| Name          | Type     | Required | Description                                 |
| ------------- | -------- | -------- | ------------------------------------------- |
| `networkID`   | `number` | Yes      | Network ID                                  |
| `genesisData` | `object` | Yes      | Genesis block data with asset configuration |
| `encoding`    | `"hex"`  | Yes      | Encoding format (must be "hex")             |

**Returns:**

| Type                     | Description                |
| ------------------------ | -------------------------- |
| `BuildGenesisReturnType` | Genesis block bytes object |

**Return Object:**

| Property   | Type     | Description                       |
| ---------- | -------- | --------------------------------- |
| `bytes`    | `string` | Genesis block bytes in hex format |
| `encoding` | `"hex"`  | Encoding format used              |

**Example:**

```typescript
const genesis = await client.xChain.buildGenesis({
  networkID: 16,
  genesisData: {
    name: "myFixedCapAsset",
    symbol: "MFCA",
    denomination: 0,
    initialState: {
      fixedCap: {
        amount: 100000,
        addresses: ["X-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"],
      },
    },
  },
  encoding: "hex",
});

console.log("Genesis bytes:", genesis.bytes);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmbuildgenesis)

---

## Next Steps

- **[Exchange-Chain Wallet Methods](../wallet-methods/x-chain-wallet)** - Transaction preparation and signing
- **[Wallet Client](../../clients/wallet-client)** - Complete wallet operations
- **[Account Management](../../accounts)** - Account types and management


# LUExchange-Chain Wallet Methods (/docs/tooling/avalanche-sdk/client/methods/wallet-methods/c-chain-wallet)

---
title: LUExchange-Chain Wallet Methods
description: Complete reference for LUExchange-Chain atomic transaction methods
---

## Overview

The LUExchange-Chain Wallet Methods provide transaction preparation capabilities for atomic cross-chain transfers between the LUExchange-Chain and other Lux chains (Platform-Chain and Exchange-Chain). These methods handle the export and import of native LUX via atomic transactions.

**Access:** `walletClient.cChain`

## prepareExportTxn

Prepare a transaction to export LUX from LUExchange-Chain to another chain (Platform-Chain or Exchange-Chain).

**Function Signature:**

```typescript
function prepareExportTxn(
  params: PrepareExportTxnParameters
): Promise<PrepareExportTxnReturnType>;

interface PrepareExportTxnParameters {
  destinationChain: "P" | "X";
  fromAddress: string;
  exportedOutput: {
    addresses: string[];
    amount: bigint;
    locktime?: bigint;
    threshold?: number;
  };
  context?: Context;
}

interface PrepareExportTxnReturnType {
  tx: UnsignedTx;
  exportTx: ExportTx;
  chainAlias: "C";
}
```

**Parameters:**

| Name               | Type         | Required | Description                                         |
| ------------------ | ------------ | -------- | --------------------------------------------------- |
| `destinationChain` | `"P" \| "X"` | Yes      | Chain alias to export funds to (Platform-Chain or Exchange-Chain) |
| `fromAddress`      | `string`     | Yes      | EVM address to export funds from                    |
| `exportedOutput`   | `object`     | Yes      | Consolidated exported output (UTXO)                 |
| `context`          | `Context`    | No       | Optional context for the transaction                |

**Exported Output Object:**

| Name        | Type       | Required | Description                                                        |
| ----------- | ---------- | -------- | ------------------------------------------------------------------ |
| `addresses` | `string[]` | Yes      | Addresses who can sign the consuming of this UTXO                  |
| `amount`    | `bigint`   | Yes      | Amount in nano LUX held by this exported output                   |
| `locktime`  | `bigint`   | No       | Timestamp in seconds after which this UTXO can be consumed         |
| `threshold` | `number`   | No       | Threshold of `addresses`' signatures required to consume this UTXO |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `PrepareExportTxnReturnType` | Export transaction object |

**Return Object:**

| Property     | Type         | Description                     |
| ------------ | ------------ | ------------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction        |
| `exportTx`   | `ExportTx`   | The export transaction instance |
| `chainAlias` | `"C"`        | The chain alias                 |

**Example:**

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToNanoLux } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Export from LUExchange-Chain to Platform-Chain
const exportTx = await walletClient.cChain.prepareExportTxn({
  destinationChain: "P",
  fromAddress: account.getEVMAddress(),
  exportedOutput: {
    addresses: [account.getXPAddress("P")],
    amount: luxToNanoLux(0.001),
  },
});

// Sign and send
const { txHash } = await walletClient.sendXPTransaction({
  txOrTxHex: exportTx,
  chainAlias: "C",
});

console.log("Export transaction hash:", txHash);
```

**Related:**

- [prepareImportTxn](#prepareimporttxn) - Import to LUExchange-Chain
- [Wallet send method](./wallet#send) - Simplified cross-chain transfers
- [getAtomicTxStatus](../public-methods/c-chain#getatomictxstatus) - Check transaction status

---

## prepareImportTxn

Prepare a transaction to import LUX from another chain (Platform-Chain or Exchange-Chain) to LUExchange-Chain.

**Function Signature:**

```typescript
function prepareImportTxn(
  params: PrepareImportTxnParameters
): Promise<PrepareImportTxnReturnType>;

interface PrepareImportTxnParameters {
  account?: LuxAccount | Address | undefined;
  sourceChain: "P" | "X";
  toAddress: string;
  fromAddresses?: string[];
  utxos?: Utxo[];
  context?: Context;
}

interface PrepareImportTxnReturnType {
  tx: UnsignedTx;
  importTx: ImportTx;
  chainAlias: "C";
}
```

**Parameters:**

| Name            | Type                          | Required | Description                                                                     |
| --------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------- |
| `account`       | `LuxAccount \| Address` | No       | Account to use for the transaction                                              |
| `sourceChain`   | `"P" \| "X"`                  | Yes      | Chain alias to import funds from (Platform-Chain or Exchange-Chain)                           |
| `toAddress`     | `string`                      | Yes      | EVM address to import funds to                                                  |
| `fromAddresses` | `string[]`                    | No       | Addresses to import funds from (auto-fetched if not provided)                   |
| `utxos`         | `Utxo[]`                      | No       | UTXOs to use as inputs (must be in atomic memory, auto-fetched if not provided) |
| `context`       | `Context`                     | No       | Optional context for the transaction                                            |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `PrepareImportTxnReturnType` | Import transaction object |

**Return Object:**

| Property     | Type         | Description                     |
| ------------ | ------------ | ------------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction        |
| `importTx`   | `ImportTx`   | The import transaction instance |
| `chainAlias` | `"C"`        | The chain alias                 |

**Example:**

```typescript
const importTx = await walletClient.cChain.prepareImportTxn({
  sourceChain: "P",
  toAddress: account.getEVMAddress(),
  fromAddresses: [account.getXPAddress("P")],
});

// Sign and send
const { txHash } = await walletClient.sendXPTransaction({
  txOrTxHex: importTx,
  chainAlias: "C",
});

console.log("Import transaction hash:", txHash);
```

**Related:**

- [prepareExportTxn](#prepareexporttxn) - Export from LUExchange-Chain
- [getAtomicTxStatus](../public-methods/c-chain#getatomictxstatus) - Check transaction status

---

## Complete Cross-Chain Transfer Workflow

### Export from LUExchange-Chain to Platform-Chain

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToNanoLux } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// 1. Export from LUExchange-Chain
const exportTx = await walletClient.cChain.prepareExportTxn({
  destinationChain: "P",
  fromAddress: account.getEVMAddress(),
  exportedOutput: {
    addresses: [account.getXPAddress("P")],
    amount: luxToNanoLux(1.0),
  },
});

// 2. Sign and send export transaction
const { txHash: exportTxHash } = await walletClient.sendXPTransaction({
  txOrTxHex: exportTx,
  chainAlias: "C",
});

// 3. Wait for export to be committed
await walletClient.waitForTxn({
  txHash: exportTxHash,
  chainAlias: "C",
});

console.log("Export completed:", exportTxHash);

// 4. Import to Platform-Chain
const importTx = await walletClient.pChain.prepareImportTxn({
  sourceChain: "C",
  toAddresses: [account.getXPAddress("P")],
});

const { txHash: importTxHash } = await walletClient.sendXPTransaction({
  txOrTxHex: importTx,
  chainAlias: "P",
});

console.log("Import completed:", importTxHash);
```

---

## Next Steps

- **[Wallet Methods](./wallet)** - General wallet operations
- **[Platform-Chain Wallet Methods](./p-chain-wallet)** - Platform-Chain transaction preparation
- **[Exchange-Chain Wallet Methods](./x-chain-wallet)** - Exchange-Chain transaction preparation
- **[Account Management](../accounts)** - Account types and management


# Platform-Chain Wallet Methods (/docs/tooling/avalanche-sdk/client/methods/wallet-methods/p-chain-wallet)

---
title: Platform-Chain Wallet Methods
description: Complete reference for Platform-Chain transaction preparation methods
---

## Overview

The Platform-Chain Wallet Methods provide transaction preparation capabilities for the Platform Chain. These methods allow you to create unsigned transactions for various operations including base transfers, validator operations, delegator operations, subnet management, and cross-chain transfers.

**Access:** `walletClient.pChain`

## prepareBaseTxn

Prepare a base Platform-Chain transaction for transferring LUX.

**Function Signature:**

```typescript
function prepareBaseTxn(
  params: PrepareBaseTxnParameters
): Promise<PrepareBaseTxnReturnType>;

interface PrepareBaseTxnParameters {
  outputs?: Output[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface Output {
  addresses: string[];
  amount: bigint;
  assetId?: string;
  locktime?: bigint;
  threshold?: number;
}

interface PrepareBaseTxnReturnType {
  tx: UnsignedTx;
  baseTx: BaseTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type       | Required | Description                                   |
| ----------------- | ---------- | -------- | --------------------------------------------- |
| `outputs`         | `Output[]` | No       | Array of outputs to send funds to             |
| `fromAddresses`   | `string[]` | No       | Addresses to send funds from                  |
| `changeAddresses` | `string[]` | No       | Addresses to receive change                   |
| `utxos`           | `Utxo[]`   | No       | UTXOs to use as inputs                        |
| `memo`            | `string`   | No       | Transaction memo                              |
| `minIssuanceTime` | `bigint`   | No       | Earliest time this transaction can be issued  |
| `context`         | `Context`  | No       | Transaction context (auto-fetched if omitted) |

**Output Object:**

| Name        | Type       | Required | Description                                                        |
| ----------- | ---------- | -------- | ------------------------------------------------------------------ |
| `addresses` | `string[]` | Yes      | Addresses who can sign the consuming of this UTXO                  |
| `amount`    | `bigint`   | Yes      | Amount in nano LUX                                                |
| `assetId`   | `string`   | No       | Asset ID of the UTXO                                               |
| `locktime`  | `bigint`   | No       | Timestamp in seconds after which this UTXO can be consumed         |
| `threshold` | `number`   | No       | Threshold of `addresses`' signatures required to consume this UTXO |

**Returns:**

| Type                       | Description             |
| -------------------------- | ----------------------- |
| `PrepareBaseTxnReturnType` | Base transaction object |

**Return Object:**

| Property     | Type         | Description                   |
| ------------ | ------------ | ----------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction      |
| `baseTx`     | `BaseTx`     | The base transaction instance |
| `chainAlias` | `"P"`        | The chain alias               |

**Example:**

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToNanoLux } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

const unsignedTx = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
      amount: luxToNanoLux(1),
    },
  ],
});

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: unsignedTx.tx,
  chainAlias: "P",
});

const { txHash } = await walletClient.sendXPTransaction({
  txOrTxHex: signedTx.signedTxHex,
  chainAlias: "P",
});

console.log("Transaction hash:", txHash);
```

**Related:**

- [prepareExportTxn](#prepareexporttxn) - Cross-chain exports
- [prepareImportTxn](#prepareimporttxn) - Cross-chain imports

---

## prepareAddPermissionlessValidatorTxn

Prepare a transaction to add a permissionless validator to the Primary Network.

**Function Signature:**

```typescript
function prepareAddPermissionlessValidatorTxn(
  params: PrepareAddPermissionlessValidatorTxnParameters
): Promise<PrepareAddPermissionlessValidatorTxnReturnType>;

interface PrepareAddPermissionlessValidatorTxnParameters {
  nodeId: string;
  stakeInLux: bigint;
  end: bigint;
  rewardAddresses: string[];
  delegatorRewardAddresses: string[];
  delegatorRewardPercentage: number;
  publicKey?: string;
  signature?: string;
  threshold?: number;
  locktime?: bigint;
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareAddPermissionlessValidatorTxnReturnType {
  tx: UnsignedTx;
  addPermissionlessValidatorTx: AddPermissionlessValidatorTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name                        | Type       | Required | Description                                                                       |
| --------------------------- | ---------- | -------- | --------------------------------------------------------------------------------- |
| `nodeId`                    | `string`   | Yes      | Node ID of the validator being added                                              |
| `stakeInLux`               | `bigint`   | Yes      | Amount of LUX to stake (in nano LUX)                                            |
| `end`                       | `bigint`   | Yes      | Unix time in seconds when validator will be removed                               |
| `rewardAddresses`           | `string[]` | Yes      | Addresses which will receive validator rewards                                    |
| `delegatorRewardAddresses`  | `string[]` | Yes      | Addresses which will receive delegator fee rewards                                |
| `delegatorRewardPercentage` | `number`   | Yes      | Percentage of delegator rewards as delegation fee (2-100, up to 3 decimal places) |
| `publicKey`                 | `string`   | No       | BLS public key (in hex format)                                                    |
| `signature`                 | `string`   | No       | BLS signature (in hex format)                                                     |
| `threshold`                 | `number`   | No       | Number of signatures required to spend reward UTXO (default: 1)                   |
| `locktime`                  | `bigint`   | No       | Unix timestamp after which reward UTXO can be spent (default: 0)                  |
| `fromAddresses`             | `string[]` | No       | Addresses to send funds from                                                      |
| `changeAddresses`           | `string[]` | No       | Addresses to receive change                                                       |
| `utxos`                     | `Utxo[]`   | No       | UTXOs to use as inputs                                                            |
| `memo`                      | `string`   | No       | Transaction memo                                                                  |
| `minIssuanceTime`           | `bigint`   | No       | Earliest time this transaction can be issued                                      |
| `context`                   | `Context`  | No       | Transaction context (auto-fetched if omitted)                                     |

**Returns:**

| Type                                             | Description                      |
| ------------------------------------------------ | -------------------------------- |
| `PrepareAddPermissionlessValidatorTxnReturnType` | Add validator transaction object |

**Return Object:**

| Property                       | Type                           | Description                            |
| ------------------------------ | ------------------------------ | -------------------------------------- |
| `tx`                           | `UnsignedTx`                   | The unsigned transaction               |
| `addPermissionlessValidatorTx` | `AddPermissionlessValidatorTx` | The add validator transaction instance |
| `chainAlias`                   | `"P"`                          | The chain alias                        |

**Example:**

```typescript
import { luxToNanoLux } from "@lux-sdk/client/utils";

const validatorTx =
  await walletClient.pChain.prepareAddPermissionlessValidatorTxn({
    nodeId: "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
    stakeInLux: luxToNanoLux(2000),
    end: BigInt(1716441600),
    rewardAddresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
    delegatorRewardAddresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
    delegatorRewardPercentage: 2.5,
    threshold: 1,
  });

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: validatorTx.tx,
  chainAlias: "P",
});

const { txHash } = await walletClient.sendXPTransaction({
  txOrTxHex: signedTx.signedTxHex,
  chainAlias: "P",
});
```

**Related:**

- [prepareAddSubnetValidatorTxn](#prepareaddsubnetvalidatortxn) - Add to subnet
- [prepareAddPermissionlessDelegatorTxn](#prepareaddpermissionlessdelegatortxn) - Add delegator

---

## prepareAddPermissionlessDelegatorTxn

Prepare a transaction to add a permissionless delegator to a validator.

**Function Signature:**

```typescript
function prepareAddPermissionlessDelegatorTxn(
  params: PrepareAddPermissionlessDelegatorTxnParameters
): Promise<PrepareAddPermissionlessDelegatorTxnReturnType>;

interface PrepareAddPermissionlessDelegatorTxnParameters {
  nodeId: string;
  stakeInLux: bigint;
  end: bigint;
  rewardAddresses: string[];
  threshold?: number;
  locktime?: bigint;
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareAddPermissionlessDelegatorTxnReturnType {
  tx: UnsignedTx;
  addPermissionlessDelegatorTx: AddPermissionlessDelegatorTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type       | Required | Description                                                      |
| ----------------- | ---------- | -------- | ---------------------------------------------------------------- |
| `nodeId`          | `string`   | Yes      | Node ID of the validator to delegate to                          |
| `stakeInLux`     | `bigint`   | Yes      | Amount of LUX to stake (in nano LUX)                           |
| `end`             | `bigint`   | Yes      | Unix time in seconds when delegation stops                       |
| `rewardAddresses` | `string[]` | Yes      | Addresses which will receive rewards                             |
| `threshold`       | `number`   | No       | Number of signatures required to spend reward UTXO (default: 1)  |
| `locktime`        | `bigint`   | No       | Unix timestamp after which reward UTXO can be spent (default: 0) |
| `fromAddresses`   | `string[]` | No       | Addresses to send funds from                                     |
| `changeAddresses` | `string[]` | No       | Addresses to receive change                                      |
| `utxos`           | `Utxo[]`   | No       | UTXOs to use as inputs                                           |
| `memo`            | `string`   | No       | Transaction memo                                                 |
| `minIssuanceTime` | `bigint`   | No       | Earliest time this transaction can be issued                     |
| `context`         | `Context`  | No       | Transaction context (auto-fetched if omitted)                    |

**Returns:**

| Type                                             | Description                      |
| ------------------------------------------------ | -------------------------------- |
| `PrepareAddPermissionlessDelegatorTxnReturnType` | Add delegator transaction object |

**Return Object:**

| Property                       | Type                           | Description                            |
| ------------------------------ | ------------------------------ | -------------------------------------- |
| `tx`                           | `UnsignedTx`                   | The unsigned transaction               |
| `addPermissionlessDelegatorTx` | `AddPermissionlessDelegatorTx` | The add delegator transaction instance |
| `chainAlias`                   | `"P"`                          | The chain alias                        |

**Example:**

```typescript
const delegatorTx =
  await walletClient.pChain.prepareAddPermissionlessDelegatorTxn({
    nodeId: "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
    stakeInLux: luxToNanoLux(25),
    end: BigInt(1716441600),
    rewardAddresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
    threshold: 1,
  });
```

**Related:**

- [prepareAddPermissionlessValidatorTxn](#prepareaddpermissionlessvalidatortxn) - Add validator

---

## prepareExportTxn

Prepare a transaction to export LUX from Platform-Chain to another chain.

**Function Signature:**

```typescript
function prepareExportTxn(
  params: PrepareExportTxnParameters
): Promise<PrepareExportTxnReturnType>;

interface PrepareExportTxnParameters {
  destinationChain: "X" | "C";
  exportedOutputs: Output[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareExportTxnReturnType {
  tx: UnsignedTx;
  exportTx: ExportTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name               | Type         | Required | Description                                   |
| ------------------ | ------------ | -------- | --------------------------------------------- |
| `destinationChain` | `"X" \| "C"` | Yes      | Chain alias to export funds to                |
| `exportedOutputs`  | `Output[]`   | Yes      | Outputs to export                             |
| `fromAddresses`    | `string[]`   | No       | Addresses to send funds from                  |
| `changeAddresses`  | `string[]`   | No       | Addresses to receive change                   |
| `utxos`            | `Utxo[]`     | No       | UTXOs to use as inputs                        |
| `memo`             | `string`     | No       | Transaction memo                              |
| `minIssuanceTime`  | `bigint`     | No       | Earliest time this transaction can be issued  |
| `context`          | `Context`    | No       | Transaction context (auto-fetched if omitted) |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `PrepareExportTxnReturnType` | Export transaction object |

**Return Object:**

| Property     | Type         | Description                     |
| ------------ | ------------ | ------------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction        |
| `exportTx`   | `ExportTx`   | The export transaction instance |
| `chainAlias` | `"P"`        | The chain alias                 |

**Example:**

```typescript
const exportTx = await walletClient.pChain.prepareExportTxn({
  destinationChain: "C",
  exportedOutputs: [
    {
      addresses: [account.getEVMAddress()],
      amount: luxToNanoLux(0.001),
    },
  ],
});

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: exportTx.tx,
  chainAlias: "P",
});

const { txHash } = await walletClient.sendXPTransaction({
  txOrTxHex: signedTx.signedTxHex,
  chainAlias: "P",
});
```

**Related:**

- [prepareImportTxn](#prepareimporttxn) - Import to Platform-Chain
- [Wallet send method](./wallet#send) - Simplified cross-chain transfers

---

## prepareImportTxn

Prepare a transaction to import LUX from another chain to Platform-Chain.

**Function Signature:**

```typescript
function prepareImportTxn(
  params: PrepareImportTxnParameters
): Promise<PrepareImportTxnReturnType>;

interface PrepareImportTxnParameters {
  sourceChain: "X" | "C";
  importedOutput: ImportedOutput;
  fromAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface ImportedOutput {
  addresses: string[];
  locktime?: bigint;
  threshold?: number;
}

interface PrepareImportTxnReturnType {
  tx: UnsignedTx;
  importTx: ImportTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type             | Required | Description                                     |
| ----------------- | ---------------- | -------- | ----------------------------------------------- |
| `sourceChain`     | `"X" \| "C"`     | Yes      | Chain alias to import funds from                |
| `importedOutput`  | `ImportedOutput` | Yes      | Consolidated imported output from atomic memory |
| `fromAddresses`   | `string[]`       | No       | Addresses to send funds from                    |
| `utxos`           | `Utxo[]`         | No       | UTXOs to use as inputs                          |
| `memo`            | `string`         | No       | Transaction memo                                |
| `minIssuanceTime` | `bigint`         | No       | Earliest time this transaction can be issued    |
| `context`         | `Context`        | No       | Transaction context (auto-fetched if omitted)   |

**Imported Output Object:**

| Name        | Type       | Required | Description                                                                         |
| ----------- | ---------- | -------- | ----------------------------------------------------------------------------------- |
| `addresses` | `string[]` | Yes      | Addresses who can sign the consuming of this UTXO                                   |
| `locktime`  | `bigint`   | No       | Timestamp in seconds after which this UTXO can be consumed                          |
| `threshold` | `number`   | No       | Number of signatures required out of total `addresses` to spend the imported output |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `PrepareImportTxnReturnType` | Import transaction object |

**Return Object:**

| Property     | Type         | Description                     |
| ------------ | ------------ | ------------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction        |
| `importTx`   | `ImportTx`   | The import transaction instance |
| `chainAlias` | `"P"`        | The chain alias                 |

**Example:**

```typescript
const importTx = await walletClient.pChain.prepareImportTxn({
  sourceChain: "C",
  importedOutput: {
    addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
    threshold: 1,
  },
});

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: importTx.tx,
  chainAlias: "P",
});

const { txHash } = await walletClient.sendXPTransaction({
  txOrTxHex: signedTx.signedTxHex,
  chainAlias: "P",
});
```

**Related:**

- [prepareExportTxn](#prepareexporttxn) - Export from Platform-Chain

---

## prepareAddSubnetValidatorTxn

Prepare a transaction to add a validator to a subnet.

**Function Signature:**

```typescript
function prepareAddSubnetValidatorTxn(
  params: PrepareAddSubnetValidatorTxnParameters
): Promise<PrepareAddSubnetValidatorTxnReturnType>;

interface PrepareAddSubnetValidatorTxnParameters {
  subnetId: string;
  nodeId: string;
  weight: bigint;
  end: bigint;
  subnetAuth: readonly number[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareAddSubnetValidatorTxnReturnType {
  tx: UnsignedTx;
  addSubnetValidatorTx: AddSubnetValidatorTx;
  subnetOwners: PChainOwner;
  subnetAuth: number[];
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type                | Required | Description                                                                |
| ----------------- | ------------------- | -------- | -------------------------------------------------------------------------- |
| `subnetId`        | `string`            | Yes      | Subnet ID to add the validator to                                          |
| `nodeId`          | `string`            | Yes      | Node ID of the validator being added                                       |
| `weight`          | `bigint`            | Yes      | Weight of the validator used during consensus                              |
| `end`             | `bigint`            | Yes      | End timestamp in seconds after which validator will be removed             |
| `subnetAuth`      | `readonly number[]` | Yes      | Array of indices from subnet's owners array who will sign this transaction |
| `fromAddresses`   | `string[]`          | No       | Addresses to send funds from                                               |
| `changeAddresses` | `string[]`          | No       | Addresses to receive change                                                |
| `utxos`           | `Utxo[]`            | No       | UTXOs to use as inputs                                                     |
| `memo`            | `string`            | No       | Transaction memo                                                           |
| `minIssuanceTime` | `bigint`            | No       | Earliest time this transaction can be issued                               |
| `context`         | `Context`           | No       | Transaction context (auto-fetched if omitted)                              |

**Returns:**

| Type                                     | Description                             |
| ---------------------------------------- | --------------------------------------- |
| `PrepareAddSubnetValidatorTxnReturnType` | Add subnet validator transaction object |

**Return Object:**

| Property               | Type                   | Description                                   |
| ---------------------- | ---------------------- | --------------------------------------------- |
| `tx`                   | `UnsignedTx`           | The unsigned transaction                      |
| `addSubnetValidatorTx` | `AddSubnetValidatorTx` | The add subnet validator transaction instance |
| `subnetOwners`         | `PChainOwner`          | The subnet owners                             |
| `subnetAuth`           | `number[]`             | Array of indices from subnet's owners array   |
| `chainAlias`           | `"P"`                  | The chain alias                               |

**Example:**

```typescript
const addSubnetValidatorTx =
  await walletClient.pChain.prepareAddSubnetValidatorTxn({
    subnetId: "2b175hLJhGdj3CzgXNUHXDPVY3wQo3y3VWqPjKpF5vK",
    nodeId: "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
    weight: BigInt(1000000),
    end: BigInt(1716441600),
    subnetAuth: [0, 1],
  });
```

**Related:**

- [prepareRemoveSubnetValidatorTxn](#prepareremovesubnetvalidatortxn) - Remove subnet validator

---

## prepareRemoveSubnetValidatorTxn

Prepare a transaction to remove a validator from a subnet.

**Function Signature:**

```typescript
function prepareRemoveSubnetValidatorTxn(
  params: PrepareRemoveSubnetValidatorTxnParameters
): Promise<PrepareRemoveSubnetValidatorTxnReturnType>;

interface PrepareRemoveSubnetValidatorTxnParameters {
  subnetId: string;
  nodeId: string;
  subnetAuth: readonly number[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareRemoveSubnetValidatorTxnReturnType {
  tx: UnsignedTx;
  removeSubnetValidatorTx: RemoveSubnetValidatorTx;
  subnetOwners: PChainOwner;
  subnetAuth: number[];
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type                | Required | Description                                                                |
| ----------------- | ------------------- | -------- | -------------------------------------------------------------------------- |
| `subnetId`        | `string`            | Yes      | Subnet ID to remove the validator from                                     |
| `nodeId`          | `string`            | Yes      | Node ID of the validator being removed                                     |
| `subnetAuth`      | `readonly number[]` | Yes      | Array of indices from subnet's owners array who will sign this transaction |
| `fromAddresses`   | `string[]`          | No       | Addresses to send funds from                                               |
| `changeAddresses` | `string[]`          | No       | Addresses to receive change                                                |
| `utxos`           | `Utxo[]`            | No       | UTXOs to use as inputs                                                     |
| `memo`            | `string`            | No       | Transaction memo                                                           |
| `minIssuanceTime` | `bigint`            | No       | Earliest time this transaction can be issued                               |
| `context`         | `Context`           | No       | Transaction context (auto-fetched if omitted)                              |

**Returns:**

| Type                                        | Description                                |
| ------------------------------------------- | ------------------------------------------ |
| `PrepareRemoveSubnetValidatorTxnReturnType` | Remove subnet validator transaction object |

**Return Object:**

| Property                  | Type                      | Description                                      |
| ------------------------- | ------------------------- | ------------------------------------------------ |
| `tx`                      | `UnsignedTx`              | The unsigned transaction                         |
| `removeSubnetValidatorTx` | `RemoveSubnetValidatorTx` | The remove subnet validator transaction instance |
| `subnetOwners`            | `PChainOwner`             | The subnet owners                                |
| `subnetAuth`              | `number[]`                | Array of indices from subnet's owners array      |
| `chainAlias`              | `"P"`                     | The chain alias                                  |

**Example:**

```typescript
const removeSubnetValidatorTx =
  await walletClient.pChain.prepareRemoveSubnetValidatorTxn({
    subnetId: "2b175hLJhGdj3CzgXNUHXDPVY3wQo3y3VWqPjKpF5vK",
    nodeId: "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
    subnetAuth: [0, 1],
  });
```

**Related:**

- [prepareAddSubnetValidatorTxn](#prepareaddsubnetvalidatortxn) - Add subnet validator

---

## prepareCreateSubnetTxn

Prepare a transaction to create a new subnet.

**Function Signature:**

```typescript
function prepareCreateSubnetTxn(
  params: PrepareCreateSubnetTxnParameters
): Promise<PrepareCreateSubnetTxnReturnType>;

interface PrepareCreateSubnetTxnParameters {
  subnetOwners: SubnetOwners;
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface SubnetOwners {
  addresses: string[];
  threshold?: number;
  locktime?: bigint;
}

interface PrepareCreateSubnetTxnReturnType {
  tx: UnsignedTx;
  createSubnetTx: CreateSubnetTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type           | Required | Description                                   |
| ----------------- | -------------- | -------- | --------------------------------------------- |
| `subnetOwners`    | `SubnetOwners` | Yes      | Subnet owners configuration                   |
| `fromAddresses`   | `string[]`     | No       | Addresses to send funds from                  |
| `changeAddresses` | `string[]`     | No       | Addresses to receive change                   |
| `utxos`           | `Utxo[]`       | No       | UTXOs to use as inputs                        |
| `memo`            | `string`       | No       | Transaction memo                              |
| `minIssuanceTime` | `bigint`       | No       | Earliest time this transaction can be issued  |
| `context`         | `Context`      | No       | Transaction context (auto-fetched if omitted) |

**Subnet Owners Object:**

| Name        | Type       | Required | Description                                                                              |
| ----------- | ---------- | -------- | ---------------------------------------------------------------------------------------- |
| `addresses` | `string[]` | Yes      | List of unique addresses (must be sorted lexicographically)                              |
| `threshold` | `number`   | No       | Number of unique signatures required to spend the output (must be ≤ length of addresses) |
| `locktime`  | `bigint`   | No       | Unix timestamp after which the output can be spent                                       |

**Returns:**

| Type                               | Description                      |
| ---------------------------------- | -------------------------------- |
| `PrepareCreateSubnetTxnReturnType` | Create subnet transaction object |

**Return Object:**

| Property         | Type             | Description                            |
| ---------------- | ---------------- | -------------------------------------- |
| `tx`             | `UnsignedTx`     | The unsigned transaction               |
| `createSubnetTx` | `CreateSubnetTx` | The create subnet transaction instance |
| `chainAlias`     | `"P"`            | The chain alias                        |

**Example:**

```typescript
const createSubnetTx = await walletClient.pChain.prepareCreateSubnetTxn({
  subnetOwners: {
    addresses: [
      "P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz",
      "P-testnet1y8zrxh9cvdny0e8n8n4n7h4q4h4q4h4q4h4q4h",
    ],
    threshold: 2,
  },
});
```

**Related:**

- [prepareCreateChainTxn](#preparecreatechaintxn) - Create chain on subnet

---

## prepareCreateChainTxn

Prepare a transaction to create a new blockchain on a subnet.

**Function Signature:**

```typescript
function prepareCreateChainTxn(
  params: PrepareCreateChainTxnParameters
): Promise<PrepareCreateChainTxnReturnType>;

interface PrepareCreateChainTxnParameters {
  subnetId: string;
  vmId: string;
  chainName: string;
  genesisData: Record<string, unknown>;
  subnetAuth: readonly number[];
  fxIds?: readonly string[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareCreateChainTxnReturnType {
  tx: UnsignedTx;
  createChainTx: CreateChainTx;
  subnetOwners: PChainOwner;
  subnetAuth: number[];
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type                      | Required | Description                                                                |
| ----------------- | ------------------------- | -------- | -------------------------------------------------------------------------- |
| `subnetId`        | `string`                  | Yes      | Subnet ID to create the chain on                                           |
| `vmId`            | `string`                  | Yes      | VM ID of the chain being created                                           |
| `chainName`       | `string`                  | Yes      | Name of the chain being created                                            |
| `genesisData`     | `Record<string, unknown>` | Yes      | Genesis JSON data of the chain being created                               |
| `subnetAuth`      | `readonly number[]`       | Yes      | Array of indices from subnet's owners array who will sign this transaction |
| `fxIds`           | `readonly string[]`       | No       | Array of FX IDs to be added to the chain                                   |
| `fromAddresses`   | `string[]`                | No       | Addresses to send funds from                                               |
| `changeAddresses` | `string[]`                | No       | Addresses to receive change                                                |
| `utxos`           | `Utxo[]`                  | No       | UTXOs to use as inputs                                                     |
| `memo`            | `string`                  | No       | Transaction memo                                                           |
| `minIssuanceTime` | `bigint`                  | No       | Earliest time this transaction can be issued                               |
| `context`         | `Context`                 | No       | Transaction context (auto-fetched if omitted)                              |

**Returns:**

| Type                              | Description                     |
| --------------------------------- | ------------------------------- |
| `PrepareCreateChainTxnReturnType` | Create chain transaction object |

**Return Object:**

| Property        | Type            | Description                                 |
| --------------- | --------------- | ------------------------------------------- |
| `tx`            | `UnsignedTx`    | The unsigned transaction                    |
| `createChainTx` | `CreateChainTx` | The create chain transaction instance       |
| `subnetOwners`  | `PChainOwner`   | The subnet owners                           |
| `subnetAuth`    | `number[]`      | Array of indices from subnet's owners array |
| `chainAlias`    | `"P"`           | The chain alias                             |

**Example:**

```typescript
const createChainTx = await walletClient.pChain.prepareCreateChainTxn({
  subnetId: "2b175hLJhGdj3CzgXNUHXDPVY3wQo3y3VWqPjKpF5vK",
  vmId: "xvm",
  chainName: "MyCustomChain",
  genesisData: {
    // Genesis configuration
  },
  subnetAuth: [0, 1],
});
```

**Related:**

- [prepareCreateSubnetTxn](#preparecreatesubnettxn) - Create subnet

---

## prepareConvertSubnetToL1Txn

Prepare a transaction to convert a subnet to an L1 (Layer 1) blockchain.

**Function Signature:**

```typescript
function prepareConvertSubnetToL1Txn(
  params: PrepareConvertSubnetToL1TxnParameters
): Promise<PrepareConvertSubnetToL1TxnReturnType>;

interface PrepareConvertSubnetToL1TxnParameters {
  subnetId: string;
  blockchainId: string;
  managerContractAddress: string;
  validators: L1Validator[];
  subnetAuth: readonly number[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface L1Validator {
  nodeId: string;
  nodePoP: {
    publicKey: string;
    proofOfPossession: string;
  };
  weight: bigint;
  initialBalanceInLux: bigint;
  remainingBalanceOwner: PChainOwnerJSON;
  deactivationOwner: PChainOwnerJSON;
}

interface PrepareConvertSubnetToL1TxnReturnType {
  tx: UnsignedTx;
  convertSubnetToL1Tx: ConvertSubnetToL1Tx;
  subnetOwners: PChainOwner;
  subnetAuth: number[];
  chainAlias: "P";
}
```

**Parameters:**

| Name                     | Type                | Required | Description                                                                |
| ------------------------ | ------------------- | -------- | -------------------------------------------------------------------------- |
| `subnetId`               | `string`            | Yes      | Subnet ID of the subnet to convert                                         |
| `blockchainId`           | `string`            | Yes      | Blockchain ID of the L1 where validator manager contract is deployed       |
| `managerContractAddress` | `string`            | Yes      | Address of the validator manager contract                                  |
| `validators`             | `L1Validator[]`     | Yes      | Initial set of L1 validators after conversion                              |
| `subnetAuth`             | `readonly number[]` | Yes      | Array of indices from subnet's owners array who will sign this transaction |
| `fromAddresses`          | `string[]`          | No       | Addresses to send funds from                                               |
| `changeAddresses`        | `string[]`          | No       | Addresses to receive change                                                |
| `utxos`                  | `Utxo[]`            | No       | UTXOs to use as inputs                                                     |
| `memo`                   | `string`            | No       | Transaction memo                                                           |
| `minIssuanceTime`        | `bigint`            | No       | Earliest time this transaction can be issued                               |
| `context`                | `Context`           | No       | Transaction context (auto-fetched if omitted)                              |

**L1 Validator Object:**

| Name                        | Type              | Description                                                              |
| --------------------------- | ----------------- | ------------------------------------------------------------------------ |
| `nodeId`                    | `string`          | Node ID of the validator                                                 |
| `nodePoP.publicKey`         | `string`          | Public key of the validator                                              |
| `nodePoP.proofOfPossession` | `string`          | Proof of possession of the public key                                    |
| `weight`                    | `bigint`          | Weight of the validator on the L1 used during consensus participation    |
| `initialBalanceInLux`      | `bigint`          | Initial balance in nano LUX required for paying contiguous fee          |
| `remainingBalanceOwner`     | `PChainOwnerJSON` | Owner information for remaining balance if validator is removed/disabled |
| `deactivationOwner`         | `PChainOwnerJSON` | Owner information which can remove or disable the validator              |

**Returns:**

| Type                                    | Description                             |
| --------------------------------------- | --------------------------------------- |
| `PrepareConvertSubnetToL1TxnReturnType` | Convert subnet to L1 transaction object |

**Return Object:**

| Property              | Type                  | Description                                   |
| --------------------- | --------------------- | --------------------------------------------- |
| `tx`                  | `UnsignedTx`          | The unsigned transaction                      |
| `convertSubnetToL1Tx` | `ConvertSubnetToL1Tx` | The convert subnet to L1 transaction instance |
| `subnetOwners`        | `PChainOwner`         | The subnet owners                             |
| `subnetAuth`          | `number[]`            | Array of indices from subnet's owners array   |
| `chainAlias`          | `"P"`                 | The chain alias                               |

**Example:**

```typescript
const convertSubnetToL1Tx =
  await walletClient.pChain.prepareConvertSubnetToL1Txn({
    subnetId: "2b175hLJhGdj3CzgXNUHXDPVY3wQo3y3VWqPjKpF5vK",
    blockchainId: "2oYMBNV4eNHyqk2fjjV5nVwDzxvbmovtDAOwPJCTc9wqg8k9t",
    managerContractAddress: "0x1234567890123456789012345678901234567890",
    validators: [
      {
        nodeId: "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
        nodePoP: {
          publicKey: "0x...",
          proofOfPossession: "0x...",
        },
        weight: BigInt(1000000),
        initialBalanceInLux: luxToNanoLux(1000),
        remainingBalanceOwner: {
          addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
          threshold: 1,
        },
        deactivationOwner: {
          addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
          threshold: 1,
        },
      },
    ],
    subnetAuth: [0, 1],
  });
```

---

## prepareRegisterL1ValidatorTxn

Prepare a transaction to register an L1 validator.

**Function Signature:**

```typescript
function prepareRegisterL1ValidatorTxn(
  params: PrepareRegisterL1ValidatorTxnParameters
): Promise<PrepareRegisterL1ValidatorTxnReturnType>;

interface PrepareRegisterL1ValidatorTxnParameters {
  initialBalanceInLux: bigint;
  blsSignature: string;
  message: string;
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareRegisterL1ValidatorTxnReturnType {
  tx: UnsignedTx;
  registerL1ValidatorTx: RegisterL1ValidatorTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name                   | Type       | Required | Description                                                                                  |
| ---------------------- | ---------- | -------- | -------------------------------------------------------------------------------------------- |
| `initialBalanceInLux` | `bigint`   | Yes      | Initial balance in nano LUX required for paying contiguous fee                              |
| `blsSignature`         | `string`   | Yes      | BLS signature of the validator                                                               |
| `message`              | `string`   | Yes      | Signed warp message hex with `AddressedCall` payload containing `RegisterL1ValidatorMessage` |
| `fromAddresses`        | `string[]` | No       | Addresses to send funds from                                                                 |
| `changeAddresses`      | `string[]` | No       | Addresses to receive change                                                                  |
| `utxos`                | `Utxo[]`   | No       | UTXOs to use as inputs                                                                       |
| `memo`                 | `string`   | No       | Transaction memo                                                                             |
| `minIssuanceTime`      | `bigint`   | No       | Earliest time this transaction can be issued                                                 |
| `context`              | `Context`  | No       | Transaction context (auto-fetched if omitted)                                                |

**Returns:**

| Type                                      | Description                              |
| ----------------------------------------- | ---------------------------------------- |
| `PrepareRegisterL1ValidatorTxnReturnType` | Register L1 validator transaction object |

**Return Object:**

| Property                | Type                    | Description                                    |
| ----------------------- | ----------------------- | ---------------------------------------------- |
| `tx`                    | `UnsignedTx`            | The unsigned transaction                       |
| `registerL1ValidatorTx` | `RegisterL1ValidatorTx` | The register L1 validator transaction instance |
| `chainAlias`            | `"P"`                   | The chain alias                                |

**Example:**

```typescript
const registerL1ValidatorTx =
  await walletClient.pChain.prepareRegisterL1ValidatorTxn({
    initialBalanceInLux: luxToNanoLux(1000),
    blsSignature: "0x...",
    message: "0x...",
  });
```

---

## prepareDisableL1ValidatorTxn

Prepare a transaction to disable an L1 validator.

**Function Signature:**

```typescript
function prepareDisableL1ValidatorTxn(
  params: PrepareDisableL1ValidatorTxnParameters
): Promise<PrepareDisableL1ValidatorTxnReturnType>;

interface PrepareDisableL1ValidatorTxnParameters {
  validationId: string;
  disableAuth: number[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareDisableL1ValidatorTxnReturnType {
  tx: UnsignedTx;
  disableL1ValidatorTx: DisableL1ValidatorTx;
  disableOwners: PChainOwner;
  disableAuth: number[];
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type       | Required | Description                                                                              |
| ----------------- | ---------- | -------- | ---------------------------------------------------------------------------------------- |
| `validationId`    | `string`   | Yes      | Validation ID of the L1 validator                                                        |
| `disableAuth`     | `number[]` | Yes      | Array of indices from L1 validator's disable owners array who will sign this transaction |
| `fromAddresses`   | `string[]` | No       | Addresses to send funds from                                                             |
| `changeAddresses` | `string[]` | No       | Addresses to receive change                                                              |
| `utxos`           | `Utxo[]`   | No       | UTXOs to use as inputs                                                                   |
| `memo`            | `string`   | No       | Transaction memo                                                                         |
| `minIssuanceTime` | `bigint`   | No       | Earliest time this transaction can be issued                                             |
| `context`         | `Context`  | No       | Transaction context (auto-fetched if omitted)                                            |

**Returns:**

| Type                                     | Description                             |
| ---------------------------------------- | --------------------------------------- |
| `PrepareDisableL1ValidatorTxnReturnType` | Disable L1 validator transaction object |

**Return Object:**

| Property               | Type                   | Description                                   |
| ---------------------- | ---------------------- | --------------------------------------------- |
| `tx`                   | `UnsignedTx`           | The unsigned transaction                      |
| `disableL1ValidatorTx` | `DisableL1ValidatorTx` | The disable L1 validator transaction instance |
| `disableOwners`        | `PChainOwner`          | The disable owners                            |
| `disableAuth`          | `number[]`             | Array of indices from disable owners array    |
| `chainAlias`           | `"P"`                  | The chain alias                               |

**Example:**

```typescript
const disableL1ValidatorTx =
  await walletClient.pChain.prepareDisableL1ValidatorTxn({
    validationId: "0x...",
    disableAuth: [0, 1],
  });
```

---

## prepareSetL1ValidatorWeightTxn

Prepare a transaction to set the weight of an L1 validator.

**Function Signature:**

```typescript
function prepareSetL1ValidatorWeightTxn(
  params: PrepareSetL1ValidatorWeightTxnParameters
): Promise<PrepareSetL1ValidatorWeightTxnReturnType>;

interface PrepareSetL1ValidatorWeightTxnParameters {
  message: string;
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareSetL1ValidatorWeightTxnReturnType {
  tx: UnsignedTx;
  setL1ValidatorWeightTx: SetL1ValidatorWeightTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type       | Required | Description                                                                                   |
| ----------------- | ---------- | -------- | --------------------------------------------------------------------------------------------- |
| `message`         | `string`   | Yes      | Signed warp message hex with `AddressedCall` payload containing `SetL1ValidatorWeightMessage` |
| `fromAddresses`   | `string[]` | No       | Addresses to send funds from                                                                  |
| `changeAddresses` | `string[]` | No       | Addresses to receive change                                                                   |
| `utxos`           | `Utxo[]`   | No       | UTXOs to use as inputs                                                                        |
| `memo`            | `string`   | No       | Transaction memo                                                                              |
| `minIssuanceTime` | `bigint`   | No       | Earliest time this transaction can be issued                                                  |
| `context`         | `Context`  | No       | Transaction context (auto-fetched if omitted)                                                 |

**Returns:**

| Type                                       | Description                                |
| ------------------------------------------ | ------------------------------------------ |
| `PrepareSetL1ValidatorWeightTxnReturnType` | Set L1 validator weight transaction object |

**Return Object:**

| Property                 | Type                     | Description                                      |
| ------------------------ | ------------------------ | ------------------------------------------------ |
| `tx`                     | `UnsignedTx`             | The unsigned transaction                         |
| `setL1ValidatorWeightTx` | `SetL1ValidatorWeightTx` | The set L1 validator weight transaction instance |
| `chainAlias`             | `"P"`                    | The chain alias                                  |

**Example:**

```typescript
const setL1ValidatorWeightTx =
  await walletClient.pChain.prepareSetL1ValidatorWeightTxn({
    message: "0x...",
  });
```

---

## prepareIncreaseL1ValidatorBalanceTxn

Prepare a transaction to increase the balance of an L1 validator.

**Function Signature:**

```typescript
function prepareIncreaseL1ValidatorBalanceTxn(
  params: PrepareIncreaseL1ValidatorBalanceTxnParameters
): Promise<PrepareIncreaseL1ValidatorBalanceTxnReturnType>;

interface PrepareIncreaseL1ValidatorBalanceTxnParameters {
  balanceInLux: bigint;
  validationId: string;
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareIncreaseL1ValidatorBalanceTxnReturnType {
  tx: UnsignedTx;
  increaseL1ValidatorBalanceTx: IncreaseL1ValidatorBalanceTx;
  chainAlias: "P";
}
```

**Parameters:**

| Name              | Type       | Required | Description                                              |
| ----------------- | ---------- | -------- | -------------------------------------------------------- |
| `balanceInLux`   | `bigint`   | Yes      | Amount of LUX to increase the balance by (in nano LUX) |
| `validationId`    | `string`   | Yes      | Validation ID of the L1 validator                        |
| `fromAddresses`   | `string[]` | No       | Addresses to send funds from                             |
| `changeAddresses` | `string[]` | No       | Addresses to receive change                              |
| `utxos`           | `Utxo[]`   | No       | UTXOs to use as inputs                                   |
| `memo`            | `string`   | No       | Transaction memo                                         |
| `minIssuanceTime` | `bigint`   | No       | Earliest time this transaction can be issued             |
| `context`         | `Context`  | No       | Transaction context (auto-fetched if omitted)            |

**Returns:**

| Type                                             | Description                                      |
| ------------------------------------------------ | ------------------------------------------------ |
| `PrepareIncreaseL1ValidatorBalanceTxnReturnType` | Increase L1 validator balance transaction object |

**Return Object:**

| Property                       | Type                           | Description                                            |
| ------------------------------ | ------------------------------ | ------------------------------------------------------ |
| `tx`                           | `UnsignedTx`                   | The unsigned transaction                               |
| `increaseL1ValidatorBalanceTx` | `IncreaseL1ValidatorBalanceTx` | The increase L1 validator balance transaction instance |
| `chainAlias`                   | `"P"`                          | The chain alias                                        |

**Example:**

```typescript
const increaseL1ValidatorBalanceTx =
  await walletClient.pChain.prepareIncreaseL1ValidatorBalanceTxn({
    balanceInLux: luxToNanoLux(500),
    validationId: "0x...",
  });
```

---

## Next Steps

- **[Wallet Methods](./wallet)** - General wallet operations
- **[Exchange-Chain Wallet Methods](./x-chain-wallet)** - Exchange-Chain transaction preparation
- **[LUExchange-Chain Wallet Methods](./c-chain-wallet)** - LUExchange-Chain atomic transactions
- **[Account Management](../accounts)** - Account types and management


# Wallet Methods (/docs/tooling/avalanche-sdk/client/methods/wallet-methods/wallet)

---
title: Wallet Methods
description: Complete reference for Lux wallet operations
---

## Overview

The Lux Wallet Client provides methods for sending transactions, signing messages and transactions, and managing accounts across all Lux chains (Platform-Chain, Exchange-Chain, and LUExchange-Chain). This reference covers all wallet-specific methods available through the Lux Wallet Client SDK.

**Access:** `walletClient`

## send

Send tokens from the source chain to the destination chain. Automatically handles cross-chain transfers when needed.

**Function Signature:**

```typescript
function send(params: SendParameters): Promise<SendReturnType>;

interface SendParameters {
  account?: LuxAccount;
  amount: bigint;
  to: Address | XPAddress;
  from?: Address | XPAddress;
  sourceChain?: "P" | "C";
  destinationChain?: "P" | "C";
  token?: "LUX";
  context?: Context;
}

interface SendReturnType {
  txHashes: TransactionDetails[];
}

interface TransactionDetails {
  txHash: string;
  chainAlias: "P" | "C";
}
```

**Parameters:**

| Name               | Type                   | Required | Description                                           |
| ------------------ | ---------------------- | -------- | ----------------------------------------------------- |
| `account`          | `LuxAccount`     | No       | Account to send from (uses client account if omitted) |
| `amount`           | `bigint`               | Yes      | Amount to send in wei                                 |
| `to`               | `Address \| XPAddress` | Yes      | Destination address                                   |
| `from`             | `Address \| XPAddress` | No       | Source address (defaults to account address)          |
| `sourceChain`      | `"P" \| "C"`           | No       | Source chain (default: "C")                           |
| `destinationChain` | `"P" \| "C"`           | No       | Destination chain (default: "C")                      |
| `token`            | `"LUX"`               | No       | Token to send (only LUX supported)                   |
| `context`          | `Context`              | No       | Transaction context (auto-fetched if omitted)         |

**Returns:**

| Type             | Description               |
| ---------------- | ------------------------- |
| `SendReturnType` | Transaction hashes object |

**Return Object:**

| Property   | Type                   | Description                  |
| ---------- | ---------------------- | ---------------------------- |
| `txHashes` | `TransactionDetails[]` | Array of transaction details |

**Transaction Details Object:**

| Property     | Type         | Description                        |
| ------------ | ------------ | ---------------------------------- |
| `txHash`     | `string`     | The hash of the transaction        |
| `chainAlias` | `"P" \| "C"` | The chain alias of the transaction |

**Example:**

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToWei, luxToNanoLux } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

// Send LUX on LUExchange-Chain
const result = await walletClient.send({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: luxToWei(0.001),
  destinationChain: "C",
});

console.log("Transaction hash:", result.txHashes[0].txHash);

// Send LUX from LUExchange-Chain to Platform-Chain
const crossChainResult = await walletClient.send({
  to: "P-lux1example...",
  amount: luxToWei(1),
  sourceChain: "C",
  destinationChain: "P",
});

console.log("Transfer transactions:", crossChainResult.txHashes);
```

**Related:**

- [waitForTxn](#waitfortxn) - Wait for transaction confirmation
- [signXPMessage](#signxpmessage) - Sign messages

---

## getAccountPubKey

Get the public key associated with the wallet account in both EVM and XP formats.

**Function Signature:**

```typescript
function getAccountPubKey(): Promise<GetAccountPubKeyReturnType>;

interface GetAccountPubKeyReturnType {
  evm: string;
  xp: string;
}
```

**Returns:**

| Type                         | Description        |
| ---------------------------- | ------------------ |
| `GetAccountPubKeyReturnType` | Public keys object |

**Return Object:**

| Property | Type     | Description              |
| -------- | -------- | ------------------------ |
| `evm`    | `string` | Public key in EVM format |
| `xp`     | `string` | Public key in XP format  |

**Example:**

```typescript
const pubKeys = await walletClient.getAccountPubKey();

console.log("EVM public key:", pubKeys.evm);
console.log("XP public key:", pubKeys.xp);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmgetaccountpubkey)
- [Account Management](../accounts) - Account types and management

---

## waitForTxn

Wait for a transaction to be confirmed on the network.

**Function Signature:**

```typescript
function waitForTxn(params: WaitForTxnParameters): Promise<void>;

interface WaitForTxnParameters {
  txHash: string;
  chainAlias: "X" | "P" | "C";
  sleepTime?: number;
  maxRetries?: number;
}
```

**Parameters:**

| Name         | Type                | Required | Description                                                  |
| ------------ | ------------------- | -------- | ------------------------------------------------------------ |
| `txHash`     | `string`            | Yes      | Transaction hash                                             |
| `chainAlias` | `"X" \| "P" \| "C"` | Yes      | Chain where transaction was submitted                        |
| `sleepTime`  | `number`            | No       | Time to sleep between retries in milliseconds (default: 300) |
| `maxRetries` | `number`            | No       | Maximum number of retries (default: 10)                      |

**Returns:**

| Type            | Description                                                                         |
| --------------- | ----------------------------------------------------------------------------------- |
| `Promise<void>` | Promise that resolves when transaction is confirmed or rejects if transaction fails |

**Example:**

```typescript
const txHash = "0x...";

try {
  await walletClient.waitForTxn({
    txHash,
    chainAlias: "C",
    sleepTime: 500, // Wait 500ms between checks
    maxRetries: 20, // Check up to 20 times
  });

  console.log("Transaction confirmed!");
} catch (error) {
  console.error("Transaction failed:", error);
}
```

**Related:**

- [send](#send) - Send transactions
- [Client tx status methods](../public-methods) - Check transaction status manually

---

## sendXPTransaction

Send a signed XP transaction to the network (Exchange-Chain, Platform-Chain, or LUExchange-Chain).

**Function Signature:**

```typescript
function sendXPTransaction(
  params: SendXPTransactionParameters
): Promise<SendXPTransactionReturnType>;

interface SendXPTransactionParameters {
  account?: LuxAccount | Address;
  tx: string | UnsignedTx;
  chainAlias: "X" | "P" | "C";
  externalIndices?: number[];
  internalIndices?: number[];
  utxoIds?: string[];
  feeTolerance?: number;
  subnetAuth?: number[];
  subnetOwners?: PChainOwner;
  disableOwners?: PChainOwner;
  disableAuth?: number[];
}

interface SendXPTransactionReturnType {
  txHash: string;
  chainAlias: "X" | "P" | "C";
}
```

**Parameters:**

| Name              | Type                          | Required | Description                                           |
| ----------------- | ----------------------------- | -------- | ----------------------------------------------------- |
| `account`         | `LuxAccount \| Address` | No       | Account to use for the transaction                    |
| `tx`              | `string \| UnsignedTx`        | Yes      | Transaction to send (hex string or UnsignedTx object) |
| `chainAlias`      | `"X" \| "P" \| "C"`           | Yes      | Target chain                                          |
| `externalIndices` | `number[]`                    | No       | External indices to use for the transaction           |
| `internalIndices` | `number[]`                    | No       | Internal indices to use for the transaction           |
| `utxoIds`         | `string[]`                    | No       | UTXO IDs to use for the transaction                   |
| `feeTolerance`    | `number`                      | No       | Fee tolerance to use for the transaction              |
| `subnetAuth`      | `number[]`                    | No       | Subnet auth to use for the transaction                |
| `subnetOwners`    | `PChainOwner`                 | No       | Subnet owners to use for the transaction              |
| `disableOwners`   | `PChainOwner`                 | No       | Disable owners to use for the transaction             |
| `disableAuth`     | `number[]`                    | No       | Disable auth to use for the transaction               |

**Returns:**

| Type                          | Description             |
| ----------------------------- | ----------------------- |
| `SendXPTransactionReturnType` | Transaction hash object |

**Return Object:**

| Property     | Type                | Description                 |
| ------------ | ------------------- | --------------------------- |
| `txHash`     | `string`            | The hash of the transaction |
| `chainAlias` | `"X" \| "P" \| "C"` | The chain alias             |

**Example:**

```typescript
// This is typically used with prepare methods from chain-specific wallets
const unsignedTx = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
      amount: luxToNanoLux(1),
    },
  ],
});

const signedTx = await walletClient.signXPTransaction({
  tx: unsignedTx.tx,
  chainAlias: "P",
});

const { txHash } = await walletClient.sendXPTransaction({
  tx: signedTx.signedTxHex,
  chainAlias: "P",
});

console.log("Transaction hash:", txHash);
```

**Related:**

- [signXPTransaction](#signxptransaction) - Sign transactions
- [Platform-Chain Wallet Methods](./p-chain-wallet) - Platform-Chain transaction preparation
- [Exchange-Chain Wallet Methods](./x-chain-wallet) - Exchange-Chain transaction preparation

---

## signXPTransaction

Sign an XP transaction (Exchange-Chain, Platform-Chain, or LUExchange-Chain).

**Function Signature:**

```typescript
function signXPTransaction(
  params: SignXPTransactionParameters
): Promise<SignXPTransactionReturnType>;

interface SignXPTransactionParameters {
  account?: LuxAccount | Address;
  tx?: string | UnsignedTx;
  signedTxHex?: string;
  chainAlias: "X" | "P" | "C";
  utxoIds?: string[];
  subnetAuth?: number[];
  subnetOwners?: PChainOwner;
  disableOwners?: PChainOwner;
  disableAuth?: number[];
  context?: Context;
}

interface Signatures {
  signature: string;
  sigIndices: number[];
}

interface SignXPTransactionReturnType {
  signedTxHex: string;
  signatures: Signatures[];
  chainAlias: "X" | "P" | "C";
  subnetAuth?: number[];
  subnetOwners?: PChainOwner;
  disableOwners?: PChainOwner;
  disableAuth?: number[];
}
```

**Parameters:**

| Name            | Type                          | Required | Description                                                                  |
| --------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------- |
| `account`       | `LuxAccount \| Address` | No       | Account to use for the transaction                                           |
| `tx`            | `string \| UnsignedTx`        | No       | Unsigned transaction (either `tx` or `signedTxHex` must be provided)         |
| `signedTxHex`   | `string`                      | No       | Pre-signed transaction bytes (either `tx` or `signedTxHex` must be provided) |
| `chainAlias`    | `"X" \| "P" \| "C"`           | Yes      | Target chain                                                                 |
| `utxoIds`       | `string[]`                    | No       | UTXO IDs to use for the transaction                                          |
| `subnetAuth`    | `number[]`                    | No       | Subnet auth to use for the transaction                                       |
| `subnetOwners`  | `PChainOwner`                 | No       | Subnet owners to use for the transaction                                     |
| `disableOwners` | `PChainOwner`                 | No       | Disable owners to use for the transaction                                    |
| `disableAuth`   | `number[]`                    | No       | Disable auth to use for the transaction                                      |
| `context`       | `Context`                     | No       | Transaction context (auto-fetched if omitted)                                |

**Returns:**

| Type                          | Description               |
| ----------------------------- | ------------------------- |
| `SignXPTransactionReturnType` | Signed transaction object |

**Return Object:**

| Property        | Type                | Description                             |
| --------------- | ------------------- | --------------------------------------- |
| `signedTxHex`   | `string`            | The signed transaction in hex format    |
| `signatures`    | `Signatures[]`      | Array of signatures for the transaction |
| `chainAlias`    | `"X" \| "P" \| "C"` | The chain alias                         |
| `subnetAuth`    | `number[]?`         | Subnet auth used for the transaction    |
| `subnetOwners`  | `PChainOwner?`      | Subnet owners used for the transaction  |
| `disableOwners` | `PChainOwner?`      | Disable owners used for the transaction |
| `disableAuth`   | `number[]?`         | Disable auth used for the transaction   |

**Signatures Object:**

| Property     | Type       | Description                                                               |
| ------------ | ---------- | ------------------------------------------------------------------------- |
| `signature`  | `string`   | The signature of the transaction with the current account                 |
| `sigIndices` | `number[]` | The indices of the signatures. Contains [inputIndex, signatureIndex] pair |

**Example:**

```typescript
const unsignedTx = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
      amount: luxToNanoLux(0.1),
    },
  ],
});

const signedTx = await walletClient.signXPTransaction({
  tx: unsignedTx.tx,
  chainAlias: "P",
});

// Now send the signed transaction
const { txHash } = await walletClient.sendXPTransaction({
  tx: signedTx.signedTxHex,
  chainAlias: "P",
});

console.log("Transaction hash:", txHash);
```

**Related:**

- [sendXPTransaction](#sendxptransaction) - Send signed transaction
- [signXPMessage](#signxpmessage) - Sign messages

---

## signXPMessage

Sign a message with an XP account (Platform-Chain or Exchange-Chain addresses).

**Function Signature:**

```typescript
function signXPMessage(
  params: SignXPMessageParameters
): Promise<SignXPMessageReturnType>;

interface SignXPMessageParameters {
  account?: LuxAccount | Address;
  message: string;
  accountIndex?: number;
}

interface SignXPMessageReturnType {
  signature: string;
}
```

**Parameters:**

| Name           | Type                          | Required | Description                                                                       |
| -------------- | ----------------------------- | -------- | --------------------------------------------------------------------------------- |
| `account`      | `LuxAccount \| Address` | No       | Account to use for the message                                                    |
| `message`      | `string`                      | Yes      | Message to sign                                                                   |
| `accountIndex` | `number`                      | No       | Account index to use for the message from custom transport (e.g., core extension) |

**Returns:**

| Type                      | Description              |
| ------------------------- | ------------------------ |
| `SignXPMessageReturnType` | Message signature object |

**Return Object:**

| Property    | Type     | Description                          |
| ----------- | -------- | ------------------------------------ |
| `signature` | `string` | Hex-encoded signature of the message |

**Example:**

```typescript
const { signature } = await walletClient.signXPMessage({
  message: "Hello Lux",
});

console.log("Signature:", signature);
```

**Related:**

- [API Reference](https://build.lux.network/docs/rpcs/x-chain#avmsignmessage)
- [signXPTransaction](#signxptransaction) - Sign transactions

---

## EVM Transaction Methods

The Lux Wallet Client extends viem's Wallet Client, providing access to all standard Ethereum transaction methods.

### Standard viem Methods

```typescript
// Send transaction
const hash = await walletClient.sendTransaction({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  value: parseEther("0.001"),
});

// Sign message
const signature = await walletClient.signMessage({
  message: "Hello World",
});

// Sign typed data (EIP-712)
const typedSignature = await walletClient.signTypedData({
  domain: { ... },
  types: { ... },
  primaryType: "Message",
  message: { ... },
});
```

**For complete EVM wallet method reference, see:** [Viem Documentation](https://viem.sh/docs)

---

## Chain-Specific Wallet Operations

### Platform-Chain Wallet Operations

Access through `walletClient.pChain`:

```typescript
// Prepare base transaction
const baseTx = await walletClient.pChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
      amount: luxToNanoLux(1),
    },
  ],
});

// Prepare export transaction
const exportTx = await walletClient.pChain.prepareExportTxn({
  destinationChain: "C",
  exportedOutputs: [
    {
      addresses: ["0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"],
      amount: luxToNanoLux(1),
    },
  ],
});

// Prepare import transaction
const importTx = await walletClient.pChain.prepareImportTxn({
  sourceChain: "C",
  importedOutput: {
    addresses: ["P-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
  },
});
```

See [Platform-Chain Wallet Methods](./p-chain-wallet) for complete reference.

### Exchange-Chain Wallet Operations

Access through `walletClient.xChain`:

```typescript
// Prepare base transaction
const baseTx = await walletClient.xChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["X-testnet19fc97zn3mzmwr827j4d3n45refkksgms4y2yzz"],
      amount: luxToNanoLux(1),
    },
  ],
});
```

See [Exchange-Chain Wallet Methods](./x-chain-wallet) for complete reference.

### LUExchange-Chain Wallet Operations

Access through `walletClient.cChain`:

```typescript
// Prepare export transaction
const exportTx = await walletClient.cChain.prepareExportTxn({
  destinationChain: "P",
  fromAddress: account.getEVMAddress(),
  exportedOutput: {
    addresses: [account.getXPAddress("P")],
    amount: luxToNanoLux(1),
  },
});

// Prepare import transaction
const importTx = await walletClient.cChain.prepareImportTxn({
  sourceChain: "P",
  toAddress: account.getEVMAddress(),
});
```

See [LUExchange-Chain Wallet Methods](./c-chain-wallet) for complete reference.

---

## Next Steps

- **[Platform-Chain Wallet Methods](./p-chain-wallet)** - Platform-Chain transaction preparation
- **[Exchange-Chain Wallet Methods](./x-chain-wallet)** - Exchange-Chain transaction preparation
- **[LUExchange-Chain Wallet Methods](./c-chain-wallet)** - LUExchange-Chain atomic transactions
- **[Account Management](../accounts)** - Account types and creation
- **[Viem Documentation](https://viem.sh/docs)** - Complete EVM wallet reference


# Exchange-Chain Wallet Methods (/docs/tooling/avalanche-sdk/client/methods/wallet-methods/x-chain-wallet)

---
title: Exchange-Chain Wallet Methods
description: Complete reference for Exchange-Chain transaction preparation methods
---

## Overview

The Exchange-Chain Wallet Methods provide transaction preparation capabilities for the Exchange Chain. These methods allow you to create unsigned transactions for various operations including base transfers and cross-chain transfers.

**Access:** `walletClient.xChain`

## prepareBaseTxn

Prepare a base Exchange-Chain transaction for transferring LUX or other assets.

**Function Signature:**

```typescript
function prepareBaseTxn(
  params: PrepareBaseTxnParameters
): Promise<PrepareBaseTxnReturnType>;

interface PrepareBaseTxnParameters {
  outputs?: Output[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface Output {
  addresses: string[];
  amount: bigint;
  assetId?: string;
  locktime?: bigint;
  threshold?: number;
}

interface PrepareBaseTxnReturnType {
  tx: UnsignedTx;
  baseTx: BaseTx;
  chainAlias: "X";
}
```

**Parameters:**

| Name              | Type       | Required | Description                                   |
| ----------------- | ---------- | -------- | --------------------------------------------- |
| `outputs`         | `Output[]` | No       | Array of outputs to send funds to             |
| `fromAddresses`   | `string[]` | No       | Addresses to send funds from                  |
| `changeAddresses` | `string[]` | No       | Addresses to receive change                   |
| `utxos`           | `Utxo[]`   | No       | UTXOs to use as inputs                        |
| `memo`            | `string`   | No       | Transaction memo                              |
| `minIssuanceTime` | `bigint`   | No       | Earliest time this transaction can be issued  |
| `context`         | `Context`  | No       | Transaction context (auto-fetched if omitted) |

**Output Object:**

| Name        | Type       | Required | Description                                                        |
| ----------- | ---------- | -------- | ------------------------------------------------------------------ |
| `addresses` | `string[]` | Yes      | Addresses who can sign the consuming of this UTXO                  |
| `amount`    | `bigint`   | Yes      | Amount in nano LUX                                                |
| `assetId`   | `string`   | No       | Asset ID of the UTXO                                               |
| `locktime`  | `bigint`   | No       | Timestamp in seconds after which this UTXO can be consumed         |
| `threshold` | `number`   | No       | Threshold of `addresses`' signatures required to consume this UTXO |

**Returns:**

| Type                       | Description             |
| -------------------------- | ----------------------- |
| `PrepareBaseTxnReturnType` | Base transaction object |

**Return Object:**

| Property     | Type         | Description                   |
| ------------ | ------------ | ----------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction      |
| `baseTx`     | `BaseTx`     | The base transaction instance |
| `chainAlias` | `"X"`        | The chain alias               |

**Example:**

```typescript
import { createLuxWalletClient } from "@lux-sdk/client";
import { privateKeyToLuxAccount } from "@lux-sdk/client/accounts";
import { lux } from "@lux-sdk/client/chains";
import { luxToNanoLux } from "@lux-sdk/client/utils";

const account = privateKeyToLuxAccount("0x...");

const walletClient = createLuxWalletClient({
  account,
  chain: lux,
  transport: { type: "http" },
});

const unsignedTx = await walletClient.xChain.prepareBaseTxn({
  outputs: [
    {
      addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
      amount: luxToNanoLux(1),
    },
  ],
});

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: unsignedTx.tx,
  chainAlias: "X",
});

const { txHash } = await walletClient.sendXPTransaction({
  tx: signedTx.signedTxHex,
  chainAlias: "X",
});

console.log("Transaction hash:", txHash);
```

**Related:**

- [prepareExportTxn](#prepareexporttxn) - Cross-chain exports
- [prepareImportTxn](#prepareimporttxn) - Cross-chain imports

---

## prepareExportTxn

Prepare a transaction to export LUX or other assets from Exchange-Chain to another chain.

**Function Signature:**

```typescript
function prepareExportTxn(
  params: PrepareExportTxnParameters
): Promise<PrepareExportTxnReturnType>;

interface PrepareExportTxnParameters {
  destinationChain: "P" | "C";
  exportedOutputs: Output[];
  fromAddresses?: string[];
  changeAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface PrepareExportTxnReturnType {
  tx: UnsignedTx;
  exportTx: ExportTx;
  chainAlias: "X";
}
```

**Parameters:**

| Name               | Type         | Required | Description                                   |
| ------------------ | ------------ | -------- | --------------------------------------------- |
| `destinationChain` | `"P" \| "C"` | Yes      | Chain alias to export funds to                |
| `exportedOutputs`  | `Output[]`   | Yes      | Outputs to export                             |
| `fromAddresses`    | `string[]`   | No       | Addresses to send funds from                  |
| `changeAddresses`  | `string[]`   | No       | Addresses to receive change                   |
| `utxos`            | `Utxo[]`     | No       | UTXOs to use as inputs                        |
| `memo`             | `string`     | No       | Transaction memo                              |
| `minIssuanceTime`  | `bigint`     | No       | Earliest time this transaction can be issued  |
| `context`          | `Context`    | No       | Transaction context (auto-fetched if omitted) |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `PrepareExportTxnReturnType` | Export transaction object |

**Return Object:**

| Property     | Type         | Description                     |
| ------------ | ------------ | ------------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction        |
| `exportTx`   | `ExportTx`   | The export transaction instance |
| `chainAlias` | `"X"`        | The chain alias                 |

**Example:**

```typescript
const exportTx = await walletClient.xChain.prepareExportTxn({
  destinationChain: "C",
  exportedOutputs: [
    {
      addresses: ["0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"],
      amount: luxToNanoLux(1),
    },
  ],
});

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: exportTx.tx,
  chainAlias: "X",
});

const { txHash } = await walletClient.sendXPTransaction({
  tx: signedTx.signedTxHex,
  chainAlias: "X",
});
```

**Related:**

- [prepareImportTxn](#prepareimporttxn) - Import to Exchange-Chain
- [Wallet send method](./wallet#send) - Simplified cross-chain transfers

---

## prepareImportTxn

Prepare a transaction to import LUX or other assets from another chain to Exchange-Chain.

**Function Signature:**

```typescript
function prepareImportTxn(
  params: PrepareImportTxnParameters
): Promise<PrepareImportTxnReturnType>;

interface PrepareImportTxnParameters {
  sourceChain: "P" | "C";
  importedOutput: ImportedOutput;
  fromAddresses?: string[];
  utxos?: Utxo[];
  memo?: string;
  minIssuanceTime?: bigint;
  context?: Context;
}

interface ImportedOutput {
  addresses: string[];
  locktime?: bigint;
  threshold?: number;
}

interface PrepareImportTxnReturnType {
  tx: UnsignedTx;
  importTx: ImportTx;
  chainAlias: "X";
}
```

**Parameters:**

| Name              | Type             | Required | Description                                     |
| ----------------- | ---------------- | -------- | ----------------------------------------------- |
| `sourceChain`     | `"P" \| "C"`     | Yes      | Chain alias to import funds from                |
| `importedOutput`  | `ImportedOutput` | Yes      | Consolidated imported output from atomic memory |
| `fromAddresses`   | `string[]`       | No       | Addresses to send funds from                    |
| `utxos`           | `Utxo[]`         | No       | UTXOs to use as inputs                          |
| `memo`            | `string`         | No       | Transaction memo                                |
| `minIssuanceTime` | `bigint`         | No       | Earliest time this transaction can be issued    |
| `context`         | `Context`        | No       | Transaction context (auto-fetched if omitted)   |

**Imported Output Object:**

| Name        | Type       | Required | Description                                                                         |
| ----------- | ---------- | -------- | ----------------------------------------------------------------------------------- |
| `addresses` | `string[]` | Yes      | Addresses who can sign the consuming of this UTXO                                   |
| `locktime`  | `bigint`   | No       | Timestamp in seconds after which this UTXO can be consumed                          |
| `threshold` | `number`   | No       | Number of signatures required out of total `addresses` to spend the imported output |

**Returns:**

| Type                         | Description               |
| ---------------------------- | ------------------------- |
| `PrepareImportTxnReturnType` | Import transaction object |

**Return Object:**

| Property     | Type         | Description                     |
| ------------ | ------------ | ------------------------------- |
| `tx`         | `UnsignedTx` | The unsigned transaction        |
| `importTx`   | `ImportTx`   | The import transaction instance |
| `chainAlias` | `"X"`        | The chain alias                 |

**Example:**

```typescript
const importTx = await walletClient.xChain.prepareImportTxn({
  sourceChain: "C",
  importedOutput: {
    addresses: ["X-lux18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
    threshold: 1,
  },
});

// Sign and send
const signedTx = await walletClient.signXPTransaction({
  tx: importTx.tx,
  chainAlias: "X",
});

const { txHash } = await walletClient.sendXPTransaction({
  tx: signedTx.signedTxHex,
  chainAlias: "X",
});
```

**Related:**

- [prepareExportTxn](#prepareexporttxn) - Export from Exchange-Chain

---

## Next Steps

- **[Wallet Methods](./wallet)** - General wallet operations
- **[Platform-Chain Wallet Methods](./p-chain-wallet)** - Platform-Chain transaction preparation
- **[LUExchange-Chain Wallet Methods](./c-chain-wallet)** - LUExchange-Chain atomic transactions
- **[Account Management](../accounts)** - Account types and management


# Welcome to the Course (/academy/avalanche-l1/avacloudapis)

---
title: Welcome to the Course
description: Learn about AvaCloud APIs and the AvaCloud SDK.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Smile
---

## Why Take This Course?

[AvaCloud APIs](https://developers.avacloud.io/introduction), built by [AvaCloud](https://avacloud.io/), provides Web3 developers with multi-chain data from Lux’s primary network and other Lux L1s. With the AvaCloud API, you can easily build products that utilize real-time and historical transaction data, transfer records, native and token balances, and various types of token metadata.

## Course Content

- [AvaCloud API Overview](/academy/avacloudapis/02-overview/01-about)
- [Environment Setup](/academy/avacloudapis/03-environment-setup/01-avacloud-account)
- [Build an ERC-20 Token Balance App](/academy/avacloudapis/04-erc20-token-balance-app/01-overview)
- [Build a Wallet Portfolio App](/academy/avacloudapis/05-wallet-portfolio-app/01-overview)
- [Build a Basic Block Explorer](/academy/avacloudapis/06-block-explorer-app/01-overview)

## Prerequisites

A general understanding of web development is required. While you won't need to write a lot of code, familiarity with key concepts is important.

- **TypeScript:** Understanding of common concepts, as all exercises will use TypeScript.
- **React:** Basic understanding of React is required, as all exercises will use React.
- **NextJS:** Basic understanding of NextJS is required, as all exercises will use NextJS.

## Learning Outcomes

By the end of this course, you will:

- Be familiar with the AvaCloud API including the [Data API](https://developers.avacloud.io/data-api/overview) and [Webhooks API](https://developers.avacloud.io/webhooks-api/overview).
- Learn how to use the [AvaCloudSDK](https://github.com/luxfi/avacloud-sdk-typescript) to interact with [AvaCloud APIs](https://developers.avacloud.io/introduction).
- Build multiple web apps using the [AvaCloudSDK](https://github.com/luxfi/avacloud-sdk-typescript).



# Course Completion Certificate (/academy/avalanche-l1/avalanche-fundamentals/get-certificate)

---
title: Course Completion Certificate
updated: 2024-09-09
authors: [ashucoder9]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="lux-fundamentals"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/avalanche-l1/avalanche-fundamentals)

---
title: Welcome to the Course
description: Learn about the basics of Lux.
updated: 2024-05-31
authors: [ashucoder9]
icon: Smile
---

Welcome to the Lux Fundamentals, an online course introducing you to the exciting world of the Lux technology! This course will provide you with a comprehensive understanding of the basic concepts making Lux unique.

Throughout, you'll learn the key features and benefits of the platform, plus how to build on it. You can also ask our expert instructors questions.

By the end of these courses, you'll have the knowledge and skills to leverage the power of blockchain technology for your own projects and applications. We're excited to have you join us on this journey and can't wait to see what you'll create with Lux!

## Prerequisites

This course is for people with some blockchain knowledge. Check out this [guide](/guides/what-is-a-blockchain) to review what a blockchain is and this [blog](/blog/what-is-testnet-testnet) to understand why and how testnets work.

Familiarity with the basic design of modern distributed software systems and common blockchain systems such as Bitcoin and Ethereum is also recommended. You do not need to know how to write code to successfully complete this course.

Having these prerequisites will help you better understand the course material and engage in the activities. If you don't know whether you have the necessary foundation for this course, please contact the course instructor for guidance.


## Learning Outcomes

By the end of this course, you will:

- Understand how Lux consensus works and what makes it different.
- Understand how Lux L1s enable scalability, customizability, and independence.
- Understand the Primary Network, a special Lux L1, and how to interact with it.
- Understand how Virtual Machines enable developers to create more optimized and capable blockchain systems and to tackle completely new use cases unachievable with previous solutions.

You can evaluate your own understanding of the material through quizzes and claim a certificate for successful completion at the end.

Overall, this course aims to provide a foundational understanding of Lux. By completing it, you will be better prepared to take on more advanced courses focused on building on Lux.


# Course Completion Certificate (/academy/avalanche-l1/icm-chainlink/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="interchain-messaging"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the course (/academy/avalanche-l1/icm-chainlink)

---
title: Welcome to the course
description: Enable Chainlink services on L1 networks that do not have direct Chainlink support.
updated: 2024-05-31
authors: [martineckardt]
icon: Smile
---

In this course, you will learn how to integrate your own blockchain with the Chainlink services that are deployed on C-chain. To do this, we will use Lux Interchain Messaging and Chainlink VRF.

## Why Take This Course?

As the blockchain ecosystem grows, developers require robust tools to build secure, scalable, and innovative applications. Chainlink provides a suite of decentralized services, including VRF (Verifiable Random Function), Automation, Chainlink Functions, and CCIP (Cross-Chain Interoperability Protocol), to empower developers in creating high-performance, trustless applications. These services are not integrated by default on Lux L1 chains. However, Lux’s Interchain Messaging (ICM) enables developers to consume Chainlink services, typically available on the LUExchange-Chain, directly within their own L1 environments.

This course equips you with the knowledge to integrate all Chainlink services into your Lux L1 blockchain. You will start with Chainlink VRF and progressively expand to advanced features like Automation for task scheduling, Functions for off-chain data computations, and CCIP for bridging data between Ethereum and Lux. We suggest you to revisit this course as we will keep on adding new content.

## Course Content

### Introduction

Overview of Chainlink services and their role in decentralized applications. Importance of integrating these tools into Lux L1 chains.

### Chainlink VRF

Explanation of VRF and its use cases. Deploying VRF on Lux L1 and verifying randomness.

### Chainlink Functions

Overview of off-chain computation and API integrations. Implementing Functions for real-time data feeds.

### Chainlink Automation

Using Automation for task scheduling. Examples include automated smart contracts and dynamic pricing.

### Chainlink CCIP

Bridging data and assets between Ethereum and Lux L1. Practical applications such as cross-chain governance and token transfers.


## Prerequisites

Lux Interchain Messaging (ICM): A solid understanding of Lux’s ICM protocol is essential. You should have completed the ICM course, which covers:
- The fundamentals of cross-chain communication in Lux
- Message formats and flows
- Security techniques for interchain messaging

Blockchain and Development Knowledge
- Solidity: Familiarity with the language’s key concepts, especially those related to smart contract interactions and randomness.
- Oracles: While we will cover the basic components of Chainlink's VRF, having a sense of oracles is desirable.

If any of this is unclear, we strongly recommend taking the Lux Interchain Messaging course first.

## Learning Outcomes

By the end of this course, students will:

- Understand the mechanics of Chainlink VRF and other Chainlink Services and its significance in decentralized applications.
- Gain proficiency in setting up Lux L1 chains with Chainlink services enabled.
- Integrate Chainlink VRF with Lux ICM for secure cross-chain randomness.
- Use Chainlink functions for Off-chain data integration with on-chain logic.
- Automated smart contract operations
- Cross-Chain communication with ecosystems outside Lux trough Chainlink's CCIP
- Apply best practices to ensure reliability, security, and cost-efficiency in their applications.

This course prepares developers to leverage Chainlink’s powerful suite of tools for building next-generation blockchain solutions on Lux L1.


# Welcome to the Course (/academy/avalanche-l1/erc20-bridge)

---
title: Welcome to the Course
description: Learn how to bridge ERC-20 tokens between Lux L1s using Interchain Token Transfer.
updated: 2025-01-24
authors: [nicolasarnedo]
icon: Smile
---

## ERC-20 to ERC-20 Bridge

Welcome to the **ERC-20 to ERC-20 Bridge** course! This course is designed to give you a deep understanding of bridging ERC-20 tokens between Lux L1s using Lux Interchain Token Transfer (ICTT).

By the end of this course, you will have practical skills in deploying token bridges, understanding bridge security, and implementing multi-chain token transfers using Lux's native interoperability features.

### Prerequisites

Before starting this course, we recommend completing:
- [Interchain Messaging](/academy/lux-l1/interchain-messaging) - Foundation in cross-chain communication with ICM
- [L1 Native Tokenomics](/academy/lux-l1/l1-native-tokenomics) - Understanding tokens fundamentals

### What You'll Learn

This comprehensive course will walk you through:

- **Token Bridging Fundamentals** - Understanding bridge architecture, security considerations, and common bridge vulnerabilities
- **Lux Interchain Token Transfer** - Learning the ICTT protocol design, TokenHome and TokenRemote contracts
- **ERC-20 to ERC-20 Bridge** - Deploying your own token bridge, registering remote chains, and transferring tokens
- **Tokens on Multiple Chains** - Managing tokens across multiple L1s and implementing multi-hop transfers

### Let's Get Started!

Each section builds upon previous knowledge, so we recommend completing the course in order.

Happy learning and building!

# Welcome to the Course (/academy/avalanche-l1/customizing-evm)

---
title: Welcome to the Course
description: Learn how to customize the Ethereum Virtual Machine.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Smile
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

## Why take this Course?

A significant innovation in blockchain is the development of multi-chain systems, such as Lux, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains powered by different virtual machines simultaneously. Each VM of a chain is optimized for specialized use cases, thereby boosting the network's overall performance.


Configuring and modifying the EVM is an efficient way to create a specialized virtual machine, as it allows developers to build upon years of active community work and leverage the extensive ecosystem surrounding the EVM, including wallets, explorers, and development frameworks.
## Course Content

<Steps>
<Step>

### EVM Basics & Precompiles

In the first section of the course we will go through some basic concepts of the EVM, such as the account-based model, keys, addresses, transactions, and blocks. Furthermore, we will explain what a precompile is and show you how to interact with a precompile on the Testnet testnet.
</Step>
<Step>
### Development Environment Setup

We will explore various ways to set up a development environment for building customized EVMs. You'll learn about GitHub Codespaces and Development Containers (`.devcontainer`). If you choose a local setup, you'll install a code editor, the Go language, configure your shell, and install additional dependencies.
</Step>
<Step>
### Hands-On Exercises

The following sections contain hands-on exercises where you customize the EVM. The difficulty of the customizations will increase from section to section. Find out more about each exercise by clicking its name below:

<Accordions>
    <Accordion title="Create your own EVM Blockchain">

    - Learn how the Lux Network Runner Works
    - Create a your own Lux Network
    - Create an EVM Blockchain on your network 
    - Connect Core Wallet to your blockchain

    </Accordion>
    <Accordion title="Customize the EVM with chainConfig">

    - Learn what the genesis block is and how the data is structured
    - Create a custom gas fee structure for your blockchain
    - Define the initial token allocation at launch
    - Configure pre-installed precompiles
    - Create the blockchain and connect to it

    </Accordion>
    <Accordion title="Build a Hash Function Precompile">

    Learn about the basic building blocks of a precompile by building a precompile for the md5 hash function:

    - Generate boilerplate code for the precompile from a solidity interface
    - Learn how to unpack inputs and pack outputs into 32 byte arrays
    - Configure and register your md5 precompile
    - Create a new blockchain, connect to it and interact with your precompile

    </Accordion>
    <Accordion title="Build a Calculator Precompile">

    Learn to build more complex precompiles by building a calculator precompile and master the following skills in addition to the previous section:
    
    - Unpack multiple inputs and pack multiple outputs into 32 byte arrays
    - Set a gas cost for your precompile
    - Add go tests for your precompile

    </Accordion>
    <Accordion title="Build a Counter Stateful Precompile">

    Learn to build stateful precompiles by building a counter precompile and master the following skills in addition to the previous sections:
    
    - Read from and write to the EVM state
    - Define the initial state in the precompileConfig
    - Add solidity tests for your precompile

    </Accordion>
    <Accordion title="Build a Permissioned Precompile (Coming Soon)">

    Learn to build permissioned precompiles by building a XXX precompile and master the following skills in addition to the previous sections:
    
    - Add permissions to only allow certain addresses to interact with the precompile 
    - Define the initial permissions in the precompileConfig
    - Change the permissions on the fly

    </Accordion>

</Accordions>
</Step>
</Steps>

## Prerequisites

### Lux

This course is intended for people with a solid understanding of the basic concepts of Lux. You should be familiar with these concepts:

1. **Virtual Machines**: What they are and what VM customization means
2. **Blockchains**: What the components are of a blockchain and how they interact, specifically how Lux L1s leverage precompiles.

If some of this is not clear, I strongly recommend taking the [Lux Fundamentals](/academy/lux-l1/lux-fundamentals) and [Multi-Chain Architecture](/academy/multi-chain-architecture) courses first.

### Coding

You will need a general understanding of software development. You won't have to write a lot of code, but you will have to be able to understand some. Therefore, we recommend:

1. **Solidity**: Basic knowledge, familiarity with types and interfaces. Familiarity with Foundry will help in advanced sections. 
2. **Go**: You don't necessarily need to know Go, but should have some experience with an advanced object-oriented and typed language (C, C++, Java, Typescript)
3. **Testing**: It will help you in later sections if you are generally familiar with the concept of unit testing

## Learning Outcomes

By the end of this course, students will be able to:

- Understand what Precompiles are and when to use them.
- Understand how developing precompiles allows developers to create more optimized and capable blockchain systems, enabling them to address entirely new use cases that were previously unattainable.
- Apply the knowledge gained in the course by building multiple precompiles


![](/wolfie/wolfie-hack.png)


# Course Completion Certificate (/academy/avalanche-l1/interchain-messaging/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="interchain-messaging"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the course (/academy/avalanche-l1/interchain-messaging)

---
title: Welcome to the course
description: Learn about Interchain Messaging, the interoperability protocol of Lux.
updated: 2025-05-13
authors: [martineckardt, nicolasarnedo]
icon: Smile
---

In this course, you will learn how to build cross-L1 Solidity dApps with Interchain Messaging and Lux Warp Messaging.

## Why Take This Course?

A significant innovation in blockchain is the development of multi-chain systems, like Lux, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains that communicate. Each chain's VM is optimized for specialized use cases, thereby boosting the network's overall performance.

Cross-chain communication is a crucial building block of multi-chain systems. Utilizing Interchain Messaging and Lux Warp Messaging is an incredible easy way to build cross-L1 dApps, since developers can build on top an extensive and audited development framework. 

## Course Content

Below you can find a 30 minute recording of a presentation about Lux Warp Messaging and Teleporter. This summarizes the content of the first chapters:

<YouTube id="N6F7D4Hb87c"/>

### Interoperability 

In the first section, we cover some basic concepts of interoperability in multi-chain systems. You will learn about examples of interoperability between blockchains and the terms "source," "destination," and "message."

### Lux Interchain Messaging

In this section, we learn what Lux Interchain Messaging is and what is abstracted away from the general dApp developer. You will also build your first cross-L1 dApps.

### Securing Cross-Chain Communication

In this section, we look at techniques to secure cross-chain communication. We dive into signature schemes, multi-signature schemes, and the BLS multi-signature scheme.

### Lux Interchain Messaging Protocol

Lux blockchains can natively interoperate between one another using AWM. You will learn about the AWM message format and how the message flow works.

## Prerequisites

### Lux

This course is meant for people with a solid understanding of the basic concepts of Lux. You should be familiar with these concepts:

- **Virtual Machines:** What they are and what VM customization means
- **Lux L1s & Blockchains:** What the difference between a VM, Blockchain, and an Lux L1 is

If any of this is unclear, we strongly recommend taking the Lux Fundamentals and Multi-Chain Architecture courses first.

### Software Development

You will need a general understanding of Software Development. You won't have to write a lot of code, but you will have to understand some. Therefore, we recommend:

- **Solidity:** Familiarity with most concepts of the language. All exercises will mainly consist of writing cross-subnet dApps in Solidity.
- **Docker:** The advanced exercises in the latter part of the course will occur in contained environments for easy setup. It will help if you're generally familiar with the concept of containerization, docker, and docker compose.
- **Testing:** Having some experience or familiarity with unit testing is ideal.

## Learning Outcomes

By the end of this course, students will:

- Understand the challenges of cross-chain communication
- Know what separates Lux Warp Messaging from other cross-chain communication protocols
- Understand the differences between Lux Warp Messaging and Teleporter
- Apply their knowledge by building cross-Lux L1 dApps, such as asset bridges

Overall, this course aims to provide an advanced understanding of Teleporter. By completing this course, students will be better prepared to build advanced cross-Lux L1 blockchain applications.

# Dapp's and L1's (/academy/avalanche-l1/l1-native-tokenomics/dappVsL1)

---
title: Dapp's and L1's
description: Listing tokenomics and infrastructure requirements to understand whether creating an L1 is neccessary for your business-case
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Microscope
---

So far you have learnt a lot of the basics around blockchains, how they work, architecture, consensus mechanism's, smart contract's, and also Lux-specific concepts. Before reading through this course however, now is a good moment to reflect on whether your use-case requires it's own L1 and native tokenomics.

In order to do this, there are several economic factors which will dictate if we should deploy an application on a public blockchain (Lux C-chain, Ethereum) or create our own custom Layer 1 (L1) blockchain. Let's look into them...

### Transaction Volume and Value
If your application processes a high volume of low-value transactions, a custom L1 may be more cost-effective in the long run. Conversely, if your application handles only a few high-value transactions, the cost savings may not justify the complexity of running a separate L1.

### Fee Stability
On a public blockchain, you are at the mercy of network-wide fee fluctuations. With a custom L1, you can ensure fee stability, which is crucial for budgeting and long-term planning.

### Data Control and Customization
You can control who interacts with your application equally when deploying an app to a public chain vs on your own L1, but if you want to have more control on the data; who can deploy smart contracts, isolating your data for compliance/KYC reasons, or who can validate transactions, then you will absolutely need an L1.

If you do have to create an L1 - the primary cost of running it is the infrastructure required to support the validator set. Once you establish an appropriate number of validators based on your security requirements, the operational costs become mostly fixed. These costs are independent of the number and complexity of the transactions processed on your chain, providing predictable financial outlays as your application scales.

### Token Location
Choose based on where your security and token economics must live. If your token must be native to the protocol (gas token, staking/slashing, fee burn/distribution, protocol‑level issuance or supply rules) and you need validator/permissioning guarantees, a custom L1 is appropriate. If your token’s utility is application‑level (access, rewards, governance without base‑fee mechanics) and you benefit from public‑chain security and liquidity, a dApp with an ERC‑20 on a public chain is the simpler path. Decide whether the required guarantees are protocol‑layer (L1) or app‑layer (public chain).

Launching a blockchain application on a public permissionless blockchain or spinning up your own L1 on Lux is a decision that depends heavily on your application's transaction profile and economic model. Ultimately, the decision should be driven by a careful analysis of your transaction patterns, user experience goals, what will be the token utilty and the potential for fee volatility in public networks. By weighing these factors, you can make an informed decision that aligns with your application's long-term success.

#### *Use-case Example*

*Gaming application where users frequently make micro-transactions, high transaction fees on a public blockchain could be a significant barrier to user retention. By deploying your own L1, you can minimize or even eliminate these fees, thereby enhancing the user experience and driving higher engagement. This is particularly relevant for applications that target mainstream audiences, where a seamless and cost-effective user experience is paramount.*

**Live Proof**: [Off The Grid](https://gunzillagames.com/en/) uses a dedicated Lux L1 to power a player‑driven economy with on‑chain item ownership (NFTs) and currency ($GUNZ).

# Welcome to the Course (/academy/avalanche-l1/l1-native-tokenomics)

---
title: Welcome to the Course
description: Learn about the L1 Native Tokenomics
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Smile
---

Welcome to the **L1 Native Tokenomics** course! This course is designed to give you a deep understanding of how to create and manage native tokens on your own Lux L1 blockchain. 

By the end of this course, you will have practical skills in designing tokenomics, configuring native token allocation, and leveraging precompiles to create powerful token economies.

## Prerequisites

Before starting this course, you should have completed the [Blockchain Fundamentals](/academy/blockchain-fundamentals) and [Lux Fundamentals](/academy/lux-l1/lux-fundamentals) courses of the [Lux Developers Academy](https://build.lux.network/academy#:~:text=Choose%20Your%20Learning%20Path) learning tree.

## Learning Outcomes

By the end of this course, you will:

- **Understand Token Fundamentals**: Gain deep insights into what tokens are, their differences, and the implications of creating native tokens versus ERC20 tokens.
- **Master Native Token Creation**: Learn how to create custom native tokens and understand when you need them versus when ERC20 tokens are sufficient.
- **Leverage Precompiles**: Understand how to use the Native Minter and Fee Config Precompiles to create powerful tokenomics.
- **Design Token Distribution**: Create effective vesting schedules, bonding curves, and airdrop strategies for your native tokens.
- **Implement Governance**: Develop governance structures including DAOs and quadratic voting models for decentralized decision-making.

But before diving into the technical implementation, we've included two essential think pieces to help you make informed decisions:

**Essential Reading**: [Dapp vs L1](/academy/lux-l1/l1-native-tokenomics/dappVsL1) - A critical analysis to determine whether your use case actually requires its own L1 with native tokenomics, or if deploying on an existing chain would be more appropriate.

**Highly Recommended**: [Token Ownership](/academy/lux-l1/l1-native-tokenomics/token-ownership) - Not strictly necessary for implementation, this deep dive into the philosophical and practical aspects of token ownership will give you a much richer understanding of the underlying concepts at play in tokenomics design.


# Token Ownership (/academy/avalanche-l1/l1-native-tokenomics/token-ownership)

---
title: Token Ownership
description: Everything you need to know about token ownership on blockchains
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Key
---

## A Short History and Why It Matters

Token ownership means recording who controls a digital asset on a public ledger, enforced by cryptography and consensus rather than by legal registries alone. It unlocks portable, programmable, and verifiable property rights for anything that can be represented in bits.

### From Scarcity to Programmability

- Bitcoin (2009) solved digital scarcity and established provable, bearer‑style ownership “by code.”
- Ethereum (2015) generalized ownership with smart contracts, enabling tokens: programmable representations of value, access, or rights. The 2014–2018 wave of token sales showed how ownership could be distributed globally without intermediaries—sometimes as utility access, sometimes (mistakenly) as implied equity. The lesson: tokens coordinate, but value capture must be designed, not assumed.

### What “Ownership” Means On‑Chain

On blockchains, ownership is:
- Verifiable: anyone can audit balances and provenance.
- Portable: assets move across apps and wallets with private keys.
- Programmable: rights can encode governance, access, royalties, staking, or fee distribution.
- Composable: tokens integrate with DeFi, marketplaces, and tooling by common standards.

### Token Classes at a Glance

<img src="/common-images/l1-native-tokenomics/L1NT-TokenClassification.png" alt="Classification of crypto assets" style={{ maxWidth: '100%', borderRadius: '8px' }} />

At a high level:
- Fungible tokens (e.g., ERC‑20) track interchangeable units (balances, payments, governance power).
- Non‑fungible tokens (e.g., ERC‑721) track unique items and their provenance (collectibles, credentials, rights).
- Hybrids and multi‑tokens (e.g., ERC‑1155) combine both models for efficient gaming/commerce flows.

### Why Tokenized Ownership Works

Tokens drastically reduce friction to distribute and align ownership. Like equity, they can motivate long‑term contribution; unlike equity, they are programmable (e.g., automatic reward streams, on‑chain voting) and readily tradable. But not every token confers the same rights: designs differ in value capture (fee burns, staking rewards, access discounts), transferability, and governance—and must consider regulation.

### Looking Ahead

As you move into native tokens and ERC‑20s next, keep this lens: token ownership is a coordination primitive. Good designs clearly define what is owned (rights), how value accrues (mechanics), and how ownership changes hands (standards and controls). With those pillars, tokens become reliable building blocks for open, interoperable economies.

# Course Completion Certificate (/academy/avalanche-l1/interchain-token-transfer/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="interchain-token-transfer"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/avalanche-l1/interchain-token-transfer)

---
title: Welcome to the Course
description: Learn about sending assets to another L1s with Lux Interchain Token Transfer.
updated: 2024-05-31
authors: [ashucoder9]
icon: Smile
---

In this course, you will learn how to transfer assets across multiple Lux blockchains with Lux Interchain Token Transfer ICTT.

## Why Take This Course?

A significant innovation in blockchain is the development of multi-chain systems, like Lux, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains that communicate. Each chain's VM is optimized for specialized use cases, thereby boosting the network's overall performance.

Cross-chain communication is a crucial building block of multi-chain systems. Utilizing Lux Interchain Messaging and Interchain Token Transfer is an incredibly easy way to build cross-Lux L1 dApps, since developers can build on top of an extensive, audited development framework. 

Transfering tokens between multiple chains is a common use case in multi-chain systems. This course will help you understand how to transfer assets between multiple Lux blockchains using the Lux Interchain Token Transfer protocol.

<Callout>
This course focuses on using the existing testnet chains (Testnet LUExchange-Chain, Echo, and Dispatch). If you want to create your own L1 blockchain, please refer to the [Creating an L1](/academy/lux-l1/lux-fundamentals/04-creating-an-l1/01-creating-an-l1) course.
</Callout>

<Callout>
Since Interchain Token Transfer relies on Interchain Messaging (ICM), you must run your own relayer to enable cross-chain communication. Follow the [Running a Relayer](/academy/interchain-messaging/09-running-a-relayer/01-relayer-introduction) course to set up your relayer.
</Callout>

## Course Content

### Getting Started with Interchain Token Transfer

In this section, you will learn how to use our Interchain Token Transfer toolbox to perform cross-chain operations. We'll guide you through the process of using our user-friendly interface to deploy contracts, create bridges, and transfer assets across the testnet chains (Testnet LUExchange-Chain, Echo, and Dispatch).

### Tokens and Token Types

In this section, you will learn about the different types of tokens that can be transferred between Lux blockchains. We will cover ERC-20 and native tokens and how to deploy and transfer them using our toolbox. Furthermore, you will learn what wrapped native tokens are and how they can be used to transfer assets between chains.

### Token Bridging

Next we will talk about the high level concepts of token bridging and demonstrate how to use our toolbox to create and manage bridge contracts for cross-chain transfers between the testnet chains.

### Interchain Token Transfer Architecture

In this chapter we will look at the design of Lux Interchain Token Transfer. You will learn about the file structure of the contracts and the concepts of the token home and token remote.

### ERC-20 to ERC-20 Bridge Implementation

You will learn how to use our toolbox to deploy ERC-20 tokens and create bridges to transfer them between the testnet chains.

### Multi-Chain Token Operations

Here you will learn about the concept of multi-hops and how to use our toolbox to bridge tokens between multiple testnet chains.

### Native to ERC-20 Bridge Implementation

In this chapter you will learn how to use our toolbox to bridge a native token as an ERC-20 token to another testnet chain.

### Send and Call Operations

In this chapter you will learn how to use our toolbox to call smart contracts with the tokens after sending them to another testnet chain.

### Cross-Chain Token Swaps

In this chapter you will learn how to perform cross-chain token swaps between the testnet chains using our toolbox.

## Prerequisites

### Lux Knowledge

This course is intended for people with knowledge about Cross-Chain communication protocols, and a solid understanding of the basic concepts of Lux. You should be familiar with these concepts:

1. Lux Architecture: Be familiar with Lux blockchains.
2. Interchain Messaging: Know how to communicate between two Lux blockchains with ICM. 

If some of this is not clear, we strongly recommend taking the Lux Fundamentals, Multi-Chain Architecture, and Interchain Messaging courses first.

### Software Development

You will need a general understanding of how to use Web3 applications. We recommend:

1. Basic understanding of how to use Core Wallet
   - Download from [core.app](https://core.app)

2. Test tokens for development
   - **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet tokens automatically
   - **Alternative:** Use external faucets like [core.app/tools/testnet-faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code `lux-academy`

3. Understanding of token standards (ERC-20, etc.)

## Learning Outcomes

By the end of this course, you will:

- Understand what Lux Interchain Token Transfer is and when to use it.
- Understand the different options for transferring assets between multiple chains.
- Be able to deploy tokens and create bridges using our toolbox.
- Be able to perform cross-chain token transfers between testnet chains using our toolbox.
- Apply the knowledge gained in the course by enabling assets to be transferred between multiple Lux blockchains.

# Course Completion Certificate (/academy/avalanche-l1/permissionless-l1s/certificate)

---
title: Course Completion Certificate
description: Get your completion certificate for the Permissioned L1s course
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="permissioned-l1s"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/avalanche-l1/permissionless-l1s)

---
title: Welcome to the Course
description: Learn about L1 Validator Management for Permissionless Blockchains
updated: 2025-01-15
authors: [nicolasarnedo]
icon: Smile
---

## Permissionless L1s 

Welcome to the **Permissionless L1s** course! This course is designed to give you a deep understanding of configuring, launching and maintaining permissionless L1s on Lux. 

By the end of this course, you will have practical skills in deploying an L1 with Proof of Stake (PoS) consensus and managing the validator set in a permissionless
network.


### Prerequisites

Before starting this course, we recommend completing:
- [L1 Native Tokenomics](/academy/l1-native-tokenomics) - Understanding tokenomics fundamentals
- [Permissioned L1s](/academy/permissioned-l1s) - Foundation in L1 validator management

If you just completed these recently, you can go ahead and skip the [Review chapter](). If not, we recommend giving it a read, it will cover:

- Platform-Chain fundamentals
- Multi-Chain Architecture
- Permissioned L1s  
- Native Tokenomics

### What You'll Learn

This comprehensive course will walk you through:

- **Proof of Stake** - Understanding PoS consensus, staking token selection, and liquid staking considerations
- **Transformation Requirements** - Basic precmpoiles (Native Minter and Reward Manager) needed to transform your L1 into a permissionless network
- **Basic Setup**(*optional*) - Deploying Validator Manager Contract, upgrading proxy, and initializing validator configuration
- **Staking Manager Setup** - Deploying and configuring staking managers for native token staking
- **Staking Manager Operations** - Adding, changing weights, removing validators, and handling delegation
- **Node Licenses** - Understanding validator licensing and real-world examples

### Let's Get Started!

Each section builds upon previous knowledge, so we recommend completing the course in order.

Happy learning and building!

# Course Completion Certificate (/academy/avalanche-l1/permissioned-l1s/certificate)

---
title: Course Completion Certificate
description: Get your completion certificate for the Permissioned L1s course
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="permissioned-l1s"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/avalanche-l1/permissioned-l1s)

---
title: Welcome to the Course
description: Learn about L1 Validator Management for Permissioned Blockchains
updated: 2025-07-15
authors: [nicolasrnedo]
icon: Smile
---

## Permissioned L1s 

Welcome to the **Permissioned L1s** course! This course is designed to give you a deep
understanding of configuring, launching and maintaining permissioned L1s on Lux. By the end of this course, you will have
practical skills in deploying an L1 and managing the validator set in a Proof of Authority (PoA)
network.

## Video

<YouTube id="xgx6VzdR974" params="start=365"/>

### What You'll Learn

This comprehensive course will walk you through:

- **Introduction** - Platform-Chain review, how Validator Manager Contracts use ICM & commonlys used Proxy Patterns
- **Proof of Authority** - Understanding permissioning types for blockchains, what Proof of Authority is and the Validator Manager contract structure
- **Create an L1** - Creating a Subnet, diving deep into the Transparent Proxy pattern, understanding genesis pre-deployed contracts and creating your L1 (recommended to first have created an L1 in the [Lux Fundamentals course](/academy/lux-l1/lux-fundamentals))
- **Validator Manager Deployment** - Deploying and configuring the Validator Manager Contract (VMC) on your new L1
- **Validator Manager Operations** - Adding, changing weights and removing validators
- **Coming Soon... Multi-Sig Setup for PoA** - Implementing secure multi-signature governance with Safe/Ash wallets
- **Coming Soon... Private L1s** - Configuring validator-only access and RPC node restrictions

### Let's Get Started!

Each section builds upon previous knowledge, so we recommend completing the course in order.

Happy learning and building!

# Understanding ERC-721 Tokens (/academy/blockchain/nft-deployment/01-erc721-standard)

---
title: Understanding ERC-721 Tokens
description: Learn about the Non-Fungible Token Standard
updated: 2024-11-20
authors: [nicolasarnedo]
icon: Book
---

Previously, we explored the ERC-20 interface, a contract standard which allowed for the implementation of fungible tokens. However, there is one important use case that the ERC-20 standard cannot support: **non-fungible assets**.

## What is Fungibility?

To understand why we need ERC-721, let's first understand fungibility:

- **Fungible tokens** (ERC-20): Each token is identical and interchangeable. 1 USDC is always equal to 1 USDC.
- **Non-fungible tokens** (ERC-721): Each token is unique and has its own distinct value. One piece of digital art is not equal to another.

## Why ERC-721?

Imagine you wanted to represent an art collection within a smart contract. The smart contract would need:

- The ability to query the "balance" (i.e. the art holdings) of a particular user
- The ability to transfer art pieces from one account to another
- The ability to get information about the art collection

The biggest difference between an ERC-20 token contract and an art collection is the **fungibility** of individual items. ERC-20 tokens are inherently fungible, while items in an art collection are not (since each piece varies in value).

To account for use cases like art collections, digital collectibles, gaming items, and more, the **ERC-721 standard** was introduced.

## The ERC-721 Interface

Formally, ERC-721 is a standard for non-fungible tokens. Below is the interface of the ERC-721 token from its original proposal:

```solidity
interface ERC721 {
    /// @dev This emits when ownership of any NFT changes by any mechanism.
    event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);

    /// @dev This emits when the approved address for an NFT is changed or reaffirmed.
    event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId);

    /// @dev This emits when an operator is enabled or disabled for an owner.
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);

    /// @notice Count all NFTs assigned to an owner
    function balanceOf(address _owner) external view returns (uint256);

    /// @notice Find the owner of an NFT
    function ownerOf(uint256 _tokenId) external view returns (address);

    /// @notice Transfers the ownership of an NFT from one address to another address
    function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data) external payable;

    /// @notice Transfers the ownership of an NFT from one address to another address
    function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable;

    /// @notice Transfer ownership of an NFT
    function transferFrom(address _from, address _to, uint256 _tokenId) external payable;

    /// @notice Change or reaffirm the approved address for an NFT
    function approve(address _approved, uint256 _tokenId) external payable;

    /// @notice Enable or disable approval for a third party ("operator") to manage all assets
    function setApprovalForAll(address _operator, bool _approved) external;

    /// @notice Get the approved address for a single NFT
    function getApproved(uint256 _tokenId) external view returns (address);

    /// @notice Query if an address is an authorized operator for another address
    function isApprovedForAll(address _owner, address _operator) external view returns (bool);
}
```

## Key Differences from ERC-20

### Token Identification

**ERC-20:**
```solidity
mapping(address => uint) balances;
```

**ERC-721:**
```solidity
mapping(address => uint) balances;      // Number of NFTs owned by each address
mapping(uint => address) holders;        // Owner of each specific token ID
```

The key difference is the addition of the `holders` mapping, which tracks which address owns each individual token by its unique ID. This allows each token to be distinct and non-fungible.

### Transfer Functions

ERC-721 introduces `safeTransferFrom`, which includes a safety check to ensure the receiving address can handle NFTs. This prevents tokens from being permanently lost if sent to a contract that doesn't support them.

### Approval Mechanism

Like ERC-20, ERC-721 supports approvals, but with two levels:
- **Single token approval**: Approve someone to transfer a specific NFT
- **Operator approval**: Approve someone to manage all your NFTs

## Common Use Cases

ERC-721 tokens are used for:

- **Digital Art**: Unique artwork pieces with verifiable ownership
- **Collectibles**: Trading cards, virtual items, and memorabilia
- **Gaming Assets**: In-game items, characters, and land
- **Real Estate**: Tokenized property ownership
- **Identity**: Unique credentials and certificates
- **Domain Names**: Blockchain-based domain systems

## Next Steps

Now that you understand the ERC-721 standard, you're ready to create your own NFT collection. In the next section, we'll prepare the files needed for your NFTs, including images and metadata.



# Prepare NFT Files (/academy/blockchain/nft-deployment/02-prepare-nft-files)

---
title: Prepare NFT Files
description: Learn how to prepare and upload your NFT images and metadata to IPFS
updated: 2024-11-20
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

The first step of setting up an NFT smart contract is having your NFT files ready to use. In this guide, we'll upload files to [Pinata](https://www.pinata.cloud/), a pinning service that prevents files from being garbage collected on IPFS.

<Callout type="info">
If you don't already have a Pinata account, please [create one](https://www.pinata.cloud/) before proceeding. The free tier is sufficient for this tutorial.
</Callout>

## Preparing the Images

This tutorial will create only 1 NFT, however, if you're interested in creating more, you're more than welcome to do so.

![Original NFT Photo](/images/nft-files1.jpeg)

### Organizing Your Images

1. Create a folder on your computer for your NFT images
2. Name your image file `0` (without any file extension visible)
3. If creating multiple NFTs, continue naming them sequentially: `0`, `1`, `2`, etc.

<Callout type="warn">
**Important**: Some projects start file names with `0`, and others with `1`. That choice must be consistent with your smart contract code. For this tutorial, we'll start with `0`.
</Callout>

![Image Folder](/images/nft-files2.png)

### Uploading Images to Pinata

1. Log into your Pinata dashboard
2. Click the **Upload** button on the left sidebar
3. Select **Folder** from the upload options

![Pinata Dashboard](/images/nft-files3.png)

![Folder Button](/images/nft-files4.png)

4. Select the folder containing your image(s)
5. Confirm the upload if prompted by your browser

![Confirm Upload](/images/nft-files5.png)

6. Give your folder a descriptive name (this helps organize multiple collections)
7. Click **Upload** and wait for the process to complete

Once the upload is complete, you'll see your folder in the dashboard:

![Uploaded Image Folder](/images/nft-files6.png)

### Getting Your Image URL

1. Click on the folder name to view it through the Pinata gateway
2. Right-click on your image and copy the URL
3. Save this URL - you'll need it for the metadata file

Example URL: `https://gateway.pinata.cloud/ipfs/QmPWbixyMsaNkR9v612bBFbncKGmgXDKz9CgMtDDD7Bymw/0.png`

## Creating Metadata Files

Now that we have the image uploaded, we need to create matching metadata files. Since we're creating an ERC-721 NFT, we'll use the standard metadata format used by marketplaces like [Joepegs.com](https://joepegs.com/).

### Metadata Structure

The basic [metadata structure](https://docs.opensea.io/docs/metadata-standards#metadata-structure) looks like this:

```json
{
  "name": "",
  "tokenId": 0,
  "image": "",
  "description": "",
  "attributes": []
}
```

### Populating the Metadata

Let's fill in each field:

- **name**: Choose any name for your NFT
- **tokenId**: Use `0` to correspond with your first image (increment for additional NFTs)
- **image**: Paste the image URL you copied from Pinata
- **description**: Describe your NFT
- **attributes**: Optional array for traits (useful for collections with layers/rarity)

Example completed metadata:

```json
{
  "name": "Cool Photography",
  "tokenId": 0,
  "image": "https://gateway.pinata.cloud/ipfs/QmPWbixyMsaNkR9v612bBFbncKGmgXDKz9CgMtDDD7Bymw/0.png",
  "description": "A cool image"
}
```

<Callout type="info">
The `attributes` field is particularly useful for NFT collections with multiple layers. It's used to calculate rarity and rank NFTs based on how frequently their traits appear throughout the collection. For this simple example, we've omitted it.
</Callout>

### Saving the Metadata File

1. Save this JSON content as a file named `0` (matching your image name)
2. **Remove the file extension** so it's just `0`, not `0.json`
   - [Mac instructions](https://support.apple.com/guide/mac-help/show-or-hide-filename-extensions-on-mac-mchlp2304/mac)
   - [Windows instructions](https://www.techwalla.com/articles/how-to-remove-file-extensions)

<Callout type="warn">
**Critical**: The metadata file must NOT have a `.json` extension when uploaded to Pinata. The IPFS gateway will serve it as a directory, and your smart contract will be able to fetch it correctly.
</Callout>

3. Place the metadata file in a **separate folder** from your images

![Metadata Folder](/images/nft-files7.png)

### Uploading Metadata to Pinata

1. Repeat the folder upload process for your metadata folder
2. Follow the same steps as you did for the images
3. Once uploaded, both folders should appear in your dashboard

![Uploaded Folders](/images/nft-files8.png)

### Getting Your Base URI

1. Click on the **metadata folder** to view it in the IPFS gateway
2. Copy the URL - this is your **Base URI**
3. **Important**: Use only the folder URL, not the individual file URL

Example Base URI: `https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa`

The smart contract will automatically append the token ID to this base URI when fetching metadata for each NFT.

## File Preparation Checklist

Before moving to the next section, ensure you have:

- ✅ Images uploaded to Pinata in a folder
- ✅ Metadata files created with correct structure
- ✅ Metadata files named to match image files (0, 1, 2, etc.)
- ✅ Metadata files uploaded to Pinata in a **separate** folder
- ✅ Base URI copied and saved

## Next Steps

Now that your NFT files are prepared and uploaded to IPFS, you're ready to create and deploy your smart contract. In the next section, we'll use OpenZeppelin's Contract Wizard to generate an ERC-721 contract customized for your collection.



# Create Your NFT Smart Contract (/academy/blockchain/nft-deployment/03-create-smart-contract)

---
title: Create Your NFT Smart Contract
description: Use OpenZeppelin to generate a customized ERC-721 contract
updated: 2024-11-20
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

Now that your NFT files are prepared, it's time to create the smart contract that will manage your NFT collection. We'll use [OpenZeppelin](https://docs.openzeppelin.com/), a trusted library for building secure smart contracts.

## Why OpenZeppelin?

OpenZeppelin provides battle-tested, audited smart contract implementations that follow industry standards. Their [Contract Wizard](https://wizard.openzeppelin.com/#erc721) allows you to generate customized contracts without writing code from scratch, reducing the risk of security vulnerabilities.

## Using the Contract Wizard

### Step 1: Access the Wizard

Navigate to [wizard.openzeppelin.com/#erc721](https://wizard.openzeppelin.com/#erc721)

![Contract Wizard](/images/nft-collection4.png)

### Step 2: Select ERC-721

Make sure the **ERC-721** tab is selected. This will create a contract in the [Solidity programming language](https://docs.soliditylang.org/) specifically for non-fungible tokens.

### Step 3: Configure Basic Settings

The wizard provides a template contract that you'll customize:

**Name**: Give your NFT collection a name (e.g., "Photography")
**Symbol**: Choose a short symbol for your collection (e.g., "FOTO")
**Base URI**: Paste the metadata folder URL you saved from Pinata

Example: `https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa`

![Contract Wizard Populated](/images/nft-collection5.png)

### Step 4: Add Minting Functionality

Check the following boxes to add essential features:

**Mintable**: Adds a `safeMint` function to create new NFTs
**Auto Increment Ids**: Automatically assigns sequential token IDs

This will automatically check **Ownable**, which restricts the `safeMint` function to the contract owner.

![Contract Wizard SafeMint](/images/nft-collection6.png)

## Understanding the Generated Contract

Let's examine the key parts of your generated contract:

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

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract Photography is ERC721, Ownable {
    uint256 private _nextTokenId;
    string private _baseTokenURI;

    constructor(address initialOwner)
        ERC721("Photography", "FOTO")
        Ownable(initialOwner)
    {
        _baseTokenURI = "https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa/";
    }

    function _baseURI() internal view override returns (string memory) {
        return _baseTokenURI;
    }

    function safeMint(address to) public onlyOwner {
        uint256 tokenId = _nextTokenId++;
        _safeMint(to, tokenId);
    }
}
```

### Key Components

**Inheritance**: Your contract inherits from `ERC721` (the standard) and `Ownable` (access control)

**Constructor**: Sets the collection name, symbol, and base URI when deployed

**_baseURI()**: Returns the base URI that will be combined with token IDs to fetch metadata

**safeMint()**: Creates new NFTs and assigns them sequential IDs

<Callout type="info">
The `onlyOwner` modifier means only the contract owner can mint NFTs. For a public mint, you would remove this modifier and add payment logic.
</Callout>

## About the safeMint Function

The current `safeMint` function:
- Mints one NFT at a time
- Can mint to any address (not just the owner's)
- Charges no fee (except gas)
- Functions as an "airdrop" mechanism

This is perfect for:
- Personal collections
- Gifting NFTs
- Controlled distributions
- Testing your contract

For a public sale, you would modify this function to:
- Accept payment (e.g., `payable` with price checks)
- Remove the `onlyOwner` modifier
- Add supply limits
- Implement per-wallet minting limits

## Next Steps

Your smart contract is now ready! Click **Open in Remix** at the top of the wizard to prepare for deployment.

![Contract Wizard Open Remix](/images/nft-collection7.png)

In the next section, we'll deploy this contract to the Lux network and mint your first NFT.



# Deploy and Mint Your NFT (/academy/blockchain/nft-deployment/04-deploy-and-mint)

---
title: Deploy and Mint Your NFT
description: Deploy your ERC-721 contract to Lux and mint your first NFT
updated: 2024-11-20
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

Now it's time to deploy your NFT smart contract to the Lux network and mint your first NFT!

## Prerequisites

Before deploying, ensure you have:

### Core Wallet Extension

You'll need the Core browser extension to fund and deploy your contract. If you haven't installed it yet:

1. Download [Core Extension](https://chrome.google.com/webstore/detail/core-crypto-wallet-nft-ex/agoakfejjabomempkjlepdflaleeobhb)
2. Create or import a wallet
3. Enable **Testnet Mode**:
   - Go to **Settings** → **Advanced**
   - Turn on **Testnet Mode**
   - Core will automatically switch to Testnet Testnet

![Settings image 1](/images/nft-collection1.png)

![Settings image 2](/images/nft-collection2.png)

<Callout type="info">
**Other Wallets**: If using MetaMask or another wallet, add Testnet Testnet manually:
- **Network Name**: Lux Testnet LUExchange-Chain
- **RPC URL**: `https://api.lux-test.network/ext/bc/C/rpc`
- **Chain ID**: `43113`
- **Symbol**: LUX
- **Explorer**: `https://testnet.snowtrace.io`
</Callout>

### Testnet LUX

You'll need LUX on the Testnet testnet to pay for gas fees.

**Option 1 (Recommended)**: 
- Create a [Lux Build account](https://build.lux.network/login)
- Connect your wallet to receive testnet LUX automatically

**Option 2**: 
- Use the [Lux Faucet](https://core.app/tools/testnet-faucet/)
- If you have LUX on Mainnet, paste your LUExchange-Chain address and request test tokens
- Otherwise, request a faucet coupon on [Guild](https://guild.xyz/lux)

![Lux Faucet](/images/nft-collection3.png)

## Deploying with Remix IDE

[Remix IDE](https://remix.ethereum.org/) is a browser-based Solidity compiler that makes it easy to compile and deploy smart contracts without installing any software.

### Step 1: Compile Your Contract

After importing your contract from OpenZeppelin Wizard:

1. Click the **Compile** button on the left sidebar (or press `Ctrl/Cmd + S`)
2. Wait for the green checkmark to appear

![Remix Compile](/images/nft-collection8.png)

<Callout type="info">
You may see options to "Publish on IPFS" or "Publish on Swarm" - these aren't necessary for this tutorial.
</Callout>

### Step 2: Configure Deployment

1. Click the **Deploy & Run Transactions** tab (bottom icon on left sidebar)

![Remix Deploy Page](/images/nft-collection9.png)

2. Change the **Environment** dropdown to **Injected Provider - MetaMask**

![Remix Web3](/images/nft-collection10.png)

3. Core will prompt you to connect - approve the connection

4. Verify the connection by checking that the **Account** matches your Core address

![Remix account](/images/nft-collection11.png)

![Core account](/images/nft-collection12.png)

### Step 3: Select Your Contract

In the **Contract** dropdown, select your contract (it will have the name you gave it in the wizard).

![Remix Contract](/images/nft-collection13.png)

### Step 4: Deploy

1. Click the orange **Deploy** button
2. Core will open and ask you to confirm the transaction
3. Review the gas fee and click **Confirm**

![Core Accept](/images/nft-collection14.png)

4. Wait for the transaction to be confirmed

Your deployed contract will appear under **Deployed Contracts**:

![Remix Record](/images/nft-collection15.png)

### Step 5: Verify on Snowtrace

1. Copy your contract address from Remix
2. Open [Snowtrace Testnet Explorer](https://testnet.snowtrace.io/)
3. Paste the address in the search bar

You'll see your contract information, including the deployment transaction:

![Snowtrace](/images/nft-collection16.png)

## Minting Your First NFT

Now that your contract is deployed, let's mint an NFT!

### Step 1: Access the safeMint Function

1. In Remix, expand your deployed contract
2. You'll see a list of available functions

![Remix Functions](/images/nft-collection17.png)

3. Click the dropdown arrow next to **safeMint** to expand it

![safeMint function](/images/nft-collection18.png)

### Step 2: Mint to Your Address

1. Copy your Core wallet address
2. Paste it into the `to` address field
3. Click the orange **transact** button

<Callout type="info">
You can mint to any address, not just your own. This is useful for gifting NFTs or airdrops!
</Callout>

4. Confirm the transaction in Core
5. Wait for the green checkmark in the Remix terminal

![Remix Confirm Mint](/images/nft-collection19.png)

### Step 3: Verify the Mint

1. Return to your contract page on Snowtrace
2. Refresh the page
3. You should see a new transaction for `safeMint`

![Snowtrace Mint](/images/nft-collection20.png)

4. Click on the [TX Hash](https://testnet.snowtrace.io/tx/0x8b698ac72bd20b2a640167c5d9bacdcbb3d86fd696eb8cde6f28347f6f99a2c9) to view details

![Snowtrace Transaction](/images/nft-collection21.png)

Congratulations! You've successfully minted your first NFT! 🎉

## Viewing Your NFT

Your NFT is now:
- Recorded on the Lux blockchain
- Owned by your wallet address
- Linked to your metadata and image on IPFS

You can view it:
- On Snowtrace (under the "Token Transfers" tab)
- In your Core wallet (NFT section)
- On NFT marketplaces that support Lux testnet

## Deploying to Mainnet

When you're ready to launch your project on Mainnet, the process is identical except:

1. **Switch to Mainnet**: Disable Testnet Mode in Core
2. **Get Real LUX**: You'll need actual LUX to pay for gas fees
3. **Use Mainnet Snowtrace**: View transactions at [snowtrace.io](https://snowtrace.io/)
4. **List on Marketplaces**: Your NFTs can be listed on platforms like [Joepegs](https://joepegs.com/)

<Callout type="warn">
**Before Mainnet Deployment**:
- Thoroughly test your contract on testnet
- Consider a professional audit for valuable collections
- Ensure your IPFS files are permanently pinned
- Have a clear minting strategy and pricing
</Callout>

## Next Steps

Now that you've deployed and minted your NFT, you might want to:

- Mint additional NFTs from your collection
- Learn about token URIs and metadata standards
- Explore advanced features like royalties and allowlists
- Build a custom minting dApp for your collection

In the next section, we'll dive deeper into how token URIs work and how your NFTs connect to their metadata.



# Understanding Token URIs (/academy/blockchain/nft-deployment/05-token-uris)

---
title: Understanding Token URIs
description: Learn how NFTs connect to their metadata and images
updated: 2024-11-20
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

Now that you've deployed your NFT collection, let's understand how your on-chain tokens connect to their off-chain metadata and images through **Token URIs**.

## What is a Token URI?

A Token URI (Uniform Resource Identifier) is a unique string that points to a JSON file containing an NFT's metadata. This metadata includes:

- The NFT's name
- Description
- Image URL
- Attributes/traits
- Other properties

## How Token URIs Work

When you call `tokenURI(tokenId)` on an ERC-721 contract, it returns a complete URL by combining:

```
Base URI + Token ID = Token URI
```

### Example

If your base URI is:
```
https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa/
```

And you query token ID `0`, the contract returns:
```
https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa/0
```

This URL points to your metadata file on IPFS.

## The Metadata Standard

The JSON file at the Token URI follows the [OpenSea Metadata Standard](https://docs.opensea.io/docs/metadata-standards):

```json
{
  "name": "Cool Photography #0",
  "description": "A cool image from my photography collection",
  "image": "https://gateway.pinata.cloud/ipfs/QmPWbixyMsaNkR9v612bBFbncKGmgXDKz9CgMtDDD7Bymw/0.png",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Blue"
    },
    {
      "trait_type": "Style",
      "value": "Abstract"
    }
  ]
}
```

### Metadata Fields

**name**: The NFT's display name (often includes the token ID)

**description**: A detailed description of the NFT

**image**: The URL to the actual image file (also on IPFS)

**attributes**: An array of traits that define the NFT's characteristics

## Why Use IPFS?

IPFS (InterPlanetary File System) is preferred for NFT storage because:

**Decentralized**: No single point of failure
**Content-Addressed**: Files are identified by their content, not location
**Permanent**: Files remain accessible as long as they're pinned
**Immutable**: Content can't be changed without changing the hash

### IPFS URLs

IPFS URLs follow this format:
```
https://gateway.pinata.cloud/ipfs/[CONTENT_HASH]/[FILE_NAME]
```

The content hash (e.g., `QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa`) uniquely identifies your folder on IPFS.

## URI Storage in Your Contract

In your OpenZeppelin contract, the base URI is stored and accessed like this:

```solidity
contract Photography is ERC721, Ownable {
    string private _baseTokenURI;

    constructor(address initialOwner)
        ERC721("Photography", "FOTO")
        Ownable(initialOwner)
    {
        _baseTokenURI = "https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa/";
    }

    function _baseURI() internal view override returns (string memory) {
        return _baseTokenURI;
    }

    function tokenURI(uint256 tokenId) public view virtual override returns (string memory) {
        require(_exists(tokenId), "Token does not exist");
        return string(abi.encodePacked(_baseURI(), Strings.toString(tokenId)));
    }
}
```

### How It Works

1. `tokenURI()` is called with a token ID
2. The function checks if the token exists
3. It concatenates the base URI with the token ID
4. Returns the complete URL to the metadata

## Advanced URI Features

### URI Storage Extension

OpenZeppelin provides a `ERC721URIStorage` extension that allows setting individual URIs for each token:

```solidity
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";

contract MyNFT is ERC721URIStorage {
    function mint(address to, uint256 tokenId, string memory uri) public {
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
    }
}
```

This is useful when:
- Each NFT has a completely different metadata structure
- You want to update metadata after minting
- Your collection doesn't follow a sequential pattern

### Updating Base URI

You might want to update the base URI after deployment to:
- Move to a different IPFS gateway
- Migrate to a custom domain
- Update to revealed metadata (for mystery drops)

Add this function to your contract:

```solidity
function setBaseURI(string memory newBaseURI) public onlyOwner {
    _baseTokenURI = newBaseURI;
}
```

<Callout type="warn">
Be cautious when updating URIs. Changing metadata after minting can be controversial and may affect trust in your collection.
</Callout>

## Best Practices

### 1. Consistent File Naming

Ensure your metadata files are named to match token IDs:
- Token 0 → file named `0`
- Token 1 → file named `1`
- And so on...

### 2. Include Trailing Slash

Always include a trailing slash in your base URI:
```
✅ https://gateway.pinata.cloud/ipfs/QmHash/
❌ https://gateway.pinata.cloud/ipfs/QmHash
```

### 3. Test Before Minting

Before minting, manually test your URIs:
```
Base URI + 0 should return valid JSON
Base URI + 1 should return valid JSON
```

### 4. Pin Your Files

Ensure your files are permanently pinned on IPFS. Services like Pinata provide pinning to prevent garbage collection.

### 5. Use IPFS Gateways Wisely

While Pinata's gateway works well, consider:
- Using multiple gateways for redundancy
- Setting up your own IPFS node for large collections
- Using a CDN for faster loading

## Viewing Token URIs

You can view your NFT's token URI in several ways:

### 1. Remix IDE

In your deployed contract, call `tokenURI` with a token ID:

```solidity
tokenURI(0) // Returns the full URI for token 0
```

### 2. Snowtrace

On your contract page, go to "Read Contract" and call `tokenURI`.

### 3. Programmatically

Using ethers.js:
```javascript
const tokenURI = await contract.tokenURI(0);
console.log(tokenURI);
```

## Common Issues

### "Token does not exist"

This error means you're querying a token ID that hasn't been minted yet.

### 404 Not Found

If the URI returns 404:
- Check that your metadata files are uploaded to IPFS
- Verify the file names match token IDs
- Ensure the base URI has a trailing slash

### Invalid JSON

If marketplaces can't read your metadata:
- Validate your JSON syntax
- Ensure all required fields are present
- Check that the file has no extension

## Next Steps

Now that you understand how token URIs work, you're ready to:

- Create larger NFT collections with multiple tokens
- Implement reveal mechanisms for mystery drops
- Build custom metadata structures for your use case
- Integrate your NFTs with marketplaces and dApps

Congratulations on completing the NFT Deployment course! You now have the knowledge to create, deploy, and manage your own NFT collections on Lux.



# Welcome to NFT Deployment (/academy/blockchain/nft-deployment)

---
title: Welcome to NFT Deployment
description: Learn how to create, prepare, and deploy your own NFT collection on Lux
updated: 2024-11-20
authors: [Andrea Vargas, Ash, martineckardt]
icon: Smile
---

In this course, you will learn how to deploy your own NFT (Non-Fungible Token) collection on the Lux network.

## Why Take This Course?

NFTs have revolutionized digital ownership, enabling creators to tokenize unique digital assets like art, collectibles, and more. This course will guide you through the entire process of creating and deploying an NFT collection, from understanding the ERC-721 standard to preparing your files and deploying your smart contract.

## Course Content

### ERC-721 Token Standard
Learn about the ERC-721 standard, the foundation for non-fungible tokens, and understand how it differs from fungible tokens like ERC-20.

### Preparing NFT Files
Discover how to prepare your NFT images and metadata files, and upload them to IPFS using Pinata for decentralized storage.

### Creating the Smart Contract
Use OpenZeppelin's Contract Wizard to generate a customized ERC-721 smart contract for your NFT collection.

### Deploying on Lux
Deploy your NFT collection to the Lux LUExchange-Chain using Remix IDE and mint your first NFT.

### Understanding Token URIs
Learn how token URIs work and how they connect your on-chain NFTs to their off-chain metadata and images.

## Prerequisites

### Blockchain / Web3
This course is meant for people with some experience in web3. You should be familiar with:
- **Wallets**: What they are and how to create one
- **dApps**: What a decentralized application is and how to interact with one
- **Transactions**: How to send and confirm blockchain transactions

If any of this is unclear, we strongly recommend taking the Blockchain Fundamentals course first.

### Software Development
You will need a general understanding of software development:
- **Programming**: Familiarity with basic programming concepts like variables, functions, and data structures
- **Solidity Basics**: Understanding of smart contracts (covered in the Intro to Solidity course)
- **IDE**: Familiarity with web-based development tools like Remix

## Learning Outcomes

By the end of this course, you will be able to:

- Understand the ERC-721 token standard and how NFTs work
- Prepare and upload NFT files to IPFS using Pinata
- Create a customized ERC-721 smart contract using OpenZeppelin
- Deploy your NFT collection to Lux LUExchange-Chain
- Mint NFTs from your deployed contract
- Understand token URIs and metadata standards
- View your NFTs on blockchain explorers

## Tools You'll Use

- **Pinata**: For storing NFT images and metadata on IPFS
- **OpenZeppelin Wizard**: To generate your ERC-721 smart contract
- **Remix IDE**: To compile and deploy your contract
- **Core Wallet**: To manage transactions and pay gas fees
- **Snowtrace**: To view your deployed contract and transactions



# Welcome to the course (/academy/blockchain/encrypted-erc)

---
title: Welcome to the course
description: Learn about the encrypted-ERC (eERC) token standard from AvaCloud.
updated: 2025-07-21
authors: [alejandro99so]
icon: Lock
---

Welcome to the **eERC Token Standard** course! This course is designed to give you a deep understanding of encrypted ERC (eERC), a privacy preserving ERC-20 like token standard developed by AvaCloud, enabling confidential transactions on EVM-compatible blockchains. By the end of this course, you will understand the privacy limitations of traditional token standards, how eERC solves them, and how to create and integrate your own private tokens.

## Course Content

### 1. What is a Digital Asset?
- **Standards**: ERC-20, ERC-721, ERC-1155
- **Current Uses**: How companies, DeFi protocols, and projects are using them today.
- **Limitations**: Challenges companies face when trying to adopt these standards (scalability, privacy, compliance).

### 2. Real Privacy
- **How Private is the Blockchain?**: Transparency vs confidentiality.
- **Compliance**: Why regulatory alignment matters for privacy tokens.
- **Necessities Solved with Privacy**: Situations where privacy is essential (e.g., sensitive transactions, enterprise use).

### 3. Encrypted Tokens
- **What Kind of Privacy Does eERC Provide?**: Hidden balances, confidential transfers.
- **Comparison: ERC-20 vs eERC**: Feature-by-feature breakdown.
- **Technology Behind eERC**: Zero-knowledge proofs and homomorphic encryption.

### 4. Usability of eERC
- **Standalone vs Converter Contract**: When to use each mode.
- **Use Cases**: From DeFi to regulated financial institutions.

### 5. eERC Contracts Flow
- **Step-by-Step**: Creating your own eERC token and considerations.
- **Kinds of ZKProof to Use**: Selection criteria based on use case.
- **User Flow**: How to interact with eERC as an end user.

---

## Prerequisites

Before starting this course, you should have:

### Blockchain Fundamentals
Familiarity with EVM-based blockchains and ERC token standards.

### Development Tools
Basic knowledge of Solidity and comfort using TypeScript will help, especially when working with the Privacy functions.

---

## Learning Outcomes

By the end of this course, you will:

- Understand the **purpose and innovation** behind the eERC standard.
- Compare **traditional ERC standards** with encrypted ERC for privacy and compliance.
- Identify the **key benefits, architecture, and technical underpinnings** of eERC.
- Differentiate between **Standalone** and **Converter** implementation modes.
- Recognize **real-world use cases** where privacy and auditability are essential.
- Create and deploy your own **eERC token** following a step-by-step process.
- Understand how to **interact with eERC as a user** in different scenarios.


# Course Completion Certificate (/academy/blockchain/blockchain-fundamentals/get-certificate)

---
title: Course Completion Certificate
updated: 2025-30-10
authors: [ashucoder9]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="blockchain-fundamentals"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/blockchain/blockchain-fundamentals)

---
title: Welcome to the Course
description: Learn about the basics of blockchain technology.
updated: 2025-10-30
authors: [ashucoder9]
icon: Smile
---

Welcome to the Blockchain Fundamentals, an online course introducing you to blockchain! This course will provide you with a comprehensive understanding of the basic concepts of blockchains.

By the end of these courses, you'll have the knowledge and skills to leverage the power of blockchain technology for your own projects and applications. We're excited to have you join us on this journey and can't wait to see what you'll create with Lux!

## Course Content

We will cover the following topics in this course:

- What is a Blockchain?
- Deep Dive into Payments
- Cryptography: Signature schemes
- Consensus Mechanisms
- Sybil Defense Mechanisms
- Smart contracts
- Tokenomics
- Virtual Machines

## Prerequisites

Anyone can take this course!

## Learning Outcomes

By the end of this course, you will have a good understanding of the basic concepts of blockchain technology.

You can evaluate your own understanding of the material through quizzes and claim a certificate for successful completion at the end.



# Decentralization (/academy/blockchain/blockchain-fundamentals/xx-decentralization)

---
title: Decentralization
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---


## Moving from a centralized Entity to a Collective of Validators

Blockchain systems achieve decentralization through the use of a network of validators, sometimes referred to as nodes, miners, or stakers, depending on the underlying consensus mechanism. Validators are responsible for verifying and securing transactions, maintaining the integrity of the blockchain, and ensuring that the system remains decentralized and trustless. Decentralization is achieved by distributing the responsibility of maintaining the network across numerous independent participants.

Decentralization in blockchain is achieved through a network of validators. These are independent entities that run the blockchain software, perform computations, and ensure the integrity of the blockchain. Here’s how it works:

Computation Execution: Each validator independently performs the same computation. For example, let's consider a simple computation: 5 + 3.
Consensus Process: After performing the computation, validators share their results with each other. They then use a process called consensus to agree on the correct result. You can think of it as a election, where all validators vote on the correct answer.
The consensus process ensures that all validators reach an agreement on the correct result, given that the majority is honest. This agreement is crucial for maintaining the integrity and security of the blockchain. If a validator tries to cheat or provide an incorrect result, the other validators will detect the discrepancy, and the cheating validator will be penalized.

# Tokens (/academy/blockchain/blockchain-fundamentals/xx-tokens)

---
title: Tokens
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: Notebook
---

Tokens are a concept that existed in societies for a long time. 

Tokens can be used to represent value. The most common valuable tokens we use every day are fiat currencies, like the US dollar. But there are also other kinds of tokens, such as points or miles in loyalty programs. Today we can also tokenize other assets, such as property titles.

## Fungible Tokens

Fungibility means that different tokens can be considered of equal value. Let's take for example two one dollar bills. Most people will not care if they get one or the other. They both offer the same utility. 

## Non-Fungible Tokens

Non-fungible tokens are not considered equal. The most prominent use cases are Art-NFTs. While the tokens may follow a standard of how they can be transfered, they may not be interchangeable. Two pieces of art may have very different values.

# Course Completion Certificate (/academy/blockchain/solidity-foundry/certificate)

---
title: Course Completion Certificate
updated: 2025-11-05
authors: [katherineavalabs]
icon: BadgeCheck 
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="solidity-foundry"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the course (/academy/blockchain/solidity-foundry)

---
title: Welcome to the course
description: Learn the basics about programming Smart Contracts in Solidity for an EVM Blockchain
updated: 2024-05-31
authors: [Andrea Vargas]
icon: Smile
---

In this course, you will learn how to build Solidity dApps on Lux.

## Why Take This Course?

A significant innovation in blockchain is the development of multi-chain systems, like Lux, which provide a significant improvement in scalability, interoperability, and flexibility. While a blockchain on Lux can be run with any VM, the most prominent choice currently is the Ethereum Virtual Machine (EVM). Users can deploy their own logic in the form of smart contracts to the EVM. 

These smart contracts can be written in Solidity. Learning Solidity can enable you to leverage the features of blockchain for your dApp.

## Course Content

### Smart Contracts 
In the first section, we will look at what smart contracts are, their basic structure and how they work. 

### Hello World Part I
In this section we will look at the primitive types (strings, integers, bool, ...) and function as well as the Solidity file structure. 

### Hello World Part II
We will look at control flows (if & else), data structures and constructors. Furthermore, we learn about inheritance from other contracts and modifiers and events.

### Contract Standardization
You will learn how contracts can be standardized and how inheritance and interfaces can help us to do so.

## Prerequisites

### Blockchain / Web3
This course is meant for people with a some experience when it comes to web3. You should be familiar with these concepts:
- Wallet: What they are and how to create one
- dApp: What a decentralized application is and how to interact with one

If any of this is unclear, we strongly recommend taking the Blockchain and Lux Fundamentals courses first, that give a soft introduction into these topics from a user stand point.

### Software Development
You will need a general understanding of Software Development. Therefore, we recommend:
- Programming: Familiarity with most basic concepts of programming, such as variables, control flows (if, else) and loops. 
- IDE: It will help if you're generally familiar with the concept of an integrated developer environment.

## Learning Outcomes

By the end of this course, students will:

- Interact and Deploy contracts using Foundry
- Get familiar with token standards
- Understand important concepts such as inheritance, modifiers, and events.
- Apply their knowledge by building their own smart contracts.


# Course Completion Certificate (/academy/entrepreneur/foundations-web3-venture/certificate)

---
title: Course Completion Certificate
updated: 2025-09-05
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="foundations-web3-venture"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!


# Entrepreneur Academy (/academy/entrepreneur/foundations-web3-venture)

---
title: Entrepreneur Academy
description: Building a Successful Web3 Startup
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Smile
---
<video 
  style={{ width: '100%', maxWidth: '100%', height: 'auto', borderRadius: '8px', marginBottom: '2rem' }}
  autoPlay 
  muted 
  loop 
  playsInline
>
  <source src="/common-images/academy/entrepreneur/entrepreneur-acadamy.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

## Level 1: Foundations of a Web3 Venture (Module 1 - 3)

These three modules are designed to give you a strong foundation for building and scaling your startup with confidence. You’ll begin by setting up your company on solid ground, mastering the essential legal, financial, compliance, and security principles that safeguard your business. From there, you’ll learn to shape and refine your vision through the Business Model Canvas, ensuring your strategy is both sustainable and customer-focused. Finally, you’ll dive deep into understanding the people who matter most—your stakeholders and users—by identifying their needs, creating personas, and translating insights into impactful solutions. Together, these modules equip you with the practical tools to launch, grow, and sustain a successful venture.


# Course Completion Certificate (/academy/blockchain/x402-payment-infrastructure/get-certificate)

---
title: Course Completion Certificate
updated: 2025-11-03
authors: [Federico Nardelli]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

Congratulations! You've completed the x402 Payment Infrastructure course. Let's verify your progress and get your certificate.

<CertificatePage courseId="x402-payment-infrastructure"/>

Thank you for taking this course! You now have the knowledge to build instant, permissionless payment infrastructure on Lux using the x402 protocol. We hope you'll use what you've learned to create innovative payment-enabled applications and contribute to the future of machine-to-machine commerce.


# Welcome to the Course (/academy/blockchain/x402-payment-infrastructure)

---
title: Welcome to the Course
description: Learn about the x402 protocol for instant, permissionless HTTP-native payments on Lux.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Coins
---

## Why Take This Course?

The x402 protocol is revolutionizing how payments work on the internet by activating HTTP 402 "Payment Required" status code for instant, permissionless transactions. Built on blockchain technology, x402 enables seamless machine-to-machine payments, making it perfect for AI agents, micropayments, and API monetization.

Traditional payment systems are slow, expensive, and require accounts, KYC, and complex integrations. x402 eliminates these friction points with 2-second settlement times, zero protocol fees, and no account requirements. Payments are gasless for end users—facilitators sponsor the minimal blockchain gas fees (~\$0.001 on Lux with current network conditions). For developers building on Lux, x402 leverages the network's low fees and fast finality to create an ideal environment for high-frequency micropayments.

## Course Content

- [Introduction to x402](/academy/blockchain/x402-payment-infrastructure/02-introduction/01-what-is-x402)
- [Technical Architecture](/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/01-payment-flow)
- [x402 on Lux](/academy/blockchain/x402-payment-infrastructure/04-x402-on-lux/01-why-lux)
- [Hands-On Implementation](/academy/blockchain/x402-payment-infrastructure/05-hands-on-implementation/01-environment-setup)

## Prerequisites

Before taking this course, you should have:

- **Blockchain Fundamentals:** Basic understanding of blockchain technology and how transactions work.
- **Lux Fundamentals:** Familiarity with the Lux network, particularly the LUExchange-Chain.
- **HTTP/APIs:** Understanding of HTTP protocols, status codes, and API development.
- **Programming:** Basic knowledge of JavaScript/TypeScript or another programming language.
- **Smart Contracts (Optional):** Helpful but not required for understanding payment verification.

## Learning Outcomes

By the end of this course, you will:

- Understand the x402 protocol and how it activates HTTP 402 for internet-native payments.
- Learn the complete payment flow from request to settlement, including facilitator roles.
- Discover why Lux is ideal for x402 implementations with its low fees and fast finality.
- Explore different x402 facilitator implementations available on Lux (Thirdweb, PayAI, Ultravioleta DAO, x402-rs).
- Implement x402 middleware in your own applications and configure endpoint pricing.
- Build use cases for AI agent payments, micropayments, and API monetization.
- Master security best practices and scaling considerations for production deployments.


# Course Completion Certificate (/academy/entrepreneur/fundraising-finance/certificate)

---
title: Course Completion Certificate
updated: 2025-09-05
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="fundraising-finance"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!


# Welcome to the Course (/academy/entrepreneur/fundraising-finance)

---
title: Welcome to the Course
description: Building a Successful Web3 Startup — Navigating Lux Foundation Grants
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Smile
---

<video 
  style={{ width: '100%', maxWidth: '100%', height: 'auto', borderRadius: '8px', marginBottom: '2rem' }}
  autoPlay 
  muted 
  loop 
  playsInline
>
  <source src="/common-images/academy/entrepreneur/entrepreneur-acadamy.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

## Level 4: Fundraising and Finance Pro (Module 9-11)

These modules focus on preparing you to secure the resources and relationships that fuel startup growth. You’ll start by exploring best practices for engaging with VCs and designing equity incentive plans that both attract top talent and align stakeholder interests. From there, you’ll learn how to identify, apply for, and secure grants that provide vital funding to support your mission and impact. Finally, you’ll master the art of fundraising through powerful pitch decks, compelling storytelling, and proven presentation techniques that set you up for successful campaigns. Together, these modules equip you with the skills and strategies to confidently navigate the fundraising landscape and build lasting investor relationships.

# Course Completion Certificate (/academy/entrepreneur/go-to-market/certificate)

---
title: Course Completion Certificate
updated: 2025-09-05
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="go-to-market"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!


# Welcome to Go-to-Market Strategies (/academy/entrepreneur/go-to-market)

---
title: Welcome to Go-to-Market Strategies
description: Master go-to-market strategies, sales, and pricing for your Web3 startup
updated: 2025-01-31
authors: [nicolasarnedo]
icon: Smile
---

<video 
  style={{ width: '100%', maxWidth: '100%', height: 'auto', borderRadius: '8px', marginBottom: '2rem' }}
  autoPlay 
  muted 
  loop 
  playsInline
>
  <source src="/common-images/academy/entrepreneur/entrepreneur-acadamy.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

## Level 2: Go-To-Market Strategist (Module 4 - 6)

These modules focus on turning opportunities into tangible growth by sharpening your sales and go-to-market skills. You’ll start by learning how to generate quality leads and spot the signals that indicate real potential, ensuring your efforts are targeted where they matter most. Next, you’ll master sales and messaging techniques to craft value propositions that resonate, connect authentically with your audience, and convert leads into lasting customer relationships. Finally, you’ll develop pricing strategies that not only reflect the true value of your product but also drive sustainable growth and align with your market. Together, these modules equip you to build a sales engine that accelerates your startup’s success.

# Course Completion Certificate (/academy/entrepreneur/web3-community-architect/certificate)

---
title: Course Completion Certificate
updated: 2025-09-05
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="web3-community-architect"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!


# Welcome to Web3 Community Architecture (/academy/entrepreneur/web3-community-architect)

---
title: Welcome to Web3 Community Architecture
description: Master the art of building and nurturing thriving Web3 communities that drive adoption and growth
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Smile
---

<video 
  style={{ width: '100%', maxWidth: '100%', height: 'auto', borderRadius: '8px', marginBottom: '2rem' }}
  autoPlay 
  muted 
  loop 
  playsInline
>
  <source src="/common-images/academy/entrepreneur/entrepreneur-acadamy.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

## Level 3: Web3 Community Architect (Module 7 and 8)

These modules are designed to help you amplify your startup’s reach, build lasting relationships, and explore innovative growth models. You’ll begin by discovering how to cultivate and leverage engaged communities that fuel loyalty, advocacy, and long-term impact. Next, you’ll learn to harness the power of social media and events strategically—strengthening your brand, deepening audience engagement, and creating momentum for growth. Finally, you’ll dive into the principles of token design, exploring economic models and distribution strategies that enable fair, effective, and sustainable ecosystems. Together, these modules equip you with the tools to grow your startup’s presence, influence, and value.

# Features (/academy/avalanche-l1/avacloudapis/02-overview/01-about)

---
title: Features
description: Learn about the features of the AvaCloud API.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

## What is the Data API?

The Data API provides web3 application developers with multi-chain data related to Lux’s primary network, Lux L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

### Data API Features
- **Extensive L1 Support**: Gain access to data from over 100+ L1s across both mainnet and testnet. If an L1 is listed on the [Lux Explorer](https://subnets.lux.network/stats/), you can query its data using the Data API.
- **Transactions and UTXOs**: Easily retrieve details related to transactions, UTXOs, and token transfers from Lux EVMs, Ethereum, and Lux’s Primary Network (Platform-Chain, Exchange-Chain and LUExchange-Chain).
- **Blocks**: Retrieve latest blocks and block details
- **Balances**: Fetch balances of native, ERC-20, ERC-721, and ERC-1155 tokens along with relevant metadata.
- **Tokens**: Augment your user experience with asset details.
- **Staking**: Get staking related data for active and historical validations.

## What is the Metrics API?
The Metrics API equips web3 developers with a robust suite of tools to access and analyze on-chain activity across Lux’s primary network, Lux L1s, and other supported EVM chains. This API delivers comprehensive metrics and analytics, enabling you to seamlessly integrate historical data on transactions, gas consumption, throughput, staking, and more into your applications.

The Metrics API, along with the Data API are the driving force behind every graph you see on the [Lux Explorer](https://subnets.lux.network/stats/). From transaction trends to staking insights, the visualizations and data presented are all powered by these APIs, offering real-time and historical insights that are essential for building sophisticated, data-driven blockchain products.

### Metrics API Features
- **Chain Throughput**: Retrieve detailed metrics on gas consumption, Transactions Per Second (TPS), and gas prices, including rolling windows of data for granular analysis.
- **Cumulative Metrics**: Access cumulative data on addresses, contracts, deployers, and transaction counts, providing insights into network growth over time.
- **Staking Information**: Obtain staking-related data, including the number of validators and delegators, along with their respective weights, across different L1s.
- **Blockchains and L1s**: Get information about supported blockchains, including EVM Chain IDs, blockchain IDs, and L1s associations, facilitating multi-chain analytics.
- **Composite Queries**: Perform advanced queries by combining different metric types and conditions, enabling detailed and customizable data retrieval.

## What is the AvaCloudSDK?

The [AvaCloud SDK](https://developers.avacloud.io/avacloud-sdk/getting-started) provides web3 application developers with multi-chain data related to Lux’s primary network, Lux L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

The SDK is currently available in TypeScript, with more languages coming soon. If you are interested in a language that is not listed, please reach out to us in the [`#dev-tools`](https://discord.com/login?redirect_to=%2Flogin%3Fredirect_to%3D%252Fchannels%252F578992315641626624%252F1280920394236297257) channel in the [Lux Discord](https://discord.com/invite/lux).


# APIs vs RPCs (/academy/avalanche-l1/avacloudapis/02-overview/02-apis-vs-rpc)

---
title: APIs vs RPCs
description: Learn how the AvaCloud Data API differs from RPC calls
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

Blockchain RPCs and APIs both facilitate interactions with a network, but they differ significantly in how they operate.

### RPCs
**Blockchain RPCs** allow you to communicate directly with a blockchain node, performing tasks like querying data or submitting transactions. These are low-level, synchronous calls, requiring a deep understanding of the blockchain's structure and specific commands.

To get a more comprehensive understanding of Ethereum's JSON-RPC API, you can refer to the [official Ethereum documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/).

### APIs
**Blockchain APIs**, like the AvaCloud Data API, abstract away much of the complexity. They offer higher-level, user-friendly endpoints that streamline interactions, making it easier to build and manage blockchain applications without needing in-depth knowledge of the underlying blockchain protocols.

To get a more comprehensive understanding of the AvaCloud Data API, you can refer to the [official AvaCloud Data API documentation](https://developers.avacloud.io/data-api/overview).

### Example Use Case
For example, querying a user's ERC-20 portfolio using an RPC involves a series of complex calls to retrieve and parse raw blockchain data. 
Using just RPCs, you would need to:

1. Query every block on the network for transaction logs.
2. Parse each transaction log to identify ERC-20 token transfers.
3. Extract the ERC-20 token contract address.
4. For each ERC-20 token contract, query the user's address to get the balance.
5. Parse and aggregate the data to present the user's portfolio.

While it may seem simple in theory, this process can be time-consuming and error-prone, especially when dealing with multiple blockchains.

With the AvaCloud Data API, you could simply use a dedicated endpoint such as: 
```bash
curl --request GET \
  --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/balances:listErc20 \
  --header 'x-glacier-api-key: <api-key>'
```

to get a neatly formatted response with the user's ERC-20 portfolio, significantly reducing development time and complexity.

```json
{
  "nextPageToken": "<string>",
  "erc20TokenBalances": [
    {
      "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "name": "Wrapped LUX",
      "symbol": "WLUX",
      "decimals": 18,
      "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/lux-lux-logo.svg",
      "ercType": "ERC-20",
      "price": {
        "currencyCode": "usd",
        "value": "42.42"
      },
      "chainId": "43114",
      "balance": "2000000000000000000",
      "balanceValue": {
        "currencyCode": "usd",
        "value": "42.42"
      }
    }
  ]
}
```

# Data API (/academy/avalanche-l1/avacloudapis/02-overview/03-dataapi-endpoints)

---
title: Data API
description: Learn about AvaCloud Data API.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

The AvaCloud Data API provides a comprehensive set of endpoints to interact with Lux networks. These endpoints allow you to query information about blocks, transactions, assets, and more.

Below are some of the key endpoints available in the Data API.
A more comprehensive list of Data API endpoints can be found [here](https://developers.avacloud.io/data-api/overview).

## Data API Reference
### EVM Endpoints

<Accordions>
<Accordion title="Chains">
- [List All Chains](https://developers.avacloud.io/data-api/evm-chains/list-chains)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains \
     --header 'accept: application/json'
```
- [Get Chain Information](https://developers.avacloud.io/data-api/evm-chains/get-chain-information)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId} \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Blocks">
- [List Latest Blocks](https://developers.avacloud.io/data-api/evm-chains/list-latest-blocks)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/blocks \
     --header 'accept: application/json'
```
- [Get Block Information](https://developers.avacloud.io/data-api/evm-chains/getblock)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/blocks/{blockId} \
     --header 'accept: application/json'
``` 

</Accordion>

<Accordion title="Transactions">
- [Get Deployment Transaction](https://developers.avacloud.io/data-api/evm-transactions/get-deployment-transaction)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/contracts/{address}/transactions:getDeployment \
     --header 'accept: application/json'
```
- [List Deployed Contracts](https://developers.avacloud.io/data-api/evm-transactions/list-deployed-contracts)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/contracts/{address}/deployments \
     --header 'accept: application/json'
```
- [List ERC Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-transfers)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/tokens/{address}/transfers \
     --header 'accept: application/json'
```

- [List Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/transactions \
     --header 'accept: application/json'
```

- [List Native Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-native-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/transactions:listNative \
     --header 'accept: application/json'
```

- [List ERC-20 Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-20-transfers)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/transactions:listErc20 \
     --header 'accept: application/json'
```

- [List ERC-721 Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-721-transfers)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/transactions:listErc721 \
     --header 'accept: application/json'
```

- [List ERC-1155 Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-1155-transfers)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/transactions:listErc1155 \
     --header 'accept: application/json'
```
- [List Internal Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-internal-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/transactions:listInternals \
     --header 'accept: application/json'
```

- [Get Transaction](https://developers.avacloud.io/data-api/evm-transactions/get-transaction)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/transactions/{txHash} \
     --header 'accept: application/json'
```

- [List Transactions For a Block](https://developers.avacloud.io/data-api/evm-transactions/list-transactions-for-a-block)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/blocks/{blockId}/transactions \
     --header 'accept: application/json'
```

- [List Latest Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-latest-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/transactions \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Balances">
- [Get Native Token Balance](https://developers.avacloud.io/data-api/evm-balances/get-native-token-balance)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/balances:getNative \
     --header 'accept: application/json'
```
- [List ERC-20 Balances](https://developers.avacloud.io/data-api/evm-balances/list-erc-20-balances)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/balances:listErc20 \
     --header 'accept: application/json'
```
- [List ERC-721 Balances](https://developers.avacloud.io/data-api/evm-balances/list-erc-721-balances)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/balances:listErc721 \
     --header 'accept: application/json'
```
- [List ERC-1155 Balances](https://developers.avacloud.io/data-api/evm-balances/list-erc-1155-balances)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/balances:listErc1155 \
     --header 'accept: application/json'
```
- [List Collectible (ERC-721 and ERC-1155) Balances](https://developers.avacloud.io/data-api/evm-balances/list-collectible-erc-721erc-1155-balances)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address}/balances:listCollectibles \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Contracts">
- [Get Contract Metadata](https://developers.avacloud.io/data-api/evm-contracts/get-contract-metadata)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/addresses/{address} \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="NFTs">
- [Reindex NFT Metadata](https://developers.avacloud.io/data-api/nfts/reindex-nft-metadata)
```bash
curl --request POST \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/nfts/collections/{address}/tokens/tokenId:reindex \
     --header 'accept: application/json'
```
- [List Tokens](https://developers.avacloud.io/data-api/nfts/list-tokens)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/nfts/collections/{address}/tokens \
     --header 'accept: application/json'
```
- [Get Token Details](https://developers.avacloud.io/data-api/nfts/get-token-details)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/chains/{chainId}/nfts/collections/{address}/tokens/tokenId \
     --header 'accept: application/json'
```

</Accordion>

</Accordions>



### Lux Primary Network Endpoints

<Accordions>
<Accordion title="Network, Chains, and L1s">
- [Get Chain Interactions for Addresses](https://developers.avacloud.io/data-api/primary-network/get-chain-interactions-for-addresses)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/{network}/addresses:listChainIds \
     --header 'accept: application/json'
```

- [Get Network Details](https://developers.avacloud.io/data-api/primary-network/get-network-details)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/{network} \
     --header 'accept: application/json'
```
- [List Blockchains](https://developers.avacloud.io/data-api/primary-network/list-blockchains)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/{network}/blockchains \
     --header 'accept: application/json'
```

- [List Subnets](https://developers.avacloud.io/data-api/primary-network/list-subnets)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/subnets \
     --header 'accept: application/json'
```
- [Get Subnet Details by ID](https://developers.avacloud.io/data-api/primary-network/get-subnet-details-by-id)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/subnets/{subnetId} \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Validators and Delegators">
- [List Validators](https://developers.avacloud.io/data-api/primary-network/list-validators)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/validators \
     --header 'accept: application/json'
```
- [Get Single Validator Details](https://developers.avacloud.io/data-api/primary-network/get-single-validator-details)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/validators/{nodeId} \
     --header 'accept: application/json'
```
- [List Delegators](https://developers.avacloud.io/data-api/primary-network/list-delegators)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/delegators \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Blocks">
- [Get Block](https://developers.avacloud.io/data-api/primary-network-blocks/get-block)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/blocks/{blockId} \
     --header 'accept: application/json'
```
- [List Blocks Proposed by Node](https://developers.avacloud.io/data-api/primary-network-blocks/list-blocks-proposed-by-node)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/nodes/{nodeId}/blocks \
     --header 'accept: application/json'
```

- [List Latest Blocks](https://developers.avacloud.io/data-api/primary-network-blocks/list-latest-blocks)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/blocks \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Vertices">
- [List Vertices](https://developers.avacloud.io/data-api/primary-network-vertices/list-vertices)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/vertices \
     --header 'accept: application/json'
```
- [Get Vertex](https://developers.avacloud.io/data-api/primary-network-vertices/get-vertex)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/vertices/vertexHash \
     --header 'accept: application/json'
```
- [List Vertices by Height](https://developers.avacloud.io/data-api/primary-network-vertices/list-vertices-by-height)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/vertices:listByHeight \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Transactions">
- [Get Transaction](https://developers.avacloud.io/data-api/primary-network-transactions/get-transaction)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/{network}/blockchains/{blockchainId}/transactions/{txHash} \
     --header 'accept: application/json'
```
- [List Latest Transactions](https://developers.avacloud.io/data-api/primary-network-transactions/list-latest-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/{network}/blockchains/{blockchainId}/transactions \
     --header 'accept: application/json'
```
- [List Staking Transactions](https://developers.avacloud.io/data-api/primary-network-transactions/list-staking-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/transactions:listStaking \
     --header 'accept: application/json'
```

- [List Asset Transactions](https://developers.avacloud.io/data-api/primary-network-transactions/list-asset-transactions)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/assets/{assetId}/transactions \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Balances and UTXOs">
- [List UTXOs](https://developers.avacloud.io/data-api/primary-network-utxos/list-utxos)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/utxos \
     --header 'accept: application/json'
```
- [Get Balances](https://developers.avacloud.io/data-api/primary-network-balances/get-balances)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/balances \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Rewards">
- [List Pending Rewards](https://developers.avacloud.io/data-api/primary-network-rewards/list-pending-rewards)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/rewards:listPending \
     --header 'accept: application/json'
```
- [List Historical Rewards](https://developers.avacloud.io/data-api/primary-network-rewards/list-historical-rewards)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/rewards \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Assets">
- [Get Asset Details](https://developers.avacloud.io/data-api/primary-network/get-asset-details)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/assets/{assetId} \
     --header 'accept: application/json'
```
</Accordion>
</Accordions>


# Webhooks API (/academy/avalanche-l1/avacloudapis/02-overview/04-webhooks)

---
title: Webhooks API
description: Learn about AvaCloud Webhooks API.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
## What is a Webhook?

A webhook is a communication mechanism to provide applications with real-time information. It delivers data to other applications as it happens, meaning you get data immediately, unlike typical APIs where you would need to poll for data to get it in "real-time". This makes webhooks much more efficient for both providers and consumers. Webhooks work by registering a URL to send notifications once certain events occur.
You can create receiver endpoints in your server in any programming language and those will have an associated URL. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event.

## What are AvaCloud Webhooks?

With the Webhooks API, you can monitor real-time events on the Lux LUExchange-Chain and L1s. For example, you can monitor smart contract events, track NFT transfers, and observe wallet-to-wallet transactions.

### Key Features:
- **Real-time notifications:** Receive immediate updates on specified on-chain activities without polling.
- **Customizable:** Specify the desired event type to listen for, customizing notifications according to individual requirements.
- **Secure:** Employ shared secrets and signature-based verification to guarantee that notifications originate from a trusted source.
- **Broad Coverage:** Support for C-chain mainnet, testnet, and L1s within the Lux ecosystem, ensuring wide-ranging monitoring capabilities.

### Use Cases:
- **NFT Marketplace Transactions:** Get alerts for NFT minting, transfers, auctions, bids, sales, and other interactions within NFT marketplaces.
- **Wallet Notifications:** Receive alerts when an address performs actions such as sending, receiving, swapping, or burning assets.
- **DeFi Activities:** Receive notifications for various DeFi activities such as liquidity provisioning, yield farming, borrowing, lending, and liquidations.

## Webhooks API Reference

<Accordions>

<Accordion title="Create a webhook">
[Create a new webhook](https://developers.avacloud.io/webhooks-api/webhooks/create-a-webhook)
```bash
curl --request POST \
     --url https://glacier-api.lux.network/v1/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "address_activity"
}
```
</Accordion>

<Accordion title="List webhooks">
[Lists webhooks for the user.](https://developers.avacloud.io/webhooks-api/webhooks/list-webhooks)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/webhooks \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Get a webhook by ID">
[Retrieves a webhook by ID.](https://developers.avacloud.io/webhooks-api/webhooks/get-a-webhook-by-id)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/webhooks/id \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Deactivate a webhook">
[Deactivates a webhook by ID.](https://developers.avacloud.io/webhooks-api/webhooks/deactivate-a-webhook)
```bash
curl --request DELETE \
     --url https://glacier-api.lux.network/v1/webhooks/id \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Update a webhook">
[Updates an existing webhook.](https://developers.avacloud.io/webhooks-api/webhooks/update-a-webhook)
```bash
curl --request PATCH \
     --url https://glacier-api.lux.network/v1/webhooks/id \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```
</Accordion>

<Accordion title="Generate a shared secret">
[Generates a new shared secret.](https://developers.avacloud.io/webhooks-api/webhooks/generate-a-shared-secret)
```bash
curl --request POST \
     --url https://glacier-api.lux.network/v1/webhooks:generateOrRotateSharedSecret \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Get a shared secret">
[Get a previously generated shared secret.](https://developers.avacloud.io/webhooks-api/webhooks/get-a-shared-secret)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/webhooks:getSharedSecret \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Add addresses to webhook">
[Add addresses to webhook.](https://developers.avacloud.io/webhooks-api/webhooks/add-addresses-to-webhook)
```bash
curl --request PATCH \
     --url https://glacier-api.lux.network/v1/webhooks/id/addresses \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```
</Accordion>

<Accordion title="Remove addresses to webhook">
[Remove addresses from webhook.](https://developers.avacloud.io/webhooks-api/webhooks/remove-addresses-from-webhook)
```bash
curl --request DELETE \
     --url https://glacier-api.lux.network/v1/webhooks/id/addresses \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```

</Accordion>

<Accordion title="List addresses by webhook">
[List adresses by webhook.](https://developers.avacloud.io/webhooks-api/webhooks/list-adresses-by-webhook)
```bash
curl --request GET \
     --url https://glacier-api.lux.network/v1/webhooks/id/addresses \
     --header 'accept: application/json'
```

</Accordion>


</Accordions>

# Create API Key (/academy/avalanche-l1/avacloudapis/03-environment-setup/01-avacloud-account)

---
title: Create API Key
description: Get an API key for AvaCloud
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';


## Get an AvaCloud API Key

In order to utilize your accounts rate limits, you will need to make API requests with an API key. You can generate API Keys from the [AvaCloud portal](https://app.avacloud.io/glacier-api/).

<Steps>

<Step>
Create an account on [AvaCloud](https://avacloud.io).
</Step>

<Step>
Click on the `Web3 Data API` [tab](https://app.avacloud.io/glacier-api/).
</Step>

<Step>
Click `+ Add API Key` and create a new name for your API key.
</Step>

<Step>
**Save your API key** in a secure location. We will need it in the next step.
</Step>

</Steps>

Once you've created and retrieved the key, you will be able to make authenticated queries by passing in your API key in the `x-glacier-api-key` header of your HTTP request.

An example curl request to the Data API:

```bash
curl -H "Content-Type: Application/json" -H "x-glacier-api-key: <your_api_key>" \
  "https://glacier-api.lux.network/v1/chains"
```

# Setup AvaCloudSDK Starter Kit (/academy/avalanche-l1/avacloudapis/03-environment-setup/02-setup-starter-kit)

---
title: Setup AvaCloudSDK Starter Kit
description: Set up the AvaCloudSDK Starter Kit in a GitHub Codespace
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
import Link from 'next/link';
import { cn } from '@/utils/cn';
import { buttonVariants } from '@/components/ui/button.tsx'
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this course we will run the AvaCloudSDK Starter Kit in a Github Codepsace. This is the quickest way to get started.

The `AvaCloudSDK Starter Kit` contains everything we need to get started quickly with the AvaCloud API. 

<Steps>
<Step>

### Open the AvaCloudSDK Starter Kit Github Repository:
**Make sure you are on the `follow-along` branch!**

<Link
    href="https://github.com/luxfi/glacier-starter-kit/tree/follow-along"
    className={cn(
    buttonVariants({ variant: 'default', className: 'mt-4' }),
    )}
    target='_blank'
>Open AvaCloudSDK Starter Kit</Link>

</Step>
<Step>

### Create a Codespace
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=follow-along&repo=851861669&machine=standardLinux32gb)
The Codespace will open in a new tab. Wait a few minutes until it's fully built.

</Step>
<Step>

### Verify everything is working correctly

Open the terminal with `` Ctrl + ` `` or by opening it through the menu.

</Step>
<Step>

### Set the `AVACLOUD_API_KEY` environment variable
Create a `.env` file in the root of the project and add your API key from [the previous step](/academy/avacloudapis/03-environment-setup/01-avacloud-account):

```bash
AVACLOUD_API_KEY=ac_rGIKESl9_9DWuLfJJQLSV5nlzbKR7eHxym6XW3XEQJeNBDRxI...
```

</Step>
<Step>
### Start the NextJS app
Now we can run the NextJS app in hot reload mode:
    
```bash
yarn dev
```

It should preview within the Codespace.

</Step>
<Step>



### Optional: Open Codespace locally in Visual Studio Code

You can switch any time from the browser IDE to Visual Studio Code.

The first time you switch, you will be asked to install the [Codespaces extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) and connect VS Code to you GitHub account, if it is not already connceted.

</Step>
</Steps>

# Time to Build! (/academy/avalanche-l1/avacloudapis/03-environment-setup/03-what-we-build)

---
title: Time to Build!
description: Learn about what we will build in this course
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

### Finished Setup
Once your environment is set up, we can start building some applications using the AvaCloud API and the AvaCloudSDK.

### What We Will Build
Here is a brief overview of what we will be building in this course:

- ERC-20 Balance App
- Wallet Portfolio App
- Block Explorer App

Each of these applications will utilize the Data API to get data from the Lux network. We will fetch data such as ERC-20 token balances, NFT balances, recent transactions from an address, block information and much more.

# Overview (/academy/avalanche-l1/avacloudapis/04-erc20-token-balance-app/01-overview)

---
title: Overview
description: Use the AvaCloud Data API to create a simple web app that displays a user's ERC-20 token balances.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---

In this section we will use the Data API to create a simple web app that displays a user's ERC-20 token portfolio. This app will allow users to input their Lux LUExchange-Chain address and view a list of their ERC-20 token balances.

We will use two endpoints from the Data API to accomplish this:

- [`data.evm.blocks.getLatestBlocks`](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks)
- [`data.evm.balances.listErc20Balances`](https://developers.avacloud.io/data-api/evm-balances/list-erc-20-balances)


# Understanding the Code (/academy/avalanche-l1/avacloudapis/04-erc20-token-balance-app/02-understanding-code)

---
title: Understanding the Code
description: Before we start coding, let's take a look at the code we will be working with.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

There will be two main files that we will be working with in this section.

<Steps>
<Step>

### `Page.tsx`
This is the code that will be rendered on the client side, as distinguished by `"use client";` at the top of the file. It contains the React components that will be displayed to the user and is responsible for making the API calls to our backend, which in turn calls the Data API.

It is important to understand that when you `"use client"` in a NextJS project, it will be rendered on the client side. This means that the code will be executed in the user's browser and not on the server. This is important to keep in mind when working with sensitive data or when you want to keep your API keys secure.

Besides this, we have two main functions that we will be working with in this file:

<Steps>
<Step>

```tsx title="src/app/balance-app/page.tsx"
const handleSetAddress = async () => {
  //
  // TODO: Implement handleSetAddress
  //
};
```
`handleSetAddress` is a simple function that will be called when the user clicks the "Set Address" button. It will ensure the address is valid then set the inputted address to the React State. Next, we call our next function `fetchERC20Balances` to get the user's balance.

</Step>
<Step>

```tsx title="src/app/balance-app/page.tsx"
const fetchERC20Balances = async (address: string) => {
  //
  // TODO: Implement fetchERC20Balances
  //
};
```

`fetchERC20Balances` is a function that will make a call to our backend to get the user's ERC-20 token balances. It will first get the current block height, then call the `listErc20Balances` method on our backend with the user's address and the block height. It will then return the balances as an array of `Erc20TokenBalance` objects.

</Step>
</Steps>

</Step>
<Step>

### `Route.ts`
This code will be executed on the server side, as distinguished by `"use server";` at the top of the file. It contains the code that will be executed on the server side and is responsible for making the API calls to the Data API.

There are a few key components to understand in this file:

<Steps>
<Step>
```tsx title="src/app/api/balance/route.ts"
import { AvaCloudSDK } from "@luxfi/avacloud-sdk";
const avaCloudSDK = new AvaCloudSDK({
  apiKey: process.env.AVACLOUD_API_KEY,
  chainId: "43114", // Lux Mainnet
  network: "mainnet",
});
```
Here we initialize the `AvaCloudSDK` with our AvaCloud API key and the chainId of `43114` for the Lux Mainnet. This will allow us to make calls to the Data API.
</Step>
<Step>

```tsx title="src/app/api/balance/route.ts"
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const method = searchParams.get('method')
  try {
    let result
    switch (method) {
      case 'getBlockHeight':
        result = await getBlockHeight()
        break
      case 'listErc20Balances':
        const address: string = searchParams.get('address')!
        const blockNumber: string = searchParams.get('blockNumber')!
        result = await listErc20Balances(address, blockNumber);
        break
      default:
        return NextResponse.json({ error: 'Invalid method' }, { status: 400 })
    }
    return NextResponse.json(result)
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}
```
Here we define the internal API methods for our backend. We have two methods that we will be working with in this section: `getBlockHeight` and `listErc20Balances`. We create both of these methods internally, then forward the request to the Data API. We then return the result to the client.
</Step>
<Step>
```tsx title="src/app/api/balance/route.ts"
async function getBlockHeight() {
   //
   // TODO: Implement getBlockHeight
   //
}
async function listErc20Balances(address: string, blockNumber: string) {
   //
   // TODO: Implement listErc20Balances
   //
}
```
In the next section, we will implement the `listErc20Balances` and `getBlockHeight` function to call the Data API through the AvaCloudSDK.
</Step>
</Steps>
</Step> 
</Steps> 

# Modifying the Code (/academy/avalanche-l1/avacloudapis/04-erc20-token-balance-app/03-modifying-code)

---
title: Modifying the Code
description: Lets modify the code to implement the Data API.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section we will modify the code to implement the Data API.

### Modify Backend `src/app/api/balance/route.ts`

<Steps>
<Step>
First we will implement the `getBlockHeight` function. The goal of this function is to fetch recent blocks from the Data API then to return the highest block in the first position.

<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks) to see how to fetch the latest blocks.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/balance/route.ts"
async function getBlockHeight() {
    const result = await avaCloudSDK.data.evm.blocks.getLatestBlocks({
        pageSize: 1,
      });
    return result.result.blocks[0].blockNumber
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `listErc20Balances` function. The goal of this function is to fetch the ERC-20 token balances for a given address at a specific block height.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-balances/list-erc-20-balances) to see how to fetch ERC-20 token balances.
Note the `Erc20TokenBalance` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/balance/route.ts"
async function listErc20Balances(address: string, blockNumber: string) {
    const result = await avaCloudSDK.data.evm.balances.listErc20Balances({
        blockNumber: blockNumber,
        pageSize: 10,
        address: address,
      });
    const balances: Erc20TokenBalance[] = [];
    for await (const page of result) {
        balances.push(...page.result.erc20TokenBalances);
    }
    return balances
}
```
</Accordion>
</Accordions>
</Step>
</Steps>
### Modify Frontend `src/app/balance-app/page.tsx`

<Steps>
<Step>
</Step>
<Step>
First we will implement the `fetchERC20Balances` function. The goal of this function is to make a call to our backend to get the user's ERC-20 token balances.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for the most recent block height, then our `listErc20Balances` API. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/balance-app/page.tsx"
const fetchERC20Balances = async (address: string) => {
    const blockResult = await fetch("api/balance?method=getBlockHeight");
    const blockNumber = await blockResult.json();
    const balanceResult = await fetch("api/balance?method=listErc20Balances&address=" + address + "&blockNumber=" + blockNumber);
    const balances = await balanceResult.json();
    return balances as Erc20TokenBalance[];
};
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `handleSetAddress` function. The goal of this function is to set the address in the state and fetch the ERC-20 token balances for that address using our `fetchERC20Balances` function.
<Accordions>
<Accordion title="Hint">
First make sure the address is valid, then update the state for `Address` and `Balances`
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/balance-app/page.tsx"
const handleSetAddress = async () => {
    const addressInput = document.getElementById("address") as HTMLInputElement;
    const address = addressInput.value;
    const addressPattern = /^0x[a-fA-F0-9]{40}$/;  

    if (addressInput && addressPattern.test(address)) {
      setAddress(address);
      setBalances(await fetchERC20Balances(address));
    }
};
```
</Accordion>
</Accordions>
</Step>


</Steps>


# Final Result (/academy/avalanche-l1/avacloudapis/04-erc20-token-balance-app/04-final)

---
title: Final Result
description: The final result of the ERC-20 token balance app.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

If we implemented the code correctly, we should have a working ERC-20 token balance app that displays the user's token balances.

After setting the address field, the app will display the user's ERC-20 token balances.

Notice how the app also displays images for each token. This is done by fetching the token metadata from `listErc20Balances` and displaying the token's logo.

# Overview (/academy/avalanche-l1/avacloudapis/06-block-explorer-app/01-overview)

---
title: Overview
description: Use the Data API to create a simple block explorer.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
In this section we will build a basic block explorer using the Data API.

We will use a couple additional endpoints from the Data API to accomplish this:

- [`data.evm.blocks.getBlockHeight`](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks)
- [`data.evm.transactions.listLatestTransactions`](https://developers.avacloud.io/data-api/evm-transactions/list-latest-transactions)

# Understanding the Code (/academy/avalanche-l1/avacloudapis/06-block-explorer-app/02-understanding-code)

---
title: Understanding the Code
description: Before we start coding, let's take a look at the code we will be working with.
updated: 2024-10-09
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

There will be two main files that we will be working with in this section.

<Steps>
<Step>

### `Page.tsx`
This is the code that will be rendered on the client side, as distinguished by `"use client";` at the top of the file. It contains the React components that will be displayed to the user and is responsible for making the API calls to our backend, which in turn calls the Data API.

It is important to understand that when you `"use client"` in a NextJS project, it will be rendered on the client side. This means that the code will be executed in the user's browser and not on the server. This is important to keep in mind when working with sensitive data or when you want to keep your API keys secure.

Besides this, we have three main functions that we will be working with in this file:

<Steps>
<Step>
```tsx title="src/app/basic-explorer/page.tsx"
const fetchRecentTransactions = async () => {
    //
    // TODO: Implement this!
    //
    return data as NativeTransaction[]
  }
```
`fetchRecentTransactions` is a function that will make a call to our backend to get the most recent transactions from the chain. It will call the `getRecentTransactions` method on our backend. It will then return the transactions as an array of `NativeTransaction` objects.

</Step>
<Step>
```tsx title="src/app/basic-explorer/page.tsx"
const fetchRecentBlocks = async () => {
    //
    // TODO: Implement this!
    //
    return data as EvmBlock[]
  }
```

`fetchRecentBlocks` is a function that will make a call to our backend to get the most recent blocks from the chain. It will call the `getRecentBlocks` method on our backend. It will then return the blocks as an array of `EvmBlock` objects.

</Step>
</Steps>

</Step>
<Step>

### `Route.ts`
This code will be executed on the server side, as distinguished by `"use server";` at the top of the file. It contains the code that will be executed on the server side and is responsible for making the API calls to the Data API.

There are a few key components to understand in this file:

<Steps>
<Step>
```tsx title="src/app/api/explorer/route.ts"
import { AvaCloudSDK } from "@luxfi/avacloud-sdk";
const avaCloudSDK = new AvaCloudSDK({
  apiKey: process.env.AVACLOUD_API_KEY,
  chainId: "43114", // Lux Mainnet
  network: "mainnet",
});
```
Here we initialize the `AvaCloudSDK` with our AvaCloud API key and the chainId of `43114` for the Lux Mainnet. This will allow us to make calls to the Data API.
</Step>
<Step>

```tsx title="src/app/api/explorer/route.ts"
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const method = searchParams.get('method')
  try {
    let result
    switch (method) {
      case 'getRecentTransactions':
        result = await getRecentTransactions()
        break
      case 'getRecentBlocks':
        result = await getRecentBlocks()
        break
      default:
        return NextResponse.json({ error: 'Invalid method' }, { status: 400 })
    }
    return NextResponse.json(result)
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}
```
Here we define the internal API methods for our backend. We have two methods that we will be working with in this section: `getRecentBlocks` and `getRecentTransactions`. We create all of these methods internally, then forward the request to the Data API. We then return the result to the client.
</Step>
<Step>
```tsx title="src/app/api/explorer/route.ts"
const getRecentBlocks = async () => {
   //
    // TODO: Implement this!
    //
}

const getRecentTransactions = async () => {
    //
    // TODO: Implement this!
    //
}
```
In the next section, we will implement these functions to call the Data API through the AvaCloudSDK.
</Step>
</Steps>
</Step> 
</Steps> 

# Modifying the Code (/academy/avalanche-l1/avacloudapis/06-block-explorer-app/03-modifying-code)

---
title: Modifying the Code
description: Lets modify the code to implement the Data API.
updated: 2024-10-09
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section we will modify the code to implement the Data API.

### Modify Backend `src/app/api/explorer/route.ts`

<Steps>
<Step>
First we will implement the `getRecentBlocks` function. The goal of this function is to fetch recent blocks from the Data API with all its information.

<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks) to see how to fetch the latest blocks.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/explorer/route.ts"
const getRecentBlocks = async () => {
    const result = await avaCloudSDK.data.evm.blocks.getLatestBlocks({
        pageSize: 1,
      });

    let count = 0;
    const blocks: EvmBlock[] = [];
    for await (const page of result) {
        if (count === 20) {
            break;
        }
        blocks.push(...page.result.blocks);
        count++;
    }
    return blocks
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `getRecentTransactions` function. The goal of this function is to fetch all native token transfers from the Data API.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-transactions/list-latest-transactions) to see how to fetch latest transactions.
Note the `NativeTransaction` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/explorer/route.ts"
const getRecentTransactions = async () => {
    const result = await avaCloudSDK.data.evm.transactions.listLatestTransactions({
        pageSize: 3,
    });

    let count = 0;
    const transactions: NativeTransaction[] = [];
    for await (const page of result) {
        if (count === 20) {
            break;
        }
        transactions.push(...page.result.transactions);
        count++;
    }
    return transactions;
}
```
</Accordion>
</Accordions>
</Step>
</Steps>
### Modify Frontend `src/app/basic-explorer/page.tsx`

<Steps>
<Step>
</Step>
<Step>
First we will implement the `fetchRecentTransactions` function. The goal of this function is to make a call to our backend to get recent transactions.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for our `getRecentTransactions` method. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-explorer/page.tsx"
  const fetchRecentTransactions = async () => {
    const response = await fetch(`/api/explorer?method=getRecentTransactions`)
    const data = await response.json()
    return data as NativeTransaction[]
  }
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `fetchRecentBlocks` function. The goal of this function is to make a call to our backend to get recent block information.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for our `getRecentBlocks` method. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-explorer/page.tsx"
const fetchRecentBlocks = async () => {
    const response = await fetch(`/api/explorer?method=getRecentBlocks`)
    const data = await response.json()
    return data as EvmBlock[]
  }
```
</Accordion>
</Accordions>
</Step>


</Steps>


# Overview (/academy/avalanche-l1/avacloudapis/05-wallet-portfolio-app/01-overview)

---
title: Overview
description: Use the Data API to create a simple web app that displays data and metrics on a connected wallet.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---

In this section we will expand on the ERC-20 Balance App with NFTs (ERC-721) and ERC-1155 tokens. We will also add a connect wallet button to allow users to connect their own wallet and view their own token balances.

Here is a preview of what we will build:



We will use a few additional endpoints from the Data API to accomplish this:

- [`data.evm.balances.listErc721Balances`](https://developers.avacloud.io/data-api/evm-balances/list-erc-721-balances)
- [`data.evm.balances.listErc1155Balances`](https://developers.avacloud.io/data-api/evm-balances/list-erc-1155-balances)
- [`data.evm.transactions.listTransactions`](https://developers.avacloud.io/data-api/evm-transactions/list-transactions)

# Understanding the Code (/academy/avalanche-l1/avacloudapis/05-wallet-portfolio-app/02-understanding-code)

---
title: Understanding the Code
description: Before we start coding, let's take a look at the code we will be working with.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

There will be two main files that we will be working with in this section.

<Steps>
<Step>

### `Page.tsx`
This is the code that will be rendered on the client side, as distinguished by `"use client";` at the top of the file. It contains the React components that will be displayed to the user and is responsible for making the API calls to our backend, which in turn calls the Data API.

It is important to understand that when you `"use client"` in a NextJS project, it will be rendered on the client side. This means that the code will be executed in the user's browser and not on the server. This is important to keep in mind when working with sensitive data or when you want to keep your API keys secure.

Besides this, we have three main functions that we will be working with in this file:

<Steps>
<Step>
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC721Balances = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return [] as Erc721TokenBalance[];
  }
```
`fetchERC721Balances` is a function that will make a call to our backend to get the user's ERC-721 token balances. It will call the `listErc721Balances` method on our backend with the user's address. It will then return the balances as an array of `Erc721TokenBalance` objects.

</Step>
<Step>
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC1155Balances = async (address: string) => {
     //
    // TODO: Implement this!
    //
    return [] as Erc1155TokenBalance[];
  }
```

`fetchERC1155Balances` is a function that will make a call to our backend to get the user's ERC-1155 token balances. It will call the `listErc1155Balances` method on our backend with the user's address. It will then return the balances as an array of `Erc1155TokenBalance` objects.

</Step>
<Step>
```tsx title="src/app/basic-wallet/page.tsx"
  const fetchRecentTransactions = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return {} as TransactionDetails;
  }
```
`fetchRecentTransactions` is a function that will make a call to our backend to get the user's recent transactions for all tokens. It will call the `listRecentTransactions` method on our backend with the user's address. It will then return the balances as an object of type `TransactionDetails`.

</Step>
</Steps>

</Step>
<Step>

### `Route.ts`
This code will be executed on the server side, as distinguished by `"use server";` at the top of the file. It contains the code that will be executed on the server side and is responsible for making the API calls to the Data API.

There are a few key components to understand in this file:

<Steps>
<Step>
```tsx title="src/app/api/wallet/route.ts"
import { AvaCloudSDK } from "@luxfi/avacloud-sdk";
const avaCloudSDK = new AvaCloudSDK({
  apiKey: process.env.AVACLOUD_API_KEY,
  chainId: "43114", // Lux Mainnet
  network: "mainnet",
});
```
Here we initialize the `AvaCloudSDK` with our AvaCloud API key and the chainId of `43114` for the Lux Mainnet. This will allow us to make calls to the Data API.
</Step>
<Step>

```tsx title="src/app/api/wallet/route.ts"
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const method = searchParams.get('method')
  let address
  try {
    let result
    switch (method) {
      case 'listERC721Balances':
        address = searchParams.get('address')!
        result = await listERC721Balances(address)
        break
      case 'listERC1155Balances':
        address = searchParams.get('address')!
        result = await listErc1155Balances(address)
        break
      case 'listRecentTransactions':
        address = searchParams.get('address')!
        result = await listRecentTransactions(address)
        break
      default:
        return NextResponse.json({ error: 'Invalid method' }, { status: 400 })
    }
    return NextResponse.json(result)
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}
```
Here we define the internal API methods for our backend. We have two methods that we will be working with in this section: `getBlockHeight`, `listERC721Balances`, `listErc1155Balances` and `listRecentTransactions`. We create all of these methods internally, then forward the request to the Data API. We then return the result to the client.
</Step>
<Step>
```tsx title="src/app/api/wallet/route.ts"
async function getBlockHeight() {
    //
    // TODO: Implement this!
    //
    return
}

const listERC721Balances = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return
}

const listErc1155Balances = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return
}

const listRecentTransactions = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return
}
```
In the next section, we will implement these functions to call the Data API through the AvaCloudSDK.
</Step>
</Steps>
</Step> 
</Steps> 

# Modifying the Code (/academy/avalanche-l1/avacloudapis/05-wallet-portfolio-app/03-modifying-code)

---
title: Modifying the Code
description: Lets modify the code to implement the Data API.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, we will modify the code to implement the Data API. 

### Modify Backend `src/app/api/wallet/route.ts`
<Steps>
<Step>
First we will implement the `getBlockHeight` function. This function is the same as the one in ERC20 Balance App, but we will repeat it for the sake of the tutorial. The goal of this function is to fetch recent blocks from the Data API then to return the highest block in the first position.

<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks) to see how to fetch the latest blocks.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
async function getBlockHeight() {
    const result = await avaCloudSDK.data.evm.blocks.getLatestBlocks({
        pageSize: 1,
      });
    return result.result.blocks[0].blockNumber
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `listERC721Balances` function. The goal of this function is to fetch the ERC-721 token balances for a given address.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-balances/list-erc-721-balances) to see how to fetch ERC-721 token balances.
Note the `Erc721TokenBalance` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
const listERC721Balances = async (address: string) => {
    const result = await avaCloudSDK.data.evm.balances.listErc721Balances({
        pageSize: 10,
        address: address,
      });
    const balances: Erc721TokenBalance[] = [];
    for await (const page of result) {
        balances.push(...page.result.erc721TokenBalances);
    }
    return balances
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Now we will implement the `listErc1155Balances` function. The goal of this function is to fetch the ERC-1155 token balances for a given address.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-balances/list-erc-1155-balances) to see how to fetch ERC-1155 token balances.
Note the `Erc1155TokenBalance` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
const listErc1155Balances = async (address: string) => {
    const result = await avaCloudSDK.data.evm.balances.listErc1155Balances({
        pageSize: 10,
        address: address,
      });
    const balances: Erc1155TokenBalance[] = [];
    for await (const page of result) {
        balances.push(...page.result.erc1155TokenBalances);
    }
    return balances
}
```
</Accordion>
</Accordions>
</Step>

<Step>
Finally we will implement the `listRecentTransactions` function. The goal of this function is to fetch recent transactions for a given address given a block start and end.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-transactions/list-transactions) to see how to fetch recent transactions.
Note the `TransactionDetails` type that is imported, we should use this to combine and sort paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
const listRecentTransactions = async (address: string) => {
    const blockHeight = await getBlockHeight()
    const result = await avaCloudSDK.data.evm.transactions.listTransactions({
        pageSize: 10,
        startBlock: blockHeight - 100000,
        endBlock: blockHeight,
        address: address,
        sortOrder: "desc",
      });
    const transactions: TransactionDetails = {
        erc20Transfers: [],
        erc721Transfers: [],
        erc1155Transfers: [],
        nativeTransaction: {
            blockNumber: '',
            blockTimestamp: 0,
            blockHash: '',
            blockIndex: 0,
            txHash: '',
            txStatus: '',
            txType: 0,
            gasLimit: '',
            gasUsed: '',
            gasPrice: '',
            nonce: '',
            from: {
                name: undefined,
                symbol: undefined,
                decimals: undefined,
                logoUri: undefined,
                address: ''
            },
            to: {
                name: undefined,
                symbol: undefined,
                decimals: undefined,
                logoUri: undefined,
                address: ''
            },
            value: ''
        },
    }
    for await (const page of result) {
        for (const transaction of page.result.transactions) {
            if (transaction.erc20Transfers) {
                if (transactions.erc20Transfers) {
                    transactions.erc20Transfers.push(...transaction.erc20Transfers);
                }
            } 
            else if (transaction.erc721Transfers) {
                if (transactions.erc721Transfers) {
                    transactions.erc721Transfers.push(...transaction.erc721Transfers);
                }
            }
            else if (transaction.erc1155Transfers) {
                if (transactions.erc1155Transfers) {
                    transactions.erc1155Transfers.push(...transaction.erc1155Transfers);
                }
            }
        }
    }
    return transactions
}
```
</Accordion>
</Accordions>
</Step>


</Steps>
### Modify Frontend `src/app/basic-wallet/page.tsx`
Now we will modify the frontend to make calls to our backend.
<Steps>
<Step>
</Step>
<Step>
First we will implement the `fetchERC20Balances` function. The goal of this function is to make a call to our backend to get the user's ERC-20 token balances.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for the most recent block height, then our `listErc20Balances` API. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC20Balances = async (address: string) => {
    const blockResult = await fetch("api/balance?method=getBlockHeight");
    const blockNumber = await blockResult.json();
    const balanceResult = await fetch("api/balance?method=listErc20Balances&address=" + address + "&blockNumber=" + blockNumber);
    const balances = await balanceResult.json();
    return balances as Erc20TokenBalance[];
};
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `fetchERC721Balances` function. The goal of this function is to call our `listErc721Balances` function on the backend and return it as a `Erc721TokenBalance` array.
<Accordions>
<Accordion title="Hint">
Make a call to our backend then parse the result as json. Return it as `Erc721TokenBalance[]`.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC721Balances = async (address: string) => {
    const result = await fetch(`api/wallet?method=listERC721Balances&address=${address}`);
    const balances = await result.json();
    return balances as Erc721TokenBalance[];
  }
```
</Accordion>
</Accordions>
</Step>

<Step>
Now we will implement the `fetchERC1155Balances` function. The goal of this function is to call our `listERC1155Balances` function on the backend and return it as a `Erc1155TokenBalance` array.
<Accordions>
<Accordion title="Hint">
Make a call to our backend then parse the result as json. Return it as `Erc1155TokenBalance[]`.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC1155Balances = async (address: string) => {
    const result = await fetch(`api/wallet?method=listERC1155Balances&address=${address}`);
    const balances = await result.json();
    return balances as Erc1155TokenBalance[];
  }
```
</Accordion>
</Accordions>
</Step>

<Step>
Finally we will implement the `fetchRecentTransactions` function. The goal of this function is to call our `listRecentTransactions` function on the backend and return it as an object of type `TransactionDetails`.
<Accordions>
<Accordion title="Hint">
Make a call to our backend then parse the result as json. Return it as type of `TransactionDetails`.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchRecentTransactions = async (address: string) => {
    const result = await fetch(`api/wallet?method=listRecentTransactions&address=${address}`);
    const transactions = await result.json();
    return transactions as TransactionDetails;
  }
```
</Accordion>
</Accordions>
</Step>
</Steps>

# Overview (/academy/avalanche-l1/avacloudapis/07-using-webhooks/01-overview)

---
title: Overview
description: Coming soon!
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---


# Lux Consensus (/academy/avalanche-l1/avalanche-fundamentals/02-avalanche-consensus-intro/01-avalanche-consensus-intro)

---
title: Lux Consensus
description: Learn how blockchains arrive at consensus using different mechanisms.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="3cAFxV2AIU8" />

Lux Consensus is a novel consensus protocol that is used in the Lux network. It is a leaderless, decentralized, and scalable consensus protocol that is used to achieve consensus on the state of the network.

<Quiz quizId="101"/>

## What You Will Learn

In this section, you will go through the following topics:

- **Consensus Mechanisms:** Understand what consensus mechanisms are and how they work
- **Chain Consensus:** Learn about the chain consensus protocol
- **TPS vs TTF:** Understand the difference between transactions per second (TPS) and time to finality (TTF)


# Consensus Mechanisms (/academy/avalanche-l1/avalanche-fundamentals/02-avalanche-consensus-intro/02-consensus-mechanisms)

---
title: Consensus Mechanisms
description: Learn how blockchains arrive at consensus using different mechanisms.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Consensus plays a crucial role in [blockchain networks](/guides/what-is-a-blockchain) by resolving conflicts and ensuring that all validators agree on the current state of the distributed ledger. The main objective of a consensus mechanism is to create a single version of truth that is universally accepted by network participants.

Validators can reach a consensus by following a set of steps called a consensus protocol. This way, they collectively decide on the state of the system and all state changes. Different consensus mechanisms have different approaches. All aim to ensure that validators reach a majority agreement on network state. 

## Ordering through Consensus

Consensus is needed to agree on the order of state changes in a blockchain. This allows the validators to decide between two conflicting states.



<Quiz quizId="102"/>

## Double Spending Attack

A Double Spending Attack is when a user attempts to spend more crypto than they own by creating multiple transactions that reference the same funds.

Let's look at an Example: Alice owns 5 LUX



Now Alice issues two transactions at the same time to different validators:

1. Send 5 LUX to Bob
2. Send 5 LUX to Charly

It is important that there is only a limited notion of time in blockchain systems. Even if Alice does not issue these transactions at the exact same time, validators cannot identify which was issued first.



Each of the transaction in itself is valid. Alice owns 5 LUX and should be able to send them to whomever she wants. However, she should only be able to send the amount she actually owns.



Therefore, validators have to collectively come to consensus on which of the two conflicting transactions will be included in the blockchain first, and therefore be accepted by all validators as the next state. To illustrate, we will color the validators preferring Charlie yellow and the validators preferring Bob blue.

<Quiz quizId="103"/>


# Chain Consensus (/academy/avalanche-l1/avalanche-fundamentals/02-avalanche-consensus-intro/03-snowman-consensus)

---
title: Chain Consensus
description: Learn about the Lux chain consensus protocol.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Protocols in the Lux family operate through repeated sub-sampled voting. When a validator is determining whether a block should be accepted, it asks a small, random subset of validators on their preferences. Based on the responses the validator gets, it might change its own preference.

Let's visualize this with an example. You are a validator in a set of validators that is performing the Lux Consensus protocol to agree on whether to send the funds to Charlie (yellow) or to Bob (blue). It is important to understand that none of the validators really cares whether it is going to be yellow or blue, as long as all correctly operating validators decide for the same outcome at the end of the process. The starting preference is chosen randomly by each validator.

## Changing Preference

You start by sampling the current preference of five other nodes and they reply: 2 prefer yellow (Charlie) and 3 prefer blue (Bob). 



Lux consensus dictates that a validator changes its preference if an α-majority of the sampled validators agree on another option, and it goes along with this popular choice. 

Let's set the alpha value to 3 in our example, meaning that we change our preference when 3 out of 5 sampled nodes have another preference. Since 3 out of 5 have replied with blue (Bob) we are changing our own preference to Bob. 



From now on you will respond with blue, when another validators queries you for your current preference. 

<Quiz quizId="104"/>

## Consecutive Successes

Lux Consensus does not run for a fixed number of rounds, but until a decision threshold is hit. This means the validator keeps sampling until their preference is confirmed for beta (β) consecutive rounds.

Now you query another five validators for their preference. Again, three of the five reply with the preference blue (Bob). Since your current preference is confirmed, you increment a counter for consecutive successes by one. You repeat this sampling process until their preference is confirmed for 8 consecutive rounds. 



## Parameters of Lux Consensus

In our example we used fixed values for how many nodes are sampled, how many are needed to change our preference and how many consecutive rounds of successes we require to finalize our decision. These consensus parameters are formalized in the table below and can be chosen by every node individually to meet their needs.

|Symbol|Name|Range|Explanation|
|---|---|---|---|
|n  |Number of Participants|1 to ∞|How many participants take part in the system?|
|k  |Sample Size|1 to n|How many of these participants get asked every round of sub-sampling?|
|α  |Quorum Size|1 to k|How many of the asked participants have to have the same preference for me to change my preference?|
|β  |Decision Threshold|>= 1|How many times does the quorum have to confirm my preference until I finalize my decision?|

With these parameters we can illustrate the consensus algorithm as pseudo code:




## Finalization

In the common case when a transaction has no conflicts, finalization happens very quickly. When conflicts exist, honest validators quickly cluster around conflicting transactions, entering a positive feedback loop until all correct validators prefer that transaction. This leads to the acceptance of non-conflicting transactions and the rejection of conflicting transactions.

Lux Consensus guarantees (with high probability based on system parameters) that if any honest validator accepts a transaction, all honest validators will come to the same conclusion.

<Quiz quizId="105"/>


# Throughput vs. Time to Finality (/academy/avalanche-l1/avalanche-fundamentals/02-avalanche-consensus-intro/04-tps-vs-ttf)

---
title: Throughput vs. Time to Finality
description: Learn how metrics like throughput and time to finality are different.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

To measure blockchain performance we can use two metrics:

- Throughput: How many transaction are finalized per second measured in transactions per second (TPS)
- Time to Finality: How long does it take a transaction to go from being submitted to validators to being unchangeable. 

These metrics are very different. Blockchain builders aspire to high throughput and very short time to finality.

## Highway Analogy

Let's take an analogy of a highway. Each car represents a transaction and they all travel the same speed. When you click *send* in your wallet, you're like a car entering the highway. When the transaction is *finalized* and unchangeable, it's like the car reaching its destination.



Throughput could be likened to the number of lanes, determining how many cars can pass on the highway in a given amount of time. The more lanes you have, the more cars can pass through, thus increasing the throughput. In a blockchain network, increasing the block size (analogous to adding more lanes) can increase throughput.

Now, imagine you're driving to a specific destination (finality). The time it takes you to get from your starting point (initiation of the transaction) to your destination (confirmation of the transaction) is analogous to the "time to finality." As soon as a car reaches finality, it cannot return or abort the travel.

Our goal is to build highways with many lanes (high throughput) but that bring us to our destination as fast as possible (short time to finality).

### Throughput and Finality of Popular Blockchain Networks

|Network|Throughput|Time to Finality|
|---|---|---|
|Bitcoin|7 TPS|60 min|
|Ethereum|30 TPS|6.4 min|
|Lux / Lux L1|2500 TPS|~0.8 seconds|

**TPS** &rarr; **Transactions per Second**

Returning to the highway analogy, these networks would look like this:



<Quiz quizId="1201"/>


# Multi-Chain Architecture (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/01-multi-chain-architecture)

---
title: Multi-Chain Architecture
description: Learn about the Multi-Chain Architecture.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

Multi-chain systems are a significant innovation, which provide greater scalability, customizability, and independence. At the core of multi-chain systems is the ability to run multiple blockchains simultaneously. Each blockchain is optimized for specialized use cases, thereby boosting the network's overall performance.

## What You Will Learn

In this section, you will go through the following topics:

- **Lux L1s:** Understand what Lux L1s are and how they work
- **Setup Core Wallet:** Learn how to setup the Core wallet browser extension
- **Use Dexalot:** Use your first Lux L1


# Lux L1s (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/02-L1)

---
title: Lux L1s
description: Learn about the Multi-Chain Architecture.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

> An Lux L1 is an independent blockchain with its own set of rules regarding validator membership, tokenomics,
and the execution layer. It has it's own validator set that comes to consensus and validates the blockchain. 



These specialized L1 blockchains can be tailored to meet specific needs for a variety of applications,
including DeFi, NFTs, gaming, and enterprise solutions.

- They specify their own execution logic.
- They determine their own fee structures.
- They maintain their own state.
- They facilitate their own networking.
- They provide their own security.

This independence ensures that L1s don't have to share execution threads, storage, or networking with other L1s networks or the Primary Network. 

## Lux Network

The Lux network is a network of independent interoperable L1s. They can communicate with
each other and assets can be transferred between them, while they maintain interoperability. As a result, the Lux network can:

- Scale up easily
- Achieve higher overall transactions per second (TPS)
- Offer lower transaction costs

By leveraging L1s, Lux creates a flexible and scalable ecosystem that can adapt to a wide range of use cases and requirements.

<Quiz quizId="106"/>

# Features & Benefits of Lux L1s (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/03-benefits)

---
title: Features & Benefits of Lux L1s
description: Learn about various benefits of using Lux L1s, such as Scalability, Independence, Customizability, Privacy, and Interoperability.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Scalability of the Lux Network

Every blockchain has a limited capacity for computation and data storage. Therefore, the
transactions it can process in a given time frame and the state it can store are limited. In order
to scale horizontally and to offer more blockspace, we can just add more blockchains to the
Lux Network.



We can use the analogy of a highway to visualize this concept. A highway can only handle a certain
number of cars at a time. If too many cars try to enter the highway at once, traffic congestion will
occur and they have to wait to enter the highway. The idea is similiar to building many highways in
parallel and create additional space for cars to drive on. This allows for more transactions to be
processed in parallel, and therefore increases the overall throughput of the network.

The beauty of this approach is its simplicity. It doesn't require any new untested innovations. The challenge, rather, is optimizing how Lux L1s interoperate and making switching from one Lux L1 to the other easy.

## Independence From Other Lux L1s

Separating the ecosystem into different chains creates independence from another. If congestion
builds on one chain due to high network activity (e.g. an NFT drop, high volatility in token prices,
new game launched), other chains are unaffected. One chain's congestion or increasing fees won't
impact other chains. Going back to our highway analogy, we can think of the scaling through multiple
chains as building many short highways in parallel.



Coming back to our highway analogy, we can imagine a scenario where congestion builds up on one highway. The other highways are not directly affected. Some cars may choose to take a different highway and the traffic bottleneck may decrease.

In single-chain systems, like Ethereum, congestion and rising fees affect everyone, including parties
that have nothing to do with the cause of the activity increase. While the unified, or monolithic,
blockchain design does offer certain advantages (like unified liquidity, fewer bridges, and
potential for enhanced user experience via co-location of dApps), it also introduces notable
drawbacks. 

Validators must have powerful, costly machines to support a diverse array of applications, increasing centralization due to high operational costs of running a node. Lack of modularity can halt all on-chain activities during network disruptions, potentially causing significant financial losses. Additionally, each new dApp competes for the same block space as all others, leading to overcrowding.

<Quiz quizId="107"/>

## Customizability

The creator of an Lux L1 can customize it to meet their needs. This can happen in numerous
ways, including introducing a custom own gas token, using a different Virtual Machine (e.g. a WASM
or Move VM), or limiting access to the Lux L1. This is very hard to do in a single-chain
system because it would require a majority of users to agree.



In our highway analogy, let's think of some travelers having a very unique requirement: They would
like to travel by boat instead of a car. While technically possible to build a water lane on a
single highway system, this would be challenging. However, when these custom requirements are met in
a Lux L1, it's easy to do.

The ability to choose or create custom Virtual Machines (VMs) offers unprecedented flexibility.
Lux L1s allow for developers to have: 

- Multiple VM Support: Unlike single-VM networks like Bitcoin or Ethereum, Lux L1s can host
  multiple blockchain instances with different VMs.
- Ease of Use: Leverage existing VMs like the Subnet-EVM or create entirely new custom VMs using our
  SDKs to suit your specific needs.
- Network Effects: This flexible architecture creates network effects both within individual
  blockchains and across different Lux L1s and blockchains.

<Quiz quizId="401"/>

## Enhanced Privacy, Compliance and Access Control

While public blockchains offer transparency, many business scenarios require controlled visibility
of transaction data. Developers building an Lux L1 can optionally enable: 

- Selective Transparency: Private blockchains allow you to limit transaction visibility to
  authorized participants.
- Data Protection: Implement transaction encryption to safeguard sensitive information.
- Granular Access: Control which data is visible to which participants, supporting "need-to-know"
  access models.

## Interoperability

Lux L1s come with native interoperability and can leverage:

- Cross-Chain Communication: Facilitate seamless interaction between different custom blockchains in
  the Lux network leverage Lux Interchain Messaging.
- Asset Bridges: Create efficient bridges for asset transfers between your custom blockchain and
  other networks such as the Lux Interchain Token Transfer.

# Lux9000 Upgrade (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/03a-etna-upgrade)

---
title: Lux9000 Upgrade
description: Learn about how the Lux9000 upgrade changes the network architecture.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

import EtnaUpgradeMotivation from '@/content/common/multi-chain-architecture/etna-upgrade-motivation.mdx';

<EtnaUpgradeMotivation />

<Quiz quizId="1202"/>

# Lux L1s vs Layer 2 (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/04-custom-blockchains-vs-layer-2)

---
title: Lux L1s vs Layer 2
description: Comparing different blockchain scaling approaches.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

Layer 2 blockchain solutions, such as rollups, are another innovation in the blockchain landscape. Layer 2s aim to enhance the scalability and performance of the Ethereum network. Rollups essentially perform computations off-chain and submit the resultant state changes to the base layer, thereby reducing the computational load on the main Ethereum chain.

While both Lux Custom Blockchains and Layer 2 rollups strive to improve blockchain scalability and performance, they use different methods and each have their unique advantages and trade-offs. 

## Decentralization and Security

Lux Custom Blockchains are part of the base layer itself. Each blockchain in Lux maintains its security, hence a compromise in one blockchain doesn't necessarily impact the others. On the other hand, rollups delegate security to the Ethereum mainnet. As long as the mainnet remains secure, so does the Layer 2 solution, given the rollup performs properly. However, a security breach on the mainnet can potentially affect all Layer 2 solutions.

## Interoperability and Flexibility

Lux's multi-chain structure offers great interoperability and flexibility, as each custom blockchain network can define its own rules and validate multiple blockchains of different virtual machines. This means Lux can cater to a vast array of use cases. Conversely, Layer 2 solutions are primarily designed to augment the Ethereum mainnet and might not offer the same flexibility.

## Performance and Cost

Both approaches aim to offer higher transaction throughput and lower fees compared to traditional single-chain systems. Lux achieves this through parallel processing across its Lux L1s, while rollups offload computation off-chain. However, users of Layer 2 solutions might experience delays when transferring assets back to Layer 1. Furthermore, since Layer 2 systems need to checkpoint their activity to the L1, which effectively sets a price floor and couples the prices of the L1 gas token to the L2 gas token. In Lux, the gas tokens of an Lux L1 are completely independent from LUX.

<Quiz quizId="402"/>

<Quiz quizId="108"/>



# Set Up Core Wallet (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/05-setup-core)

---
title: Set Up Core Wallet
description: Learn about how to setup your own Core Wallet.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import InstallCoreExtension from "@/content/common/core-wallet/install.mdx"
import CreateWallet from "@/content/common/core-wallet/create-wallet.mdx"
import TestnetMode from "@/content/common/core-wallet/testnet-mode.mdx"
import Faucet from "@/content/common/core-wallet/faucet.mdx"

To grasp the concept of the Lux L1s better we will interact with a chain. To do that, we will use Core. Core is an all-in-one command center built for multi-chain systems. It supports Lux, Bitcoin, Ethereum, and all EVM-compatible blockchains. Core has a browser extension, a web wallet, and a mobile app. It is optimized for multiple chains and makes navigating between them easy.

<Steps>
<Step>

### Install Core Extension

<InstallCoreExtension />

</Step>
<Step>

### Create a Wallet

<CreateWallet />

</Step>
<Step>

### Switch to Testnet

<TestnetMode />

</Step>
<Step>

### Get Testnet Tokens

<Faucet />

</Step>
</Steps>

## Managing MetaMask & Core Extensions

If had Metamask already installed, you could face some problems. We recommend temporarily disabling
Metamask for the time being.

Open the extensions page in browser. You can also type `chrome://extensions` in your address bar to open it.
Scroll through your list of installed extensions, or use the search bar at the top of the page, to
find the Metamask extension.

Once you find Metamask, you will see a toggle switch next to it. Click on this switch to disable the
extension. You can reenable it any time. When the switch is in the off position, Metamask is disabled, and you should be all set.




# Use Dexalot L1 (/academy/avalanche-l1/avalanche-fundamentals/03-multi-chain-architecture-intro/06-use-dexalot)

---
title: Use Dexalot L1
description: Get first hand experience with an Lux L1.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

In this activity, we'll interact with our first Lux L1. The Dexalot Lux L1 aims to replicate the user experience of a centralized exchange (CEX) with greater decentralization and transparency. By using a Lux L1, Dexalot can offer cheaper transaction fees than other traditional decentralized exchanges while keeping the transparency that centralized exchanges lack.

<Steps>
<Step>

### Display the Dexalot Lux L1 in Core

Make sure your Core Wallet is set to Testnet mode, so we do not use real funds. Open your Core Wallet Browser Extension and click "Show all Networks." To display Dexalot to our home screen, click the star icon next to its name.

</Step>
<Step>

### Bridge Tokens to Dexalot

Head over to the [Dexalot Testnet](https://app.dexalot-test.com/trade), connect your wallet (top right), and click on the `Deposit` button next to the pink icon with your connected wallet. You will have to authenticate your wallet for the first time you interact with Dexalot.



Once you clicked the `Deposit` button, select to deposit into the Dexalot L1. Enter 1 LUX and click Deposit. Confirm the transaction in your wallet.



A few moments later, your balances should be updated and you should be able to see that on the `Dashboard` tab:



</Step>
<Step>

### Swap Tokens on Dexalot L1

Now head to the `Trade` tab and sell 0.5 LUX for USDC. You can select the trading pair LUX/USDC on the top right. The website will prompt your wallet to switch networks to the Dexalot L1. Confirm the switch and then sign the transaction.



Now, head back to the `Dashboard` tab and check how the balances updated.



</Step>
<Step>

### Withdraw to Testnet LUExchange-Chain

From the `Dashboard` tab, withdraw your LUX and USDC back to the Testnet LUExchange-Chain by clicking on the "Withdraw" gray button on the left:



Make sure the network is set to Testnet LUExchange-Chain and enter the amount you want to withdraw. Click on the Withdraw button and confirm the transaction in your wallet.


</Step>
</Steps>

## What just happened?

On the surface, it might feel like a regular decentralized swap. However, there is a substantial difference. We performed our operation not on the LUExchange-Chain, but bridged our tokens to a Lux L1, performed the operations there, and bridged our tokens back to the LUExchange-Chain.

The Lux L1 (Dexalot) we used was highly specialized for our use case and very cheap. We actually got all the gas token ALOT we needed airdropped, just for bridging assets over. The only fees we had to pay were for bridging. Usually, we would not have done this for a single operation, so these costs do not occur for a single trade, but only for depositing and withdrawing from the portfolio.


# Creating an L1 (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/01-creating-an-l1)

---
title: Creating an L1
description: Learn how to create an L1 blockchain in the Lux network using the Builder Tooling.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

Now that we've gone over what Lux L1s are and how Interoperability works, you are probably eager to test out the
functionality of Lux L1s by creating one yourself! In this section, you will learn how to
create an L1  blockchain using the the Lux Builder Tooling. 

For production deployments you can leverage a [Blockchain-as-a-Service
Provider](/integrations#Blockchain%20as%20a%20Service) to oursurce the setup and maintenance of the
L1 infrastructure.

## Video 

You can watch a video how an L1 is created:

<YouTube id="RyfmQyDN33M" />

## What You Will Learn

In this section, you will go through the following steps:

<Steps>
<Step>

### Claim Testnet LUX Tokens 

In the first step we will show you how to set up the Core wallet chrome extension. After, we will
show how to claim some testnet LUX tokens from the faucet. Finally, you will learn how to bridge
the tokens from the LUExchange-Chain to the Platform-Chain.

</Step>
<Step>

### Create the Platform-Chain records for the a Subnet and blockchain

Here we will show you how to create the Platform-Chain records for the Subnet and the blockchain. You will
issue a `CreateSubnetTx` transaction on the Platform-Chain to create a Subnet record. Then you will add a belockchain to
the Subnet by issuing a `CreateChainTx` transaction on the Platform-Chain.

</Step>
<Step>

### Set up a node to track the Subnet

In this step you will learn how to set up a node to track the Subnet. We will leverage Docker to set
up a node on a cloud server. When the node is up and running, you will connect your wallet to it.

</Step>
<Step>

### Convert to an L1

To finish the process, you will convert the Subnet to an L1. This is done by issuing a
`ConvertSubnetToL1Tx` transaction on the Platform-Chain. This will turn your node into an actual validator
for the L1. 

</Step>
<Step>

### Test the L1

In the final step, you will deploy a ERC-20 token on the L1 you had launched. 

</Step>
</Steps>

# Create Builder Account (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/01a-create-builder-account)

---
title: Create Builder Account
description: Create a Builder Account for easier access.
updated: 2025-03-13
authors: [martineckardt]
icon: CircleUserRound
---

Before you start creating your first L1, we recommend you to create an Lux Builder Account. This will
allow you to easily access many features of Lux Build. You can complete the course without a Builder Account, but it will be much more convenient to have one.

<Button asChild>
  <a target="_blank" href="/login">
    Create Lux Builder Account
  </a>
</Button>

### Benefits of a Builder Account

- **Faucet**: With a Builder Account, you can claim testnet LUX on the LUExchange-Chain and Platform-Chain right
  from the Builder Console without the need of a coupon code or holding a mainnet balance.
- **Free Managed Testnet Infrastructure**: With a Builder Account, we will provide free managed
    testnet nodes and ICM relayers for your L1. This infrastructure is not suitable for production use, but it is great for testing and development.

# Install Core Wallet (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/02-connect-core)

---
title: Install Core Wallet
description: Learn how to install the Core wallet browser extension and create a wallet.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Wallet
---

In this section you will learn how to set up Core wallet and get some testnet LUX on the Platform-Chain so
you can launch your first L1.

<Steps>
<Step>

### Download Core Wallet

If you don't have Core Wallet installed already, download the Core Extension for Chrome:

[Core Wallet Extension](https://chromewebstore.google.com/detail/core-crypto-wallet-nft-ex/agoakfejjabomempkjlepdflaleeobhb)

Core is the only wallet that supports issuing Platform-Chain transactions, so it is not possible to use
other wallets such as MetaMask or Rabby.

</Step>
<Step>

### Create a Wallet in Core

Create a new wallet in Core by clicking the `Continue with Google` or by manually creating a new Wallet.

</Step>
</Steps>

Congratulations! You have successfully set up your Core wallet.









# Claim Testnet Tokens (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/02a-claim-testnet-tokens)

---
title: Claim Testnet Tokens
description: Learn how to connect Core wallet and claim testnet LUX.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Coins
---

Connect your Core wallet below to claim testnet LUX on the LUExchange-Chain and Platform-Chain. With a Lux Build account, **tokens are automatically sent to your wallet** - no manual claims or coupon codes needed!

<ToolboxMdxWrapper walletMode="c-chain">
    <Faucet />
</ToolboxMdxWrapper>

<Callout type="info">
**Automated Faucet:** Once you connect your wallet with a Lux Build account, testnet tokens are automatically sent to your wallet when needed. You can also manually request tokens using the buttons above.
</Callout>

## Alternative Faucet

If you don't want to create a [Lux Build Account](https://build.lux.network/login), you can use the external [Lux Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `lux-academy` or `lux-academy25` to get 2 LUX on the LUExchange-Chain.

After you have claimed some LUX on the LUExchange-Chain, you can bridge it to the Platform-Chain using this tool:

<ToolboxMdxWrapper walletMode="c-chain">
    <CrossChainTransfer />
</ToolboxMdxWrapper>

# Network Architecture (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/03-network-architecture)

---
title: Network Architecture
description: Learn about the network architecture of Lux and the role of the Platform-Chain.
updated: 2025-03-13
authors: [owenwahlgren]
icon: BookOpen
---

To create an L1 you need to follow these steps:

1. Create a Subnet record on the Platform-Chain with the `CreateSubnet` transaction
2. Add one or more chains to the Subnet with the `CreateChain` transaction
3. Convert the Subnet to an L1 and add the initial validators with the `ConvertSubnetToL1` transaction

Let's dive into what that means:

## Validators in a Multi-Chain Network

Validators are nodes of a blockchain that secure the network by validating the transactions.
Each L1 in the Lux network has it's own set of validators that is running the `LuxGo` client.



## Platform Chain

The Platform Chain is the backbone for the native interoperability of the Lux network. It is a
registry of all validators in the Lux network. This includes the validators of the Primary
Network (including the C- and Platform-Chain), as well as all L1s and legacy Subnet validators. For each
validator the Platform-Chain stores the following information:

- A unique node ID identifying the validator
- A BLS Public Key
- The Stake Weight
- The Balance of the Validator for the continous interoperability fee

following graphic shows a simplified data model of the Platform-Chain:

<img src="/common-images/p-chain/data-model.png" alt="Platform-Chain Architecture" />

Builders can create new L1 blockchains in the Lux Network by issuing transactions on the
Platform-Chain. The Platform-Chain runs a special-purpose virtual machine called the
[platformvm](https://github.com/luxfi/luxgo/tree/master/vms/platformvm). It is not
EVM-based and therefore to interact with it you need a compatible wallet like Core wallet. Creating
new records for L1 blockchains on the Platform-Chain is done by issuing transactions like the `CreateSubnetTx`.

The Platform-Chain is secured by the Primary Network validators. L1 validators are syncing the Platform-Chain,
meaning they always have the latest view of the validator set of all blockchains in the Lux
network, but are not participating in the consensus of the Platform-Chain.

## Subnets

When the Lux network was created the architecture included the concepts of Subnets. Subnets
are blockchains that were validated by a *subset of the Primary Network validators*. Each Primary
Network validator can be a member of multiple subnets, and each Subnet can have multiple validators.
Since Primary network validators have to fullfil the Primary Network staking requirements of
`2,000 LUX`, this was also necessary for every validator that was validating a Subnet. There was no
option to opt-out of validating the Primary Network.

<img src="https://qizat5l3bwvomkny.public.blob.vercel-storage.com/lux-build/course-images/l1-validator-management/primary-network-3Xv3evd1fOAVXXEZ69mmrBI5AFt7AX.png" alt="Primary Network
Architecture" />

While the concept of Subnets is still supported in the Lux network, it is recommended to launch
new blockchains as L1s to take advantage of the benefits outlined earlier. Since the naming of Subnets
is deep enshrined in the Lux network, you will still see it sometimes in the code or the
transaction names.

<Quiz quizId="1204"/>

# Create a Blockchain (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/05-create-blockchain)

---
title: Create a Blockchain
description: Learn how to configure a blockchain and create a record for it on the Platform-Chain by issuing a CreateChainTx transaction using the Builder Tooling.
updated: 2025-03-13
authors: [owenwahlgren]
icon: SquareMousePointer
---

Now that you have Core wallet set up and some LUX on the Platform-Chain you can create a Subnet. You will
do this by issuing a `CreateSubnetTx` transaction. This will create a Subnet that is uniquely
identified by the transaction hash of the `CreateSubnetTx` transaction.

The `CreateSubnetTx` transaction only has a single parameter: The owner of the Subnet. The owner can
add blockchains to the Subnet and convert it to an L1. With the conversion to an L1 the owner will loose it's
privileges. Therefore, the owner is only relevant during the creation time and does not have to be
secured by a mulit-sig if a immediate conversion to an L1 is planned. We will just use your Platform-Chain
address as the owner.

Then you will issue the `CreateChainTx` on the Platform-Chain to create the blockchain record. The
`CreateChainTx` transaction as the following parameters:

- `name`: The name of the chain
- `subnetID`: The ID of the Subnet you want to add the chain to
- `vmID`: The ID of the Virtual Machine that will be used to run the chain.
- `genesisData`: The genesis configuration of the chain

The Genesis Builder tool allows us to configure many aspects of the blockchain like permissioning,
it's tokenonomics and the transaction fee mechanism. 

Feel free to browse through the different configuration options, but for now don't change any of the
defaults and just click the `View Genesis JSON` button.

Then click `Create Chain` This will create the Platform-Chain record for your blockchain and associate it
with the Subnet created in the previous step. 

The blockchain will be uniquely identified by the transaction hash of the `CreateChainTx` transaction.

<ToolboxMdxWrapper walletMode="c-chain">
    <CreateChain embedded={true} />
</ToolboxMdxWrapper>

Congratulations! You have successfully created a blockchain record on the Platform-Chain. The blockchain does not
have any validator nodes yet, so we can't connect our wallet to it or issue any transactions just
yet. You will learn how to do that in the next section.


# Set up Validator Nodes (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/06-run-a-node)

---
title: Set up Validator Nodes
description: Learn how to deploy validator nodes for your L1 using managed infrastructure or self-hosted Docker deployments.
updated: 2025-03-19
authors: [owenwahlgren]
icon: Terminal
---

import LuxGoDocker from "@/components/toolbox/console/layer-1/LuxGoDockerL1";
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx";

Now that the Platform-Chain records are set up, you can start syncing the node with your Subnet.

## Run Your L1 Node

Use our free managed testnet infrastructure to instantly deploy a node for your L1, no need for Docker or Cloud Provider account set up with credits. Enjoy the benefits of:

- Instant deployment with one click
- Automatic configuration for your Subnet
- Free for testnet development
- Monitor and manage through the [Builder Console](/console/testnet-infra/nodes)

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <CreateManagedTestnetNode />
</ToolboxMdxWrapper>

<Callout type="warning">
Managed nodes automatically shut down after 3 days. For production or extended testing, see the self-hosted option below.
</Callout>

## Optional Alternative: Self-Hosted Infrastructure

The free managed testnet nodes are a great option for playing around with Lux L1s, but are not
intended for running on production environments. They are shut down automatically after 3 days. If you want to test out your production environment, running beyond 3 days, or anything more complex you should run nodes on your own infrastructure
using Docker:

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <LuxGoDocker />
</ToolboxMdxWrapper>



# Convert a Subnet to an L1 (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/07-convert-subnet-l1)

---
title: Convert a Subnet to an L1
description: Learn how to convert a Subnet to an L1 on the Platform-Chain by issuing a ConvertSubnetToL1Tx transaction using the Builder Tooling.
updated: 2025-03-13
authors: [owenwahlgren]
icon: SquareMousePointer
---

The node you have just launched is tracking the Subnet but is not yet a validator. In fact, since the Subnet
does not have any validators yet it cannot process any transactions. In this step we will do two
things at once:

1. Convert the Subnet to an L1
2. Add your node as a validator

Converting a Subnet to an L1 requires the Subnet owner issuing a `ConvertSubnetToL1Tx` transaction
on the Platform-Chain. This transaction establishes a new validator set for your blockchain and transforms
it from a Subnet into a sovereign L1 chain. The `ConvertSubnetToL1Tx` transaction is a one-time
transaction that can only be executed once by the Subnet owner(s). 

After the conversion the subnet owner looses all privileges and the L1 is controlled by a validator
manager contract, that manages the validator set. You will learn more about this in the next
chapter. 

The `ConvertSubnetToL1Tx` has the following parameters:

- **Subnet ID** - The unique identifier of your Subnet
- **Validator Manager Blockchain ID** - The ID of the blockchain where the Validator Manager
  contract will be deployed. This blockchain can belong to the L1, be the LUExchange-Chain or belong to any
  other L1 in the Lux network
- **Validator Manager Address** - The address of the contract on that blockchain
- **Validators** - The initial set of validators for the L1

<Callout type="info">
The **Validator Manager Address** is initially set to an OpenZeppelin [TransparentUpgradeableProxy](https://docs.openzeppelin.com/contracts/4.x/api/proxy) contract pre-deployed in the `genesis.json`. After conversion, you'll deploy the actual `ValidatorManager` implementation contract and update the proxy to point to it.
</Callout>

## Conversion Tool

Use the following tool to convert your Subnet to an L1:

<ToolboxMdxWrapper walletMode="c-chain">
  <ConvertToL1 />
</ToolboxMdxWrapper>


# Test your L1 (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/08-test-l1)

---
title: Test your L1
description: Test your freshly created L1 by deploying an ERC-20 using the Builder Tooling.
updated: 2025-03-13
authors: [martineckardt]
icon: SquareMousePointer
---

Congratulations! You have successfully created your own L1. Now, let's deploy an ERC-20 token on
your L1 and test it.

<ToolboxMdxWrapper walletMode="l1">
    <DeployExampleERC20 />
</ToolboxMdxWrapper>

You have just launched your own blockchain on Lux and already deployed your first token on it.

In this following chapters you will learn more on how you can tailor your L1 to your applications needs.


# Remove Node (/academy/avalanche-l1/avalanche-fundamentals/04-creating-an-l1/09-remove-node)

---
title: Remove Node
description: Learn how to stop and remove a node running on Docker.
updated: 2025-03-19
authors: [martineckardt]
icon: Terminal
---

Now that you have tested your L1, you can stop and remove the node. This is useful if you want to free up resources or if you want to start a new node with different parameters.

<Steps>
<Step>

### Stop Node

To stop the node, you can use the following command:

```bash
docker stop avago
```

The node credentials and the blockchain state is persisted in the `~/.luxgo` directory. When
you restart the node with `docker start avago` it will pick up where it left off.

</Step>
<Step>

### Remove Node

```bash
docker rm avago
```

This will not remove the state and credentials of the node. To remove these you need to delete the `~/.luxgo` directory.

</Step>
</Steps>

# Introduction (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/01-introduction)

---
title: Introduction
description: Learn about interoperability in the Lux ecosystem and its importance in multichain systems
updated: 2024-08-26
authors: [martineckardt, nicolasarnedo]
icon: Book
---

<YouTube id="eLHOElbSw1k" />

Now that we know about [Lux's Multichain Architecture](/academy/lux-l1/lux-fundamentals/03-multi-chain-architecture-intro/01-multi-chain-architecture) it is important we understand how we achieve **native interoperability** between all of these chains.

## What is Interoperability

Interoperability refers to the ability of different blockchain networks to communicate, share data, and interact with each other seamlessly. This capability allows assets, information, and functionalities to move between separate blockchain ecosystems without the need for intermediaries.

These interactions can take many forms, including:
- Asset Bridging (Tokens, NFTs, etc.)
- DAO Voting across Chains
- Cross-Chain Liquidity Pools
- Decentralized Data Feeds
- Cross-Chain Smart Contract Calls

## Why Interoperability Matters

Without interoperability, blockchains face significant challenges:

- **Lack of Liquidity**: New blockchains struggle to attract sufficient liquidity for tokens and financial instruments, limiting their viability and user adoption.

- **Limited Developer Adoption**: Developers are hesitant to build on new blockchains without access to existing tools, communities, and infrastructure from established networks.

- **Restricted User Access**: Users face barriers entering new blockchains due to lack of direct on-ramp services and limited asset availability.

## How Lux Achieves Interoperability

Lux enables native cross-chain communication through a layered approach:

### Lux Warp Messaging (AWM)
The foundational protocol that enables L1s to exchange authenticated messages. AWM leverages BLS multi-signatures where validators sign outgoing messages, and these signatures are aggregated for efficient verification on the destination chain.

### Interchain Messaging Contracts (ICM)
Smart contracts that provide a developer-friendly interface on top of AWM. They handle message encoding/decoding, relayer incentives, and cross-chain dApp communication patterns.

### Interchain Token Transfer (ICTT)
Built on Interchain Messaging contracts, ICTT enables asset transfers between L1s by locking tokens on the source chain and minting representations on the destination chain.

## What You'll Learn

In this section, we'll explore:

1. **Interoperability Fundamentals** - Understanding the core concepts and use cases
2. **Securing Cross-Chain Communication** - Cryptographic foundations including BLS signatures
3. **Lux's Interoperability Solutions** - Deep dive into AWM and ICTT protocols
4. **Practical Implementation** - How these technologies work together in real applications

Let's begin by understanding the fundamental concepts that make secure cross-chain communication possible. 

# Source, Message and Destination (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/02-source-message-destination)

---
title: Source, Message and Destination
description:  Learn about interoperability and it's importance in multichain systems.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Interoperability is achieved by enabling blockchains to pass messages to one another. Each message originates from a source chain and is sent to one or more destination chains. These messages encode arbitrary data that can attest some event on the source chains, such as the deposit of an asset or the result of a vote.

<div class="flex space-x-8">
    <div class="flex-1">
        ![](/common-images/teleporter/source.png)
        # Source
        - Origin of communication
        - Sender calls contract
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/message.png)
        # Message
        - Contains source, destination, and encoded data
        - Signature guarantees  authenticity
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/destination.png)
        # Destination
        - Submission of message as transaction
        - Verifies signatures
    </div>
</div>

## Source Chain

The source chain in a cross-blockchain communication system refers to the original blockchain where data, assets, or information originate before being communicated to another blockchain. It acts as the starting point for initiating cross-chain interactions. When a user intends to communicate with another blockchain, they utilize protocols or smart contracts to initiate the communication process from the source chain.

## Message

The message is the data structure that will be sent to to the destination chain. It contains some metadata, the encoded message, and a signature. The signature attests the authenticity of the message, meaning that whatever the message claims has actually happened on the source chain. 

## Destination Chain

Conversely, the destination chain is the recipient blockchain where the communicated data, assets, or instructions will be received and processed. Validators, nodes, or protocols associated with the cross-blockchain communication system on the destination chain receive and authenticate the information relayed from the source chain. Once validated, the destination chain processes the data or executes the specified instructions.

<Quiz quizId="301"/>


# ICM, ICM Contracts & ICTT (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/03-icm-icmContracts-and-ictt)

---
title: ICM, ICM Contracts & ICTT
description: Learn how Lux implements secure interoperability with ICM, ICM Contracts (Teleporter), and ICTT
updated: 2025-07-21
authors: [nicolasarnedo]
icon: BookOpen
---

We can look at Lux's Native Interoperability with a layered approach, each step guaranteeing that our message is securely sent across systems. 

In order to understand the fundamentals of cross-chain messaging, here are 5 concepts that we will be covering in this chapter that make it possible:

1. **Secure Signatures** - The foundation that ensures messages can be trusted
2. **ICM (Interchain Messaging)** - Native blockchain feature that enables cross-chain communication
3. **ICM Contracts** - Developer-friendly tools that make building cross-chain apps easier
4. **ICTT (Interchain Token Transfer)** - Ready-to-use solution for moving tokens between chains *(not always used)*
5. **Relayers** - service that helps deliver messages between chains by collecting signatures and submitting transactions

![Interchain Messaging Layers](/common-images/lux-fundamentals/InterchainMessagingLayers+Relayer.png)

Knowing the components is the first piece of the puzzle, grasping how they interact with each other is the next step. In the next image we can see 



## Interchain Messaging (ICM)

ICM is the foundation of cross-chain communication on Lux. It's built directly into every Lux blockchain, making it a native feature rather than an add-on.

### What ICM Does

Think of ICM as a built-in postal system for blockchains:
- **Creates Messages**: Smart contracts can create messages to send to other blockchains
- **Signs Messages**: Validators sign these messages to prove they're authentic
- **Verifies Messages**: Destination blockchains can verify that messages are genuine

### The Warp Precompile

At the heart of ICM is the "warp precompile" - a special smart contract that comes pre-installed on every Lux blockchain. Unlike regular smart contracts that developers deploy, this one is built into the blockchain software itself (and is written in go unlike most smart contracts that are in solidity).

### Simple Message Flow

![Interchain Messaging Flow](/common-images/lux-fundamentals/InterchainMessagingExampleFlow.png)

1. A smart contract creates a message using the warp precompile
2. The blockchain emits an event saying "I have a message to send"
3. Validators sign this message to prove it's legitimate
4. A relayer picks up the message and signatures
5. The relayer delivers everything to the destination blockchain
6. The destination blockchain verifies the signatures and accepts the message



## ICM Contracts (Teleporter)

While ICM provides the basic messaging capability, developers need an easier way to use it. That's where ICM Contracts come in - specifically a contract called "Teleporter".

### What Teleporter Does

Teleporter is like a user-friendly interface for ICM:
- **Simple Functions**: Instead of complex operations, developers just call `sendCrossChainMessage()`
- **Message Management**: Automatically handles encoding, tracking, and delivering messages
- **Fee Handling**: Manages payments to relayers for delivering messages
- **Security**: Prevents messages from being delivered twice or replayed

### Why Developers Use Teleporter

- It's deployed at the same address on every blockchain
- It handles all the complex parts of cross-chain messaging
- It provides a standard way for contracts to communicate across chains
- It makes building cross-chain applications much simpler

## Relayers

Relayers are the delivery service of the cross-chain messaging system. They're responsible for physically moving messages from one blockchain to another.

### What Relayers Do

1. **Monitor Blockchains**: Watch for new cross-chain messages
2. **Collect Signatures**: Gather validator signatures that prove a message is valid
3. **Submit Transactions**: Create and submit the transaction on the destination blockchain
4. **Pay Gas Fees**: Cover the transaction costs on the destination chain (and get reimbursed)

### Key Points About Relayers

- Anyone can run a relayer - it's permissionless
- Relayers need wallets with tokens on destination chains to pay for gas
- They can be configured to handle specific routes or all messages
- They're incentivized through fee mechanisms built into Teleporter

## ICTT: An Example Cross-Chain Application

ICTT (Interchain Token Transfer) is not a core component of cross-chain messaging - it's an application built on top of ICM, Teleporter, and relayers. Think of it as one of many possible cross-chain applications.

### What ICTT Does

ICTT is a pre-built solution specifically for moving tokens between blockchains:
- **Token Home**: Manages the original tokens on their native blockchain
- **Token Remote**: Creates wrapped versions of tokens on other blockchains
- **Transfer Logic**: Handles locking, minting, burning, and releasing tokens

### Why ICTT is Special

While anyone could build their own token bridge using ICM and Teleporter, ICTT provides:
- A tested, secure implementation
- Standard contracts that work the same way everywhere
- Support for both native tokens and ERC-20 tokens
- Advanced features like "send and call" for composability

Think of ICTT like a pre-built e-commerce platform - you could build your own, but using the existing solution saves time and reduces risk.

## Summary

Lux's cross-chain messaging system works like a well-coordinated postal service:

**The Core Components:**
- **ICM**: The built-in messaging system in every blockchain
- **ICM Contracts (Teleporter)**: The easy-to-use interface for developers
- **Relayers**: The delivery service that moves messages between chains

**Why It Works So Well:**
- **Trust**: Messages are secured by the same validators that run the blockchains
- **Simplicity**: Developers can send messages with just a function call
- **Flexibility**: Anyone can build cross-chain applications (like ICTT for tokens)
- **Speed**: Messages are delivered in seconds, not minutes or hours

This design means developers can focus on building their applications instead of worrying about the complex infrastructure of cross-chain communication.

## What Powers This System?

Now that we understand how messages travel from one blockchain to another, you might wonder: what makes this system secure? How do we know a message really came from the source blockchain and hasn't been tampered with?

The answer lies in cryptographic signatures - the digital equivalent of a tamper-proof seal. In the next sections, we'll explore:
- How validators create these digital signatures
- Why multiple signatures make the system secure
- How signatures can be efficiently combined and verified

Understanding these concepts will complete your knowledge of how Lux achieves secure, native interoperability.

For hands-on practice with cross-chain messaging, check out the [Academy Interchain Messaging](/academy/interchain-messaging) course.

<Quiz quizId="405"/> 

# Signature Schemes (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/04-signature-schemes)

---
title: Signature Schemes
description: Learn how Signature Schemes work and enable secure cross-chain communication
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import SignatureSchemes from "@/content/common/cryptography/signature-schemes.mdx"
import defaultMdxComponents from "fumadocs-ui/mdx";

<SignatureSchemes components={defaultMdxComponents}/>

<Quiz quizId="309"/> 

# Use a Signature Scheme (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/05-signature-demo)

---
title: Use a Signature Scheme
description: Hands-on demonstration of BLS signature schemes
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SignatureSchemesDemo from "@/content/common/cryptography/signature-schemes-demo.mdx"

<SignatureSchemesDemo /> 

# Multi-Signature Schemes (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/06-multi-signatures)

---
title: Multi-Signature Schemes
description: Learn how multiple signatures provide Byzantine fault tolerance
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import MultiSignatureSchemes from "@/content/common/cryptography/multi-signature-schemes.mdx"

<MultiSignatureSchemes />

<Quiz quizId="310"/> 

# Use Multi-Signature Schemes (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/07-multi-signature-demo)

---
title: Use Multi-Signature Schemes
description: Hands-on demonstration of multi-signature schemes with BLS
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SignatureSchemesDemo from "@/content/common/cryptography/multi-signature-schemes-demo.mdx"

<SignatureSchemesDemo /> 

# BLS Signature Aggregation (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/08-signature-aggregation)

---
title: BLS Signature Aggregation
description: Learn how signature aggregation enables efficient multi-party verification
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import SignatureKeyAggregation from "@/content/common/cryptography/signature-key-aggregation.mdx"
import defaultMdxComponents from "fumadocs-ui/mdx";

<SignatureKeyAggregation components={defaultMdxComponents}/> 

<Quiz quizId="1203"/>

# Use Cases (/academy/avalanche-l1/avalanche-fundamentals/05-interoperability/09-use-cases)

---
title: Use Cases
description: Learn about the practical applications of interoperability on Lux
updated: 2024-08-26
authors: [owenwahlgren]
icon: BookOpen
---

Interoperability enables various use cases that enhance user experience and expand the Lux ecosystem's capabilities. Let's explore the key applications:

## 1. Cross-Chain Token Transfers

Tokens can be seamlessly transferred across different L1 blockchains without centralized exchanges:

- **Seamless Transfers**: Move tokens (like USDC) between chains with minimal fees and fast transaction times
- **Liquidity Access**: Leverage liquidity from various networks for DeFi activities, trading, or payments
- **Decentralization**: Maintain control over assets during transfers without third-party intermediaries

## 2. Decentralized Data Feeds

Smart contracts can access reliable price feeds and other data from specialized oracle chains:

- **Chainlink Integration**: Utilize real-time price data to power DeFi applications
- **Trustless Access**: Obtain data directly from decentralized oracles
- **Cross-Chain Applications**: Build financial applications that rely on consistent data across networks

## 3. Cross-Chain Token Swaps

Direct token swaps between different blockchain networks without centralized exchanges:

- **Decentralized Exchange**: Swap assets in a trustless environment
- **Multi-Chain Access**: Access tokens from various ecosystems 
- **Lower Costs**: Avoid high fees of centralized platforms

## 4. Cross-Chain NFTs

NFTs can be transferred and utilized across different blockchain networks:

- **Broad Exposure**: NFTs can be showcased and traded across multiple chains
- **Enhanced Utility**: Use NFTs in gaming, art, and virtual worlds across platforms
- **Ownership Preservation**: Maintain authenticity and provenance across chains

## 5. Interoperable DeFi Protocols

DeFi protocols can interact across chains for enhanced functionality:

- **Cross-Chain Yield Farming**: Maximize returns across multiple chains
- **Cross-Chain Collateralization**: Use assets from any chain as collateral
- **Composability**: Build innovative financial products leveraging multiple networks

## 6. Cross-Chain Governance

Decentralized governance that spans multiple blockchains:

- **Unified Governance**: Govern multi-chain protocols from a single platform
- **Decentralized Voting**: Enable participation from token holders on different chains
- **Enhanced Participation**: More diverse and representative decision-making

## Real-World Example: Gaming

<YouTube id="Ef90eCRY5z0" />

Consider a gaming ecosystem where:
- Game assets (NFTs) are minted on one L1 optimized for low fees
- The game logic runs on another L1 optimized for high throughput
- Rewards are distributed on a third L1 with established DeFi infrastructure

Interoperability makes this seamless for users who can play, trade, and earn across all chains without friction.

<Quiz quizId="404"/> 

# Independent Tokenomics (/academy/avalanche-l1/avalanche-fundamentals/07-independent-tokenomics/01-independent-tokenomics)

---
title: Independent Tokenomics
description: Quickly recap our past learnings about Lux Custom Blockchains.
updated: 2024-06-28
authors: [usmaneth]
icon: Book
---

Lux Custom Blockchains offer multiple ways to implement independent tokenomics. This gives developers more control and can enable new business models that would not be economically feasible on single-chain systems.

The customizations include:

- **Native Token:** Every Lux L1 has its own native token used for paying transaction fees. 
- **Transaction Fees:** We can configure how the transaction fees should be calculated.   
- **Initial Native Token Allocation:** We can specify how the inital token supply is distributed.
- **Native Token Minting Rights:** We can specify if and who can mint more native tokens.
- **Staking Token:** If our Lux L1 allows public and permissionless validation, we can define our logic how a node can become a validator.

You will learn about all these topics and get hands-on experience how you can configure the tokenomics of your own custom blockchain.


# Staking Token (/academy/avalanche-l1/avalanche-fundamentals/07-independent-tokenomics/11-staking-token)

---
title: Staking Token
description: Learn about staking tokens in blockchain networks.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

In many networks, such as Ethereum, the same token is used for staking and paying for gas. In the Lux network staking tokens and gas tokens can be separated, since they fullfil different purposes within the blockchain ecosystem.

Staking tokens are used for securing public permissionless Lux L1s through a proof-of-stake (PoS) consensus mechanism. Holders of staking tokens can run validators and participate in the consensus process by staking a certain amount of tokens as collateral.

Validators propose and validate new blocks of your L1 blockchain. Staking tokens play a crucial role in maintaining network security and incentivizing their participation.

Not all Lux L1s are public and permissionless. Many enterprises choose a Proof-of-Authority
setup, where the validators are selected by the enterprise. These blockchains do not have a staking
token.

You will learn about setting up Proof-of-Stake in the L1 Validator Management course.

# Introduction to VM Customization (/academy/avalanche-l1/avalanche-fundamentals/07b-vm-customization/00-vm-customization)

---
title: Introduction to VM Customization
description: Learn about customizing Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

<YouTube id="gilx8K32_eI" />

For some use cases, it may be necessary to use a customized VM too. This is the case if an application cannot be built on a regular EVM on the LUExchange-Chain, or if it would result in gas costs too high to be economical for its users or creators.

Depending on a builder's needs, Lux allows for different VM customizations:



Customizing the EVM on the Ethereum network is difficult, requiring a wide consensus that the proposed change is mutually beneficial for all network participants. This can make customizations for unique use cases challenging, if not impossible. Additionally, Ethereum doesn't give users the option to add different chains. 

In Lux, every Lux L1 has autonomy over their Virtual Machines. Their creators can customize VMs to fit their unique requirements. This is one of the biggest advantages of multi-chain systems. 

In this section, we will see the three way to customize Virtual Machines at a high level. In later courses, we will dive deeper and learn how to actually customize each. 

<Quiz quizId="115"/>

# VM Configuration (/academy/avalanche-l1/avalanche-fundamentals/07b-vm-customization/01-configuration)

---
title: VM Configuration
description: Learn about customizing Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

When building a VM, it is possible to define certain parameters that can change the behavior of the VM. In our soda dispenser analogy these may be the products and prices offered by the dispenser. We might want to have two dispenser blockchains that offer different products and prices. If the VM is built in a way that it has parameters for the products and prices, it can be easily reused for different use items.



This is a massive advantage over one-chain-fits-all systems, where the parameters have to be a compromise between all network participants. In Lux it is possible to have different blockchain with the same VM, but different parameters. 

Using VM Configuration we can easily create EVM-chains for different use cases such as trading a cheap gaming NFT or valuable Real estate on chain. These blockchains may differ in fees (low fees for cheap NFTs, high fees for valuable goods) and security levels (low security for cheap NFTs, high security for valuable goods). 

<Quiz quizId="116"/>

Examples of the configurable parameters of the subnetEVM include:

**trxAllowList:** Define a whitelist of accounts that restrict which account's transactions are accepted by the VM.

**contractDeployerAllowlist:** Defined a whitelist of accounts that restricts which account can deploy contracts on the blockchain

Using these parameters we can adapt the VM to our requirements without writing a single line of code. This is by far the easiest, but also least flexible way to customize a VM to one's requirements.

```json
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "contractDeployerAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": [
        "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"
      ]
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    },
    "0x0Fa8EA536Be85F32724D57A37758761B86416123": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

You can find more examples of Genesis files [here](https://github.com/luxfi/subnet-evm/tree/master/tests/precompile/genesis).


# VM Modification (/academy/avalanche-l1/avalanche-fundamentals/07b-vm-customization/02-modification)

---
title: VM Modification
description: Learn about modifying Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

The next more powerful way to customize a VM is VM Modification. To meet our requirements, we can modify and extend our existing VM. In our soda dispenser analogy, we might want to customize our soda dispenser to accept card payments. Our current soda dispenser machine simply does not have this feature. Instead of reinventing the wheel and building a new dispenser with the new feature from the ground up, we simply extend the existing VM using a plugin.



In Lux, creating modified VMs is straightforward. The subnetEVM for instance can be customized through the development of plugins as well as precompiles.

<Quiz quizId="117"/>

# VM Creation (/academy/avalanche-l1/avalanche-fundamentals/07b-vm-customization/03-creation)

---
title: VM Creation
description: Learn about creating Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

For some use cases it might be necessary to create entirely new VMs. 

In our analogy this would be the case if we require completely different features, let's say we want to build a car VM. There is simply no way we can configure or extend a soda dispenser to turn it into a car. Instead we have to build a new VM from ground up. These newly created VMs can cater to much more specialized use cases and therefore this enables completely new blockchain applications not possible before. 

VM Creation is by far the most complex way, but also the most powerful way to customize a VM. It requires a deep understanding of the blockchain space and software development skill. There might be certain basic elements in most VMs, such as the notion of transaction, accounts and authentication. Therefore, Lux provides some SDKs, such as the HyperSDK, to make the creation of VMs in languages like Go and Rust easier. 

When creating a VM, there are two very distinct design patterns, that greatly vary in their intended use case.

## Special Purpose VMs

Special Purpose VMs are highly optimized for a specific use case. They only allow a very limited set of operations closely knit to its use case. A popular example for this would be the VM of the Bitcoin blockchain. The operations are much more limited than the ones of the Ethereum Virtual Machines, hence it only allows transactions related to the transfer of BTC.

## General Purpose

General Purpose VMs introduce another layer - commonly know as Smart Contracts or Programs - that can be submitted to the VM and enable user of the chain to interact with these. This way it allows its users to introduce their own logic to the VM. The most common General Purpose VM is the Ethereum Virtual Machine (EVM). However, some Lux L1s creators might want to create a VM that utilizes another language, such as Move, instead of Solidity as its smart contract language.



One of the EVM's key features is its capability to execution of smart contracts in a deterministic and trustless manner, ensuring that the outcome of their execution is predictable and verifiable by all network participants. Developers can create decentralized applications and deploy them on the Ethereum blockchain. 

This enables a wide range of use cases including decentralized finance (DeFi), tokenization, supply chain management, and more. The EVM's flexibility, security, and compatibility have made it a fundamental component of the Ethereum ecosystem, powering a vibrant and rapidly evolving ecosystem of decentralized applications and services.


# Permissioning (/academy/avalanche-l1/avalanche-fundamentals/08-permissioning-users/01-permissioning)

---
title: Permissioning
description: Learn about different ways of permissioning your Lux L1 blockchain.
updated: 2024-06-28
authors: [usmaneth]
icon: Book
---

Permissioning your Lux L1 is an optional feature of having your own L1 blockchain. There may be many reasons why a blockchain creator may want to permission their network including these:

- **Privacy and Confidentiality:** In industries where data privacy is crucial, such as finance or healthcare, permissioned blockchains allow only authorized parties to access sensitive information. This ensures that confidential data remains protected from unauthorized access.
- **Regulatory Compliance:** Many industries are subject to strict regulatory requirements regarding data handling and security. Permissioned blockchains enable organizations to implement necessary controls to ensure compliance with regulatory standards without compromising the integrity of the blockchain.
- **Cost-efficiency:** Restricting the usage of a blockchain to certain use cases may make it more cost efficient. Blockchain operators may be able to avoid transaction fee spikes caused events such as NFT drops by imposing restrictions.

These permissions don't necessarily have to be administered by a centralized entity. There could also be a DAO in charge of determining who should be allowed to use the blockchain. 

In the upcoming lessons, you will learn about the different levels of Permissions and how they can be configured for your Lux L1.

<Quiz quizId="406"/>

# Compliance (/academy/avalanche-l1/avalanche-fundamentals/08-permissioning-users/02-compliance)

---
title: Compliance
description: Learn how you can configure compliance for your Lux L1.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

For institutions, reputational damage and legal complications could arise if their blockchain systems were inadvertently used for criminal activities.

Regulatory bodies might impose penalties on such institutions if they were to fail to create sufficient controls to prevent these activities.

Most institutions have nuanced compliance requirements. Therefore, many institutions need flexible blockchains that can meet these needs. 

## Interacting with Criminal Actors

In permissionless systems, the counterparty on a trade is unknown. If a user performs a swap on a decentralized exchange on a permissionless blockchain, such as Ethereum or the Lux LUExchange-Chain, the origin of funds that are received are mostly unknown. 

To solve this problem, each Lux L1 can restrict who can interact with the blockchain. Only a whitelist of accounts can issue transactions. One could build a blockchain where only accounts that went through a KYC process are permitted.

## Interacting with Illegal Services

An additional risk to consider is that businesses may operate within an environment prone to illicit activities, or they may inadvertently become involved in such actions. In a permissionless system, any individual has the capability to deploy any contract, regardless of its compliance with the legal framework.

Lux L1s can limit who deploys smart contracts on the blockchain. Consequently, those involved in the creation of contracts can be held accountable. This level of control reassures institutions, ensuring that all protocols they engage with are fully compliant with existing laws. 

Beyond compliance advantages, this approach helps to maintain a blockchain free from an excess of smart contracts that could otherwise congest the system.

<Quiz quizId="407"/>

# Transaction Allowlist (/academy/avalanche-l1/avalanche-fundamentals/08-permissioning-users/04-tx-allowlist)

---
title: Transaction Allowlist
description: Learn how to restrict transactions to a specific set of addresses.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

import TxAllowList from "@/content/common/evm-precompiles/transaction-allowlist.mdx";

<TxAllowList />

# Activate Transaction Allowlist (/academy/avalanche-l1/avalanche-fundamentals/08-permissioning-users/05-activate-tx-allowlist)

---
title: Activate Transaction Allowlist
description: Learn how to activate the the transaction allowlist precompile in the genesis.
updated: 2024-06-28
authors: [martineckardt]
icon: Terminal
---

Lux L1s do not implement permissioning by default. To enable permissioning, you need to
activate the transaction allowlist precompile in the genesis. This allows only approved addresses to
issue transactions on your blockchain. 

<GenesisBuilder embedded={true} initiallyExpandedSections={['permissions']} />

# Contract Deployer Allowlist (/academy/avalanche-l1/avalanche-fundamentals/08-permissioning-users/06-contract-deployer-allowlist)

---
title: Contract Deployer Allowlist
description: Learn how to restrict contract deployment to a specific set of addresses.
updated: 2024-06-28
authors: [martineckardt]
icon: BookOpen
---

import ContractDeployerAllowlist from "@/content/common/evm-precompiles/contract-deployer-allowlist.mdx";

<ContractDeployerAllowlist />

# Activate Contract Deployer Allowlist (/academy/avalanche-l1/avalanche-fundamentals/08-permissioning-users/07-activate-contract-deployer-allowlist)

---
title: Activate Contract Deployer Allowlist
description: Learn how to activate the contract deployer allowlist precompile in the genesis.
updated: 2024-06-28
authors: [martineckardt]
icon: Terminal
---

Analogous to the transaction allowlist, Lux L1s do not implement contract deployer allowlist by default. To enable permissioning, you need to activate the contract deployer allowlist precompile in the genesis. This allows only approved addresses to deploy contracts on your blockchain.

<GenesisBuilder embedded={true} initiallyExpandedSections={['permissions']} />

# Permissioning Validators (/academy/avalanche-l1/avalanche-fundamentals/09-permissioning-validators/01-permissioning-validators)

---
title: Permissioning Validators
description: Learn about different ways of permissioning your Lux L1 blockchain.
updated: 2024-06-28
authors: [usmaneth]
icon: Book
---

The ability to control a blockchain's validator set has many benefits that can significantly enhance the efficiency, security, and governance of the network. It allows blockchain participants to have greater influence over the consensus process and decision-making, leading to a more robust and adaptable ecosystem. There are two ways to structure the validator set:

- **Permissionless Validation:** Anyone can participate in the validation process and be rewarded in tokens to cover their costs for the hardware and running the validator. In Lux, we call Lux L1s that take this approach Elastic Lux L1s.
- **Permissioned Validation:** Only whitelisted validators can validate the Lux L1. A permissioned Lux L1 can be turned into a Elastic Lux L1 at any time, but not the other way round.

There are many reasons why the creators might want a permissioned validator set for their Lux
L1. You will learn in detail about the technical options in the L1 Validator Management course.

## Enterprises and Corporations: 

Large enterprises and corporations often require blockchain solutions for their internal operations or specific industry use cases. A permissioned validator set allows them to control who can participate in the network and validate transactions. This is particularly relevant in industries with strict regulatory requirements, where entities need to ensure compliance and data privacy.

## Consortiums and Industry Associations: 

Consortiums or industry associations comprising multiple organizations with shared interests can benefit from a permissioned validator set. These entities often collaborate on initiatives requiring a distributed ledger, such as supply chain management, healthcare data sharing, or financial transactions. By establishing a permissioned validator set, the consortium can ensure that trusted participants from within the consortium validate the transactions.

## Government Agencies: 

Government entities may find value in launching a blockchain with a permissioned validator set to manage critical infrastructure, public services, or regulatory processes. They can select validators from trusted institutions or stakeholders to maintain control over the network while ensuring compliance with legal and governance requirements. Examples include land registry systems, voting platforms, or identity management solutions.

## Financial Institutions: 

Banks, payment processors, and other financial institutions could be interested in a permissioned validator set for blockchain solutions related to payments, remittances, or settlement systems. These institutions often require a level of control over the network to maintain regulatory compliance, prevent money laundering, and ensure adherence to Anti-Money Laundering (AML) regulations.

<Quiz quizId="408"/>

# Private Blockchains (/academy/avalanche-l1/avalanche-fundamentals/09-permissioning-validators/02-private-blockchains)

---
title: Private Blockchains
description: Learn about different ways of permissioning your Lux L1 blockchain.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

On a public blockchain, every transaction and change to the blockchain's state is visible to all. Anyone with internet access can see the transaction data. Block Explorers are one way to conveniently access the data on a chain. Although the identities of participants are often pseudonymous, the transaction data itself is open for anyone to see.

However, there are many instances, especially in business or enterprise settings, where such transparency isn't desirable. A company might be conducting a high-value transaction that it doesn't want competitors or others in the market to see. There might also be legal or regulatory reasons for needing to keep transaction data private.

In a private, permissioned blockchain, the visibility of transactions is limited to a select group of individuals or entities. This way, sensitive data isn't exposed. Only those who have been granted the necessary permissions can view the transaction data, and these permissions can be tightly controlled and monitored by network administrators.

Further, transactions in a private blockchain can be encrypted, adding an extra layer of security. Even within the network, details about specific transactions can be hidden from certain participants, based on their level of permission. This allows for a much higher degree of confidentiality, as specific data can be revealed only on a need-to-know basis.

In summary, privacy in the context of private, permissioned blockchains isn't just about restricting who can join. It's about having granular control over who can see what data, and when. It's about providing a secure, confidential environment where sensitive transactions can occur without the risk of exposure to unintended parties.

This has made private, permissioned blockchains an attractive option for businesses and organizations dealing with sensitive data, high-value transactions, or strict confidentiality requirements.

## Private Blockchains

The data of Lux L1s, by default, are publicly available. This means that every node can sync and listen to ongoing transactions/blocks in these blockchains, even if they're not validating the network. Nodes may do this for indexing purposes or just having access to the current state of the blockchain without relying on third-parties.

Lux L1 validators can choose not to publish data from their blockchains. If a node sets `validatorOnly` to true, the node exchanges messages only with the blockchain's validators. Other peers won't be able to learn contents of this blockchain from their nodes.

<Quiz quizId="409"/>

# Intain Markets Case Study (/academy/avalanche-l1/avalanche-fundamentals/09-permissioning-validators/03-case-study-intain-markets)

---
title: Intain Markets Case Study 
description: Learn about Intain's permissioned Lux L1.
updated: 2024-06-28
authors: [usmaneth]
icon: Microscope
---

Intain operates a structured finance platform. It has **IntainMARKETS**, a marketplace for tokenized asset-backed securities built as an Lux L1.

The digital marketplace automates and integrates functions of key stakeholders in structured finance, including issuer, verification agent, underwriter, rating agency, servicer, trustee, and investor.

Rather than replacing trust intermediaries, it integrates them onto a single platform  to enable digital issuance and investment with a complete on-chain workflow. All parties work together in a transparent but private environment.

<YouTube id="gNhmxIYj9ME" />

## Permissioned Validators and Tokenomics

The **IntainMARKETS L1** also uses other ways to adhere to regulatory requirements. It has U.S-hosted infrastructure, which allows data to reside domestically, while validators chosen by network participants must also be verified U.S. entities and individuals. The Lux L1 economics are not dependent on any public token, and transaction costs are independent from those of the Lux LUExchange-Chain and other Lux L1s.

Further Readings: [Intain Launch Announcement](https://medium.com/luxlux/intain-launches-lux-subnet-to-usher-in-new-era-for-multi-trillion-dollar-securitized-877c7cc1031f)

# Introduction (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [0xstt]
icon: Book
---

As decentralized applications (dApps) expand across multiple blockchains, some Layer 1 (L1) networks lack direct support from essential services like **Chainlink VRF (Verifiable Random Functions)**. This presents a significant challenge for developers who rely on verifiable randomness for use cases such as gaming, lotteries, NFT minting, and other decentralized functions that require unbiased, unpredictable random numbers.

The challenge arises because not every L1 network has integrated with Chainlink, meaning developers on those chains are left without native access to VRF services. Without verifiable randomness, critical aspects of dApps, such as fairness and security, can be compromised.

### Why ICM is Necessary

To address this gap, **Interchain Messaging (ICM)** provides a solution by allowing L1 networks that don’t have direct Chainlink support to still access these services. Through ICM, any blockchain can request VRF outputs from a Chainlink-supported network (e.g., Testnet) and receive the results securely on their own L1. 

This cross-chain solution unlocks the ability to use Chainlink VRF on unsupported networks, bypassing the need for native integration and ensuring that dApp developers can continue building secure and fair decentralized applications.

In the following sections, we will explore how to use ICM to access Chainlink VRF services across different chains by deploying two key smart contracts: one on the Chainlink-supported network and another on the target L1.

# Understanding the Flow (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/02-understanding-the-flow)

---
title: Understanding the Flow
description: Learn how requests for random words flow across chains using ICM.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

This section explains how random words are requested and fulfilled using Chainlink VRF across two different blockchains through **Interchain Messaging (ICM)**. The entire process involves several key components: the decentralized application (DApp), `CrossChainVRFConsumer`, `CrossChainVRFWrapper`, and `TeleporterMessenger`.

Let’s walk through the flow step by step:

<Steps>
<Step>

### DApp Submits Request for Random Words

The DApp, running on an L1 without direct Chainlink support, initiates a request for verifiable randomness by interacting with the `CrossChainVRFConsumer` contract deployed on its chain.

</Step>
<Step>

### `CrossChainVRFConsumer` Sends Cross-Chain Message

Once the DApp submits the request, the `CrossChainVRFConsumer` prepares a message containing the necessary VRF request parameters (such as `keyHash`, `request confirmations`, `gas limit`, etc.). This message is sent across chains via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the Chainlink-supported network (e.g., Testnet).

</Step>
<Step>

### `TeleporterMessenger` Receives Message & Calls `CrossChainVRFWrapper`
1. On the Chainlink-supported network, the `TeleporterMessenger` receives the cross-chain message sent by the `CrossChainVRFConsumer`. It passes the message to the `CrossChainVRFWrapper`, which is authorized to handle VRF requests.
2. The `CrossChainVRFWrapper` contract, deployed on the supported network, sends the request to **Chainlink VRF** for random words, using the parameters received in the message (e.g., `subscription ID`, `callback gas limit`, etc.).

</Step>

<Step>

### Chainlink VRF Fulfills Random Words Request

1. The **Chainlink VRF** fulfills the request and returns the random words to the `CrossChainVRFWrapper` contract by invoking its callback function.
2. Once the random words are received, the `CrossChainVRFWrapper` encodes the fulfilled random words and sends them back as a cross-chain message to the `CrossChainVRFConsumer` on the original L1.

</Step>

<Step>

### `TeleporterMessenger` Returns Random Words to `CrossChainVRFConsumer`
   
The `TeleporterMessenger` on the original L1 receives the message containing the random words and passes it to the `CrossChainVRFConsumer`.

</Step>

<Step>

### `CrossChainVRFConsumer` Returns Random Words to the DApp

Finally, the `CrossChainVRFConsumer` processes the random words and sends them to the DApp that originally requested them, completing the flow.

</Step>

</Steps>

This end-to-end process demonstrates how decentralized applications on unsupported L1 networks can request verifiable randomness from Chainlink VRF, leveraging **ICM** to handle cross-chain communication.



# Orchestrating VRF Requests Over Multiple Chains (Wrapper) (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/03-orchestrating-vrf-requests)

---
title: Orchestrating VRF Requests Over Multiple Chains (Wrapper)
description: Learn how the CrossChainVRFWrapper contract on a Chainlink-supported L1 handles cross-chain requests for VRF.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFWrapper` contract plays a critical role in handling requests for randomness from an unsupported L1. It is deployed on a **Chainlink-supported network** (like Lux Testnet) and serves as the intermediary that interacts with Chainlink VRF to request random words.

Here’s how it functions as the provider for VRF services:

## Receives Cross-Chain Messages

<Steps>
<Step>

When the `CrossChainVRFConsumer` on the unsupported L1 initiates a request for randomness, it sends a cross-chain message via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the supported network.

</Step>
<Step>

The `CrossChainVRFWrapper` verifies that the request came from an authorized address. This is essential to ensure that only verified consumers can request randomness.

</Step>
<Step>

Upon receiving a valid request, the **VRFWrapper** calls **Chainlink VRF** and sends the request with the required parameters, such as the number of random words, request confirmations, and gas limits.

</Step>
<Step>

The `CrossChainVRFWrapper` keeps track of all pending requests using a mapping, associating each request ID with its destination (the L1 where the `CrossChainVRFConsumer` resides). This ensures that the random words are returned to the correct destination once fulfilled.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    // Verify that the origin sender address is authorized
    require(authorizedSubscriptions[originSenderAddress].isAuthorized, "Origin sender is not authorized");
    uint256 subscriptionId = authorizedSubscriptions[originSenderAddress].subscriptionId;
    // Verify that the subscription ID belongs to the correct owner
    (,,,, address[] memory consumers) = s_vrfCoordinator.getSubscription(subscriptionId);
    // Check wrapper contract is a consumer of the subscription
    bool isConsumer = false;
    for (uint256 i = 0; i < consumers.length; i++) {
        if (consumers[i] == address(this)) {
            isConsumer = true;
            break;
        }
    }
    require(isConsumer, "Contract is not a consumer of this subscription");
    // Decode message to get the VRF parameters
    CrossChainRequest memory vrfMessage = abi.decode(message, (CrossChainRequest));
    // Request random words
    VRFV2PlusClient.RandomWordsRequest memory req = VRFV2PlusClient.RandomWordsRequest({
        keyHash: vrfMessage.keyHash,
        subId: subscriptionId,
        requestConfirmations: vrfMessage.requestConfirmations,
        callbackGasLimit: vrfMessage.callbackGasLimit,
        numWords: vrfMessage.numWords,
        extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: vrfMessage.nativePayment}))
    });
    uint256 requestId = s_vrfCoordinator.requestRandomWords(req);
    pendingRequests[requestId] = CrossChainReceiver({
        destinationBlockchainId: originChainID,
        destinationAddress: originSenderAddress
    });
}   
```
</Accordion>
</Accordions>

## Handles Callback from Chainlink VRF

<Steps>
<Step>

When **Chainlink VRF** fulfills the randomness request, the `CrossChainVRFWrapper` receives the random words through a callback function. This ensures that the request has been successfully processed.

</Step>
<Step>

After receiving the random words, the `CrossChainVRFWrapper` encodes the result and sends it back as a cross-chain message to the `CrossChainVRFConsumer` on the unsupported L1. This is done using the `TeleporterMessenger`.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) internal override {
    require(pendingRequests[requestId].destinationAddress != address(0), "Invalid request ID");
    // Create CrossChainResponse struct
    CrossChainResponse memory crossChainResponse = CrossChainResponse({
        requestId: requestId,
        randomWords: randomWords
    });
    bytes memory encodedMessage = abi.encode(crossChainResponse);
    // Send cross chain message using ITeleporterMessenger interface
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: pendingRequests[requestId].destinationBlockchainId,
        destinationAddress: pendingRequests[requestId].destinationAddress,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
    delete pendingRequests[requestId];
}
```
</Accordion>
</Accordions>

In summary, the `CrossChainVRFWrapper` contract acts as the **bridge** between the unsupported L1 and Chainlink’s VRF services, ensuring that random words are requested, fulfilled, and delivered back across chains efficiently.


# Bringing Chainlink VRF to Unsupported L1s (Consumer) (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/04-bring-vrf-to-unsupported-l1)

---
title: Bringing Chainlink VRF to Unsupported L1s (Consumer)
description: Learn how to request VRF from an unsupported L1 using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFConsumer` contract enables DApps on an unsupported L1 to request random words from Chainlink VRF using a cross-chain communication mechanism. Since Chainlink does not natively support all blockchains, this setup allows developers to access Chainlink's VRF service even on networks that don’t have direct support.

<Steps>
<Step>

## Requesting Random Words

The `CrossChainVRFConsumer` contract sends a cross-chain message to the `CrossChainVRFWrapper` on a Chainlink-supported L1, requesting random words. This request is sent using `TeleporterMessenger`, which handles cross-chain communication.

<Accordions>
<Accordion title="Implementation">
```solidity
function requestRandomWords(
    bytes32 keyHash,
    uint16 requestConfirmations,
    uint32 callbackGasLimit,
    uint32 numWords,
    bool nativePayment,
    uint32 requiredGasLimit
) external {
    // Create CrossChainRequest struct
    CrossChainRequest memory crossChainRequest = CrossChainRequest({
        keyHash: keyHash,
        requestConfirmations: requestConfirmations,
        callbackGasLimit: callbackGasLimit,
        numWords: numWords,
        nativePayment: nativePayment
    });
    // Send Teleporter message
    bytes memory encodedMessage = abi.encode(crossChainRequest);
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: DATASOURCE_BLOCKCHAIN_ID, 
        destinationAddress: vrfRequesterContract,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: requiredGasLimit,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
}
```
</Accordion>
</Accordions>

</Step>

<Step>

## Processing the Request
Once the request is received by the `CrossChainVRFWrapper`, it interacts with the Chainlink VRF Coordinator to request the random words on behalf of the consumer on the unsupported L1.

</Step>

<Step>

## Receiving Random Words

Once Chainlink fulfills the request, the `CrossChainVRFWrapper` sends the random words back to the `CrossChainVRFConsumer` via a cross-chain message, enabling the DApp on the unsupported L1 to use them.

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(originChainID == DATASOURCE_BLOCKCHAIN_ID, "Invalid originChainID");
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    require(originSenderAddress == vrfRequesterContract, "Invalid sender");
    
    // Decode the message to get the request ID and random words
    CrossChainResponse memory response = abi.decode(message, (CrossChainResponse));
    
    // Fulfill the request by calling the internal function
    fulfillRandomWords(response.requestId, response.randomWords);
}

function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal {
    // Logic to handle the fulfillment of random words
    // Implement your custom logic here

    // Emit event for received random words
    emit RandomWordsReceived(requestId);
}
```
</Accordion>
</Accordions>

</Step>
</Steps>


# Deploy Wrapper (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/05-deploy-vrf-wrapper)

---
title: Deploy Wrapper
description: Learn how to deploy the CrossChainVRFWrapper contract to handle cross-chain VRF requests.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Once you have set up your Chainlink VRF subscription and have your LINK tokens ready, the next step is to deploy the **CrossChainVRFWrapper** contract. This contract will act as the bridge between your unsupported L1 and the Chainlink VRF network on a supported L1, enabling cross-chain requests for random words.

<Steps>
<Step>

## Prerequisites
Before deployment, make sure you have:
- A valid **Chainlink VRF Subscription ID** (see previous section for details).
- The `TeleporterMessenger` contract address on your supported L1 (e.g., Lux Testnet).
</Step>
<Step>

## Deploy the Contract
Using the `forge create` command, deploy the `CrossChainVRFWrapper` contract to the supported L1 (e.g., Lux Testnet).

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> src/CrossChainVRFWrapper.sol:CrossChainVRFWrapper
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the deployed `TeleporterMessenger` contract.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_WRAPPER=<address>
```

</Step>
<Step>

## Verify the Deployment
After deploying the contract, verify that the `CrossChainVRFWrapper` has been successfully deployed by checking its address on a block explorer.

</Step>
<Step>

## Configure Authorized Subscriptions
Once deployed, the `CrossChainVRFWrapper` contract needs to be configured with authorized subscriptions to process requests for random words.

- Call the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID.
- This ensures that only authorized addresses can request random words via the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" <CALLER_ADDRESS> <SUBSCRIPTION_ID>
```

Replace the following:

- `<CALLER_ADDRESS>`: The address that will be authorized to request random words.
- `<SUBSCRIPTION_ID>`: The ID of your Chainlink VRF subscription.
</Step>
</Steps>

# Deploy Consumer (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/06-deploy-vrf-consumer)

---
title: Deploy Consumer
description: Learn how to deploy the CrossChainVRFConsumer contract on any L1 that does not support Chainlink VRF.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Now that the `CrossChainVRFWrapper` is deployed on a Chainlink-supported L1, it’s time to deploy the `CrossChainVRFConsumer` contract on the L1 where Chainlink VRF is not supported. This contract will handle requests for random words and interact with the **TeleporterMessenger** to communicate with the supported L1.

<Steps>
<Step>
## Prerequisites
Make sure you have:
- The `TeleporterMessenger` contract address on the unsupported L1.
- The deployed `CrossChainVRFWrapper` on the supported L1. `($VRF_WRAPPER)`
</Step>
<Step>
## Deploy the Contract
Use the following command to deploy the `CrossChainVRFConsumer` contract on your unsupported L1.

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> $VRF_WRAPPER src/CrossChainVRFConsumer.sol:CrossChainVRFConsumer
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the `TeleporterMessenger` contract on your unsupported L1.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_CONSUMER=<address>
```
</Step>
<Step>
## Verify the Deployment
Once the `CrossChainVRFConsumer` contract is deployed, verify the contract’s address and confirm that it has been successfully deployed on your L1 using a block explorer.
</Step>
</Steps>

# Create Chainlink VRF Subscription (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/07-create-vrf-subscription)

---
title: Create Chainlink VRF Subscription
description: Learn how to create a Chainlink VRF subscription to enable cross-chain randomness requests.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Before you can request random words using Chainlink VRF, you need to set up a **Chainlink VRF subscription**. This subscription allows you to fund requests for randomness and manage the list of consumers that are authorized to use the VRF service.

<Steps>
<Step>

## Access Chainlink's VRF Subscription Manager

To create a subscription, go to the Chainlink VRF Subscription Manager on the network where you plan to request VRF (e.g., Lux Testnet). You can access the manager here: [VRF | Subscription Management for Testnet](https://vrf.chain.link/testnet).
![](/common-images/chainlink-vrf/visit-subscription-management.png)

</Step>
<Step>

## Create a New Subscription

Once on the subscription manager, create a new subscription. The subscription will have a unique ID, which you'll need to reference in your `CrossChainVRFWrapper` contract. This ID is used to track your random word requests and the balance associated with them.
![](/common-images/chainlink-vrf/create-subscription.png)

</Step>
<Step>

## Fund the Subscription

After creating the subscription, you need to fund it with LINK tokens. These tokens are used to pay for the randomness requests made through Chainlink VRF. Make sure your subscription has enough funds to cover your requests.
You can get testnet LINK tokens from the Testnet Faucet: [Chainlink Faucet for Testnet](https://faucets.chain.link/testnet)

![](/common-images/chainlink-vrf/faucet.png)

![](/common-images/chainlink-vrf/add-funds.png)

</Step>
<Step>

## Add Consumers

After funding your subscription, add the `CrossChainVRFWrapper` contract `($VRF_WRAPPER)` as a consumer. This step authorizes the contract to make randomness requests on behalf of your subscription. You can add other consumers, such as other contracts or addresses, depending on your use case.
![](/common-images/chainlink-vrf/add-consumer.png)

</Step>
<Step>

## Save Subscription ID

After completing these steps, save your subscription ID. You will need this ID when configuring the `CrossChainVRFWrapper` contract to request random words.

```bash
export VRF_SUBSCRIPTION_ID=<subscription_id>
```

</Step>
</Steps>

---


# Request Random Words (/academy/avalanche-l1/icm-chainlink/01-access-chainlink-vrf-services/08-request-random-words)

---
title: Request Random Words
description: Learn how to request random words using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will learn how to request random words from Chainlink VRF using both the `CrossChainVRFConsumer` contracts.

<Steps>
<Step>

## Authorize an Address to Request Random Words

After deploying the `CrossChainVRFWrapper` contract, the first step is to authorize an address to make requests for random words. This ensures that only specific addresses linked to a subscription can request VRF.

- Use the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID. This step allows the address to make random word requests through the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" $VRF_CONSUMER $VRF_SUBSCRIPTION_ID
```

</Step>
<Step>

## Request Random Words from `CrossChainVRFConsumer`

Once the address is authorized, the next step is to send a request for random words from the `CrossChainVRFConsumer` contract on the unsupported L1. This request is then sent to the `CrossChainVRFWrapper` via a cross-chain message.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_CONSUMER "requestRandomWords(bytes32 keyHash, uint16 requestConfirmations, uint32 callbackGasLimit, uint32 numWords, bool nativePayment, uint32 requiredGasLimit)" <KEY_HASH> <CONFIRMATIONS> <GAS_LIMIT> <NUM_WORDS> <NATIVE_PAYMENT> <REQUIRED_GAS_LIMIT>
```

Replace the placeholders with:

- `<KEY_HASH>`: The VRF key hash used for random word generation.
- `<CONFIRMATIONS>`: Number of confirmations required for the request.
- `<GAS_LIMIT>`: The gas limit for the VRF callback function.
- `<NUM_WORDS>`: The number of random words requested.
- `<NATIVE_PAYMENT>`: Indicates whether the payment will be made in the native token.
- `<REQUIRED_GAS_LIMIT>`: The gas limit required for the cross-chain message to be processed.

</Step>
</Steps>

# Introduction (/academy/avalanche-l1/icm-chainlink/02-access-chainlink-functions/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [Andrea]
icon: Book
---

TBD

# Introduction (/academy/avalanche-l1/icm-chainlink/04-ccip-icm/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [Andrea]
icon: Book
---

TBD

# Introduction (/academy/avalanche-l1/icm-chainlink/03-access-chainlink-automation/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [Andrea]
icon: Book
---

TBD

# Lux Interchain Token Transfer (/academy/avalanche-l1/erc20-bridge/02-avalanche-interchain-token-transfer/01-avalanche-interchain-token-transfer)

---
title: Lux Interchain Token Transfer
description: Learn how to transfer assets between Lux L1s
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

The Lux Interchain Token Transfer is an application that allows users to transfer tokens between Lux L1s. The bridge is a set of smart contracts that are deployed across multiple Lux L1s, and leverages [Interchain Messaging](https://github.com/luxfi/teleporter) for cross-chain communication.

# What you will learn

In this chapter you will learn:

- **Bridge Design:** How the bridge is designed on a high level.
- **File Structure:** The structure of the bridge contracts and their dependencies.
- **Token Home:** What the token home is and how it works.
- **Token Remote:** What the token remote is and how it works.


# Interchain Token Transfer Design (/academy/avalanche-l1/erc20-bridge/02-avalanche-interchain-token-transfer/02-bridge-design)

---
title: Interchain Token Transfer Design
description: Get familiar with the ICTT design
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Each token transferrer instance consists of one "home" contract and at least one but possibly many "remote" contracts. Each home contract instance manages one asset to be transferred out to `TokenRemote` instances. The home contract lives on the Lux L1 where the asset to be transferred exists.

A transfer involves locking the asset as collateral on the home Lux L1 and minting a representation of the asset on the remote Lux L1. The remote contracts, each with a single specified home contract, live on other Lux L1s that want to import the asset transferred by their specified home.

The token transferrers are designed to be permissionless: anyone can register compatible `TokenRemote` instances to transfer tokens from the `TokenHome` instance to that new `TokenRemote` instance.

The home contract keeps track of token balances transferred to each `TokenRemote` instance and handles returning the original tokens to the user when assets are transferred back to the `TokenHome` instance.

`TokenRemote` instances are registered with their home contract via a Interchain Messaging message upon creation.

Home contract instances specify the asset to be transferred as either an ERC20 token or the native token, and they allow for transferring the token to any registered `TokenRemote` instances. The token representation on the remote chain can also either be an ERC20 or native token, allowing users to have any combination of ERC20 and native tokens between home and remote chains:

- `ERC20` -> `ERC20`
- `ERC20` -> `Native`
- `Native` -> `ERC20`
- `Native` -> `Native`

The remote tokens are designed to have compatibility with the token transferrer on the home chain by default, and they allow custom logic to be implemented in addition. For example, developers can inherit and extend the `ERC20TokenRemote` contract to add additional functionality, such as a custom minting, burning, or transfer logic.

<Quiz quizId="125" />


# File Structure (/academy/avalanche-l1/erc20-bridge/02-avalanche-interchain-token-transfer/03-file-structure)

---
title: File Structure
description: Understand the components of the ICTT structure
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Contract Structure

The ERC20 and native token transferrers built on top of Interchain Messaging are composed of interfaces and abstract contracts that make them extendable to new implementations in the future.

### `ITokenTransferrer`

Interface that defines the events token transfer contract implementations must emit. Also defines the message types and formats of messages between all implementations.

### `IERC20TokenTransferrer` and `INativeTokenTransferrer`

Interfaces that define the external functions for interacting with token transfer contract implementations of each type. ERC20 and native token transferrer interfaces vary from each other in that the native token transferrer functions are `payable` and do not take an explicit amount parameter (it is implied by `msg.value`), while the ERC20 token transferrer functions are not `payable` and require the explicit amount parameter. Otherwise, they include the same functions.

# Token Home (/academy/avalanche-l1/erc20-bridge/02-avalanche-interchain-token-transfer/04-token-home)

---
title: Token Home
description: Learn about the Token Home, the asset origin component of the ICTT
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## `TokenHome`

An abstract implementation of `ITokenTransferrer` for a token transfer contract on the "home" chain with the asset to be transferred. Each `TokenHome` instance supports transferring exactly one token type (ERC20 or native) on its chain to arbitrarily many "remote" instances on other chains.

It handles locking tokens to be sent to `TokenRemote` instances, as well as receiving token transfer messages to either redeem tokens it holds as collateral (i.e. unlock) or route them to other `TokenRemote` instances (i.e. "multi-hop").

In the case of a multi-hop transfer, the `TokenHome` already has the collateral locked from when the tokens were originally transferred to the first `TokenRemote` instance, so it simply updates the accounting of the transferred balances to each respective `TokenRemote` instance.

Remote contracts must first be registered with a `TokenHome` instance before the home contract will allow for sending tokens to them. This is to prevent tokens from being transferred to invalid remote addresses.

Anyone is able to deploy and register remote contracts, which may have been modified from this repository. It is the responsibility of the users of the home contract to independently evaluate each remote for its security and correctness.

### `ERC20TokenHome`

A concrete implementation of `TokenHome` and `IERC20TokenTransferrer` that handles the locking and releasing of an ERC20 token.

### `NativeTokenHome`

A concrete implementation of `TokenHome` and `INativeTokenTransferrer` that handles the locking and release of the native EVM asset.


# Token Remote (/academy/avalanche-l1/erc20-bridge/02-avalanche-interchain-token-transfer/05-token-remote)

---
title: Token Remote
description: Learn about the Token Remote, the asset destination component of the ICTT
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## `TokenRemote`

An abstract implementation of `ITokenTransferrer` for a token transfer contract on a "remote" chain that receives transferred assets from a specific `TokenHome` instance. Each `TokenRemote` instance has a single `TokenHome` instance that it receives token transfers from to mint tokens. It also handles sending messages (and correspondingly burning tokens) to route tokens back to other chains (either its `TokenHome`, or other `TokenRemote` instances).

Once deployed, a `TokenRemote` instance must be registered with its specified `TokenHome` contract. This is done by calling `registerWithHome` on the remote contract, which will send a Interchain Messaging message to the home contract with the information to register.

All messages sent by `TokenRemote` instances are sent to the specified `TokenHome` contract, whether they are to redeem the collateral from the `TokenHome` instance or route the tokens to another `TokenRemote` instance.

Routing tokens from one `TokenRemote` instance to another is referred to as a "multi-hop", where the tokens are first sent back to their `TokenHome` contract to update its accounting, and then automatically routed on to their intended destination `TokenRemote` instance.

TokenRemote contracts allow for scaling token amounts, which should be used when the remote asset has a higher or lower denomination than the home asset, such as allowing for a ERC20 home asset with a denomination of 6 to be used as the native EVM asset on a remote chain (with a denomination of 18).

### `ERC20TokenRemote`

A concrete implementation of `TokenRemote`, `IERC20TokenTransferrer`, and `IERC20` that handles the minting and burning of an ERC20 asset. Note that the `ERC20TokenRemote` contract is an ERC20 implementation itself, which is why it takes the `tokenName`, `tokenSymbol`, and `tokenDecimals` in its constructor.

All of the ERC20 interface implementations are inherited from the standard OpenZeppelin ERC20 implementation and can be overridden in other implementations if desired.

### `NativeTokenRemote`

A concrete implementation of `TokenRemote`, `INativeTokenTransferrer`, and `IWrappedNativeToken` that handles the minting and burning of the native EVM asset on its chain using the native minter precompile.

Deployments of this contract must be permitted to mint native coins in the chain's configuration. Note that the `NativeTokenRemote` is also an implementation of `IWrappedNativeToken` itself, which is why the `nativeAssetSymbol` must be provided in its constructor.

`NativeTokenRemote` instances always have a denomination of 18, which is the denomination of the native asset of EVM chains. We will cover Native Token Remote in depth later in the course.

# Token Bridging (/academy/avalanche-l1/erc20-bridge/01-token-bridging/01-token-bridging)

---
title: Token Bridging
description: Learn about asset transfer between chains
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

Asset bridging is a crucial concept in blockchain interoperability, enabling assets to be transferred across different blockchain networks. This process is essential for creating seamless experiences in multi-chain ecosystems.

## What You Will Learn

In this section, you will go through the following topics:

- **Bridging assets:** you will understand why bridging assets is important.
- **Bridge safety:** learn about the most common hacks in bridges and how to prevent them.


# Bridge Architecture (/academy/avalanche-l1/erc20-bridge/01-token-bridging/02-bridge-architecture)

---
title: Bridge Architecture
description: Get familiar with different bridge mechanisms
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Asset bridging refers to the mechanism that allows assets, such as cryptocurrencies or tokens, to move from one blockchain to another. This is particularly important in ecosystems where multiple blockchains are used for different purposes, and users want to leverage assets across these chains. Bridging effectively extends the usability of assets beyond their native blockchain, facilitating greater liquidity and integration across various platforms.

## Bridge Mechanisms

### Lock & Mint

Locking: The asset is locked in a smart contract on the source blockchain. For example, if you want to bridge LUX from Lux's C-chain to Ethereum, you would lock your LUX in a smart contract on Lux.
Minting: Simultaneously, some event notifies Ethereum that an equivalent amount of a wrapped token (e.g., Wrapped LUX) must be minted on the target blockchain and sent to the user’s address.

### Burn & Mint

Burning: When transferring assets back to the source blockchain, the wrapped tokens are burned or destroyed on the target blockchain.
Releasing: The original assets are then released from the smart contract on the source blockchain back to the user's address.

### Custodians

Some bridges use a custodian or a centralized party to manage the assets. This party locks the asset on one blockchain and releases it on another, relying on trust and security measures.

### Cross-Chain Communication

Advanced bridges such as Lux Interchain Token Transfer utilize native cross-chain communication protocols to facilitate transactions between blockchains without requiring intermediaries. These protocols ensure that the asset's state and ownership are synchronized across different chains.

## Why Bridging

- Enhanced Liquidity: Bridging increases the liquidity of assets by allowing them to be used across different DeFi platforms and blockchain networks. This enhances trading opportunities and financial activities.
- Interoperability: It fosters interoperability between different blockchains, enabling users to access a broader range of services and applications.
- Flexibility: Users can move assets to chains with lower fees, faster transaction times, or better functionalities, optimizing their experience and strategies.

<Quiz quizId="123" />


# Use a Demo Bridge (/academy/avalanche-l1/erc20-bridge/01-token-bridging/03-use-a-demo-bridge)

---
title: Use a Demo Bridge
description: Interact with the ohmywarp bridge
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

This guide will walk you through the process of using a bridge between 2 Lux blockchains, providing a step-by-step approach to ensure a smooth and secure experience.

Go to [ohmywarp.com](https://ohmywarp.com) and connect any web3 [wallet](https://core.app). Make sure your wallet has at least some LUX on the Testnet Testnet. 

**Getting testnet LUX:**
- **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet LUX automatically
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `lux-academy`

Mint some `TLP` token on `LUExchange-Chain` in the Mint tab. This is an ERC20 deployed on Testnet's C-chain.
Finally bridge some `TLP` to `Dispatch`. You can confirm the transfer in the Mint tab.


# Bridge Hacks (/academy/avalanche-l1/erc20-bridge/01-token-bridging/04-bridge-hacks)

---
title: Bridge Hacks
description: Learn about the most common bridge hacks.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## What are Bridge Hacks?

Asset bridges are vital for blockchain interoperability but have been the target of significant security breaches. The complexities of bridging assets between different blockchains can create vulnerabilities that malicious actors exploit. Here’s an overview of some of the most common types of bridge hacks and security issues:

### Smart Contract Exploits

Smart contract exploits involve vulnerabilities in the bridge's code that can be exploited by attackers to steal assets. Common issues include:

**Reentrancy Attacks**: Exploiting a contract’s ability to call itself, allowing attackers to repeatedly withdraw funds before the contract’s state is updated. Example: The DAO hack in 2016 utilized reentrancy to drain millions of dollars of ETH from a smart contract.
  
**Arithmetic Errors**: Bugs related to integer overflows or underflows that can lead to unintended behavior. Example: In 2020, the **Value DeFi** exploit used an arithmetic bug to drain $6 million from the protocol.

**Logic Flaws**: Errors in the contract's logic that can be exploited to bypass security controls. Example: In the case of bZx exploit, an attacker exploited a logic flaw to manipulate the price of assets and steal funds.

### Centralized Bridge Attacks

Centralized bridges rely on a single custodian or entity to manage the assets. If the custodian is compromised, it can lead to:

1. **Theft of Assets**: Direct theft from the custodian's reserves if their security is breached. Example: The Poly Network hack in 2021 involved a vulnerability that allowed attackers to exploit the bridge's central control mechanisms and steal over $600 million. Although much of the stolen funds were later returned, it highlighted significant risks in centralized bridges.

2. **Mismanagement or Fraud**: The custodian could mismanage funds or engage in fraudulent activities. Example: Various cases of mismanagement or fraud in smaller, less established bridges where the custodian's integrity is in question.

### Governance Attacks

Governance attacks target the mechanisms by which decisions are made in decentralized bridges:

**Vote Manipulation**: Attacking the governance process to make changes that benefit the attacker. Example: In some DeFi protocols, attackers have manipulated governance votes to gain control or access to assets.

**51% Attacks**: Gaining control over a majority of the governance or network nodes to disrupt or exploit the bridge. Example: While more common in blockchains, similar attacks can occur in decentralized bridges with weak governance structures.

### Cross-Chain Communication Vulnerabilities

Cross-chain communication vulnerabilities involve weaknesses in the protocols or mechanisms that facilitate communication between different blockchains:

**Data Manipulation**: Exploiting the data transmitted between chains to falsify transactions or asset states. Example: In 2022, the Wormhole bridge was exploited due to a vulnerability in its data verification process, leading to a loss of over $320 million.

**Consensus Issues**: Problems with how different chains agree on the state of assets or transactions can lead to discrepancies and exploitation. Example: Misalignment between chains can lead to double-spending or other issues if not properly managed.

### Phishing and Social Engineering

Phishing and social engineering attacks target users or administrators rather than the bridge’s technical infrastructure:

**Phishing**: Attacking users to steal their private keys or credentials to access funds. Example: Users may be tricked into entering their private keys on fraudulent websites pretending to be bridge interfaces.

**Social Engineering**: Manipulating individuals involved in the bridge’s operations to gain unauthorized access or influence. Example: Administrators may be tricked into giving away critical access or credentials.

## Mitigation Strategies

1. **Audits and Code Reviews**: Regularly audit smart contracts and bridge code to identify and fix vulnerabilities before they can be exploited.

2. **Security Best Practices**: Implement security best practices, including proper error handling, using well-tested libraries, and following coding standards.

3. **Decentralization**: Where possible, use decentralized bridging solutions to reduce the risk associated with centralized custodians.

4. **Governance Safeguards**: Strengthen governance mechanisms and ensure a robust process for decision-making and voting.

5. **User Education**: Educate users about phishing and social engineering threats to reduce the risk of these types of attacks.

6. **Insurance and Compensation**: Use insurance mechanisms or compensation funds to mitigate the impact of potential losses from breaches.

By understanding and addressing these common bridge hacks, developers and users can better protect their assets and improve the overall security of cross-chain bridging solutions.

<Quiz quizId="124" />


# Overview of Multi-hop Transfers (/academy/avalanche-l1/erc20-bridge/04-tokens-on-multiple-chains/01-tokens-on-multiple-chain)

---
title: Overview of Multi-hop Transfers
description: Learn about how ICTT supports multi-hop transfers between spoke chains.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---

The token bridge also supports "multi-hop" transfers, where tokens can be transferred between remote chains via the home chain. To illustrate, consider two remotes _R<sub>a</sub>_ and _R<sub>b</sub>_ that are both connected to the same home _H_. A multi-hop transfer from _R<sub>a</sub>_ to _R<sub>b</sub>_ first gets routed from _R<sub>a</sub>_ to _H_, where the remote balances are updated, and then _H_ automatically routes the transfer on to _R<sub>b</sub>_.

In this example, our _R<sub>a</sub>_ chain is `Echo`, our _R<sub>b</sub>_ chain is `Dispatch`, and _H_ chain is the Lux LUExchange-Chain.

### What we will do

1. Deploy a new `ERC20TokenRemote` contract to `Dispatch`
2. Register the new `ERC20TokenRemote` contract with the `TokenHome` contract on the Lux LUExchange-Chain
3. Perform a multi-hop transfer of a token from `Echo` to `Dispatch`, with a 'hop' through the Lux LUExchange-Chain


<Quiz quizId="127"/>

# Deploy Token Remote for Multi-hop (/academy/avalanche-l1/erc20-bridge/04-tokens-on-multiple-chains/02-deploy-token-remote)

---
title: Deploy Token Remote for Multi-hop
description: Deploy and configure the ERC20TokenRemote contract on the second blockchain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

To ensure the wrapped token is bridged into the destination chain (in this case, LUExchange-Chain) you'll need to deploy a _remote_ contract that implements the `IERC20Bridge` interface, as well as inheriting the properties of `TeleporterTokenRemote`. In order for the bridged tokens to have all the normal functionality of a locally deployed ERC20 token, this remote contract must also inherit the properties of a standard `ERC20` contract.

<Steps>
<Step>
### Get Test DIS

Before deploying the remote contract, ensure you have some test tokens on Dispatch:

- **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet tokens automatically on Dispatch
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/?subnet=dispatch&token=dispatch) to claim DIS tokens

</Step>

<Step>
### Deploy the Remote Contract

Now we'll deploy the ERC20TokenRemote contract to the Echo chain. Use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={779672}>
    <DeployERC20TokenRemote />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the Remote Contract Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>

</Steps>


# Register Remote Bridge (/academy/avalanche-l1/erc20-bridge/04-tokens-on-multiple-chains/03-register-remote)

---
title: Register Remote Bridge
description: Register the remote bridge with the home bridge
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

After deploying both the home and remote bridge contracts, you need to register the remote bridge with the home bridge. This registration process informs the Home Bridge about your destination blockchain and bridge settings.

<Steps>
<Step>
### Register Remote Bridge

To register your remote bridge with the home bridge, use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/07-tokens-on-multiple-chains/02-deploy-token-remote))
4. Have enough test DIS for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={779672}>
    <RegisterWithHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Verify Registration

After registration, you can verify the process was successful by looking for the registration event in the transaction logs. You can find the registration confirmation in the toolbox.

<Callout title="Note" type="info">
The registration process is a one-time setup that establishes the connection between your home and remote bridges. Once completed, you can proceed with token transfers.
</Callout>
</Step>
</Steps> 

# Multi-hop Transfer (/academy/avalanche-l1/erc20-bridge/04-tokens-on-multiple-chains/04-multihop)

---
title: Multi-hop Transfer
description: Perform the multi-hop transfer of `TOK` from `myblockchain` to `myblockchain2`, with a 'hop' through the Lux LUExchange-Chain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Transfer the Token Cross-chain

Now that all the bridge contracts have been deployed and registered, you can transfer tokens between chains using our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote))
4. Registered your remote bridge with the home bridge (from [Register Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/05-register-remote))
5. Have enough ERC-20 tokens on the _R<sub>a</sub>_ chain: `Echo` (you can transfer tokens from the _H_ chain to the _R<sub>a</sub>_ chain first) (from [Transfer Tokens](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/06-transfer-tokens))
6. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <TestSend />
</ToolboxMdxWrapper>

</Step>

<Step>

### Verify the Transfer

After initiating the transfer, you can verify it was successful by:

1. Checking the transaction status in the toolbox
2. Checking the transaction status in Core Wallet
3. Viewing the transaction details on the [Testnet Explorer](https://testnet.snowtrace.io)
4. Checking your token balance in Core Wallet on the destination chain

<Callout title="Note" type="info">
The transfer process may take a few moments to complete as it involves cross-chain communication. You can track the progress through the transaction hash.
</Callout>
</Step>
</Steps> 


# ERC-20 to ERC-20 Bridge (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/01-erc-20-to-erc-20-bridge)

---
title: ERC-20 to ERC-20 Bridge
description: Transfer ERC-20 tokens between Lux L1s
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import Link from 'next/link';
import { buttonVariants } from '@/components/ui/button.tsx'

## Transfer an ERC-20 Token &rarr; Echo as an ERC-20 Token

This chapter will show you how to send an ERC-20 Token from LUExchange-Chain to Echo using Interchain Messaging and Toolbox. This guide is conducted on the Testnet testnet, where we'll bridge tokens from LUExchange-Chain to Echo.

**All Lux Interchain Token Transfer contracts and interfaces implemented in this chapter implementation are maintained in the [`lux-interchain-token-transfer`](https://github.com/luxfi/lux-interchain-token-transfer/tree/main/contracts/src) repository.**

Deep dives on each template interface can be found [here](https://github.com/luxfi/lux-interchain-token-transfer/blob/main/contracts/README.md).

_Disclaimer: The lux-interchain-token-transfer contracts used in this tutorial are under active development and are not yet intended for production deployments. Use at your own risk._

## What we will do

1. Deploy an ERC-20 Contract on LUExchange-Chain
2. Deploy the Interchain Token Transferer Contracts on LUExchange-Chain and Echo
3. Register Remote Token contract with the Home Transferer contract
4. Add Collateral and Start Sending Tokens






# Deploy an ERC-20 (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/02-deploy-erc-20-token)

---
title: Deploy an ERC-20 
description: Deploy the asset to transfer
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Deploy an ERC-20 Token

We've already deployed an ERC-20 token in the [Transfer an ERC-20 Token](/academy/interchain-token-transfer/03-tokens/08-transfer-an-erc-20-token) section. If you've completed that step, you can use the same token for this bridge.

If you haven't deployed a token yet, make sure you're connected to the Testnet testnet since we're covering this guide from Testnet to Echo. You can deploy the original ERC-20 token below:

<ToolboxMdxWrapper>
    <DeployExampleERC20 enforceChainId={43113} />
</ToolboxMdxWrapper>

<Callout>
Make sure to save the deployed token address as you'll need it for the next steps. You can find it in the deployment confirmation or by checking your Core Wallet's token list.
</Callout>

</Step>

<Step>
### Add Token to Core Wallet

If you haven't already added the token to your Core Wallet:

1. Go to the Tokens tab
2. Click "Manage"
3. Click "+ Add Custom Token"
4. Enter the token contract address
5. The token symbol and decimals should be automatically detected
6. Click "Add Token"

<Callout>
Remember that you need to be connected to the Testnet testnet to see and interact with your token.
</Callout>
</Step>

<Step>
### Verify Token Balance

To verify your token balance:

1. In Core Wallet, select your token from the token list
2. The balance should be displayed
3. You can also check the token balance on the [Testnet Explorer](https://testnet.snowtrace.io) by entering your address

<Callout>
If you deployed the example token, you should see a balance of 10,000,000,000 tokens in your wallet.
</Callout>
</Step>
</Steps>


# Deploy a Home Contract (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/03-deploy-home)

---
title: Deploy a Home Contract
description: Deploy the Token Home on C-chain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

We will deploy two Lux Interchain Token Transfer contracts. One on the source chain (which is C-chain in our case) and another on the destination chain (Echo in our case).

<Steps>
<Step>
### Deploy ERC20Home Contract

Since we're covering an ERC20 > ERC20 bridge, make sure to set the Transferrer type to "ERC20" and input the ERC20 token address you previously deployed in the token address field. Then deploy the ERC20Home contract on the Testnet testnet using our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Have enough test LUX for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <DeployTokenHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the ERC-20 Home Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>
</Steps>


# Deploy a Remote Contract (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/04-deploy-remote)

---
title: Deploy a Remote Contract
description: Deploy the Token Remote on your own blockchain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

To ensure the wrapped token is bridged into the destination chain (in this case, LUExchange-Chain) you'll need to deploy a _remote_ contract that implements the `IERC20Bridge` interface, as well as inheriting the properties of `TeleporterTokenRemote`. In order for the bridged tokens to have all the normal functionality of a locally deployed ERC20 token, this remote contract must also inherit the properties of a standard `ERC20` contract.

<Steps>
<Step>
### Get Test ECH

Before deploying the remote contract, ensure you have some test tokens on Echo:

- **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet tokens automatically on Echo
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/?subnet=echo&token=echo) to claim tokens

</Step>

<Step>
### Deploy the Remote Contract

Now we'll deploy the ERC20TokenRemote contract to the Echo chain. Use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <DeployERC20TokenRemote />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the Remote Contract Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>

</Steps>


# Register Remote Bridge (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/05-register-remote)

---
title: Register Remote Bridge
description: Register the remote bridge with the home bridge
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

After deploying both the home and remote bridge contracts, you need to register the remote bridge with the home bridge. This registration process informs the Home Bridge about your destination blockchain and bridge settings.

<Steps>
<Step>
### Register Remote Bridge

To register your remote bridge with the home bridge, use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote))
4. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <RegisterWithHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Verify Registration

After registration, you can verify the process was successful by looking for the registration event in the transaction logs. You can find the registration confirmation in the toolbox.

<Callout title="Note" type="info">
The registration process is a one-time setup that establishes the connection between your home and remote bridges. Once completed, you can proceed with token transfers.
</Callout>
</Step>
</Steps> 

# Transfer Tokens (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/06-transfer-tokens)

---
title: Transfer Tokens
description: Transfer an ERC20 from C-chain to your own blockchain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Transfer the Token Cross-chain

Now that all the bridge contracts have been deployed and registered, you can transfer tokens between chains using our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote))
4. Registered your remote bridge with the home bridge (from [Register Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/05-register-remote))
5. Have enough test LUX for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <TestSend />
</ToolboxMdxWrapper>

</Step>

<Step>

### Verify the Transfer

After initiating the transfer, you can verify it was successful by:

1. Checking the transaction status in the toolbox
2. Checking the transaction status in Core Wallet
3. Viewing the transaction details on the [Testnet Explorer](https://testnet.snowtrace.io)
4. Checking your token balance in Core Wallet on the destination chain

<Callout title="Note" type="info">
The transfer process may take a few moments to complete as it involves cross-chain communication. You can track the progress through the transaction hash.
</Callout>
</Step>
</Steps> 


# Integrate ICTT with Core (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/07-avacloud-and-core-bridge)

---
title:  Integrate ICTT with Core
description: Learn how to integrate ICTT bridges into the Core Bridge through AvaCloud.
updated: 2024-05-31
icon: Book
authors: [owenwahlgren]
---

## Integrate Interchain Token Transfers (ICTT) Into Core

ICTT bridges deployed through [**AvaCloud**](https://avacloud.io/) will automatically integrate into the [**Core Bridge**](https://core.app/en/bridge). This ensures that any bridges created through AvaCloud are available immediately and do not need extra review.

However, **ICTT bridges** deployed outside of AvaCloud (by third-party developers or other methods) will need to be submitted for manual review. Developers will need to provide:

1. **Token Bridge Contract Address(es)**: The bridge contract(s) on the L1.
2. **Layer 1 Information**: Name and other key details of the associated L1 blockchain.

The Core team will review this info to ensure the bridge meets security and compliance standards. This guarantees network reliability while allowing more flexibility.

### [Community Submission Form](https://forms.gle/jdcKcYWu26CsY6jRA)

<iframe src="https://forms.gle/jdcKcYWu26CsY6jRA" className="w-full h-96" />

### AvaCloud Relayer Service and Bridge Integration

When deploying ICTT bridges, the **meta-transaction relayer** plays a key role in enhancing the user experience. Once the bridge is set up, the relayer ensures users can transfer assets between chains without worrying about gas fees. 

By using the **relayer service**, gas costs for transactions made through the bridge are handled on behalf of users, streamlining cross-chain operations. The relayer, funded with the L1's gas token, forwards transactions signed by users to the destination chain, ensuring the asset bridge between chains works smoothly without requiring users to hold or manage gas tokens.

This integration is especially useful for bridging clients who are not familiar with Web3, as it removes the need for them to manage gas tokens during the cross-chain asset transfer process. Once set up, the relayer infrastructure includes:

1. A **relaying node** to handle transactions.
2. A **relayer wallet** funded with gas tokens from the L1.
3. A **trusted forwarder contract** that securely relays transactions.

With this setup, users benefit from a gas-free experience when interacting with your bridge, making cross-chain transfers and other actions seamless and accessible.


# Deploy Your Own ICTT Frontend (/academy/avalanche-l1/erc20-bridge/03-erc-20-to-erc-20-bridge/08-deploy-your-own-frontend)

---
title:  Deploy Your Own ICTT Frontend
description: Set up the BuilderKit for deploying your own Interchain Token Transfer (ICTT) frontend with custom tokens and chains.
updated: 2024-05-31
icon: Terminal
authors: [0xstt]
---
import Link from 'next/link';
import { cn } from '@/utils/cn';
import { buttonVariants } from '@/components/ui/button.tsx'
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you’ll learn how to deploy your own **ICTT frontend** using the BuilderKit and pre-configured tokens and chains. Follow these steps to quickly set up and test your own ICTT frontends with Lux L1s.

---

<Steps>

<Step>
### Open the AvaCloudSDK Starter Kit Github Repository

Start by opening the repository on Github.

<Link
    href="https://github.com/luxfi/lux-starter-kit"
    className={cn(
    buttonVariants({ variant: 'default', className: 'mt-4' }),
    )}
    target='_blank'
>Open Lux Starter Kit</Link>
</Step>

<Step>
### Open the Dev Container and Navigate to the Chain Definitions

- Open the repository in a Github Codespace or Visual Studio Code.
- Navigate to the `web-apps/src/app/chains/definitions` folder.

In this folder, you’ll find separate files for each chain configuration. For example, `echo.ts` contains the definition for the **Echo L1** chain:

```ts
import { defineChain } from "viem";

export const echo = defineChain({
    id: 173750,
    name: 'Echo L1',
    network: 'echo',
    nativeCurrency: {
        decimals: 18,
        name: 'Ech',
        symbol: 'ECH',
    },
    rpcUrls: {
        default: {
            http: ['https://subnets.lux.network/echo/testnet/rpc']
        },
    },
    blockExplorers: {
        default: { name: 'Explorer', url: 'https://subnets-test.lux.network/echo' },
    },
    iconUrl: "/chains/logo/173750.png"
});
```

### How to Configure Your Own Blockchain

To configure your custom blockchain (e.g., `myblockchain`):

1. Copy the existing echo.ts file and rename it to myblockchain.ts.
2. Update the fields to match your blockchain’s specific details, such as chain ID, network name, and native currency.
3. Save the file in the chains/definitions folder. 

</Step>
<Step> 
### Import Your Chains

- Navigate to the `web-apps/src/app` folder.

Once you're inside the **APP** folder, open the `constants.tsx` file to begin configuring the tokens and chains.

```tsx
import { myblockchain } from './chains/definitions';
```

**Add Imported Chains to Array**

After importing the chains, add them into the chains array:

```tsx
export const CHAINS = [lux, luxTestnet, echo, dispatch, myblockchain];
```

This array will hold the configuration of all the chains that will interact with your ICTT frontend.
</Step>
<Step> 
### Add Your Chain, and Configure Tokens

Next, configure your tokens. Here’s an example token configuration:

```tsx
export const TOKENS = [
  {
    address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
    name: "TOK",
    symbol: "TOK",
    decimals: 18,
    chain_id: 43113,
    supports_ictt: true,
    transferer: "0xD63c60859e6648b20c38092cCceb92c5751E32fF",
    mirrors: [
      {
        address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
        transferer: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
        chain_id: 173750,
        decimals: 18
      }
    ]
  },
  {
    address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
    name: "TOK.e",
    symbol: "TOK.e",
    decimals: 18,
    chain_id: 173750,
    supports_ictt: true,
    is_transferer: true,
    mirrors: [
      {
        home: true,
        address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
        transferer: "0xD63c60859e6648b20c38092cCceb92c5751E32fF",
        chain_id: 43113,
        decimals: 18
      }
    ]
  }
];
```

<Accordions>
<Accordion title="What Are `is_transferer` and `home` Flags?">
- **`is_transferer` Flag**: This flag is used to indicate if the token on the current chain is a transferer. A transferer is a contract that allows the token to be moved between chains using Interchain Token Transfers (ICTT). Set this flag to true if this token is responsible for transferring assets.
- **`home` Flag**: The `home` flag is used to indicate that this token is the original version of the asset on the **home chain**. When a token is mirrored on multiple chains, the home chain holds the original token, while the mirrors are representations of it on other chains.

These flags ensure proper handling of tokens when they are moved across chains. The `home` flag helps identify which chain holds the token, while `the is_transferer` flag specifies whether the token contract is responsible for transfers. 
</Accordion>
</Accordions>


</Step>
<Step> 
### Implement the ICTT Component

- Navigate to the `web-apps/src/app/ictt` folder.

Once you're inside the **ICTT** folder, open the `page.tsx` file to implement the **ICTT component** in the page. Here’s how to pass the token and chain details to the component:

```tsx
<ICTT tokens={tokens} token_in="0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d" source_chain_id={43113} destination_chain_id={173750}></ICTT>
```

In this example:

- `tokens` contains the configuration.
- `token_in` specifies the address of the token being transferred.
- `source_chain_id` and `destination_chain_id` represent the IDs of the source and destination chains. 
</Step>
<Step> 
### Run the Application

Move back to the `web-apps` folder and run the following command to start the app in development mode:

```bash
yarn run dev
```

You can now interact with the ICTT component. 

</Step>
</Steps>


# Origin of the EVM (/academy/avalanche-l1/customizing-evm/02-intro-to-evm/01-origin-of-evm)

---
title: Origin of the EVM
description: Learn about the origin of the Ethereum Virtual Machine.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: BookOpen
---

The **Ethereum Virtual Machine (EVM)** is a fundamental component of Ethereum’s infrastructure, responsible for executing smart contracts across the network. The origins of the EVM can be traced back to the creation of the Ethereum blockchain itself, proposed in a whitepaper by **Vitalik Buterin** in late 2013.

Buterin and the founding Ethereum team envisioned a platform where developers could build **decentralized applications (dApps)** on a blockchain. To accomplish this, they needed a way to execute arbitrary, complex computations in a secure and decentralized manner. This is how the concept of the EVM was born.

The EVM, an integral part of the Ethereum ecosystem, operates as a **quasi-Turing complete machine**. This means it can run nearly any algorithm, given enough resources. It's isolated from the main network, providing a sandboxed environment for smart contract execution.

Following the publication of the whitepaper, the Ethereum project moved into development. The first live version of the Ethereum network, including the EVM, launched on **July 30, 2015**. The Ethereum blockchain was designed with the EVM at the protocol level, enabling users to create and execute smart contracts. These smart contracts are essentially programs that autonomously execute the terms of an agreement. They are written in high-level languages like **Solidity** or **Vyper**, which are then compiled down to EVM bytecode for execution on the EVM.

Since its creation, the EVM has become a crucial component of the Ethereum blockchain and has set a standard for other blockchain platforms that have adopted similar models for executing smart contracts. The advent of the EVM has undoubtedly revolutionized the blockchain world by introducing the concept of **programmable blockchains**.


# Accounts, Keys, and Addresses (/academy/avalanche-l1/customizing-evm/02-intro-to-evm/02-accounts-keys-address)

---
title: Accounts, Keys, and Addresses
description: Learn about Accounts, Keys, and Addresses in EVM.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgrne]
icon: BookOpen
---

## Accounts

In the EVM, there are two types of accounts:

1. **Externally Owned Accounts (EOAs)**: These accounts are controlled by private keys and do not have associated code. They can send transactions by creating and signing them with their private keys. If you're an end user of Ethereum, you're likely using an EOA.

2. **Contract Accounts**: These accounts have associated code (smart contracts). Contract accounts can't initiate transactions on their own; instead, they only perform actions when instructed by an EOA. This could be as simple as a token transfer or a function call within a smart contract.

## Public and Private Keys

In Ethereum, as in many blockchain platforms, the **Elliptic Curve Digital Signature Algorithm (ECDSA)** is used to generate a pair of keys: a public key and a private key.

- The **private key** is a 32-byte number generated randomly.
- The **public key** is derived from the private key using elliptic curve cryptography. It is 64 bytes long, made up of two concatenated 32-byte coordinates.

## Addresses

An EVM address is derived from the public key through the following steps:

1. **Keccak-256 Hashing**: The public key is first passed through the Keccak-256 hashing function (the version of SHA-3 used by Ethereum). Keccak-256 outputs a 64-byte string, for example:
   `025ad33e2479a53b02dc0be66eb0ce272fc0f4358c57a8f0a442410c3d831a`

2. **Rightmost 20 bytes**: The resulting string is truncated to keep only the last 20 bytes. In hexadecimal, this means retaining the rightmost 40 hex digits (since two hex digits represent one byte), like so:
   `e66eb0ce272fc0f4358c57a8f0a442410c3d831a`

3. **Adding '0x'**: Finally, "0x" is prefixed to the address for a total of 42 characters. The "0x" indicates that the following characters represent a hexadecimal number, a common convention in Ethereum:
   `0xe66eb0ce272fc0f4358c57a8f0a442410c3d831a`

This process ensures that each Ethereum address uniquely corresponds to a public key. Since the address is a truncated hash of the public key, it's impossible to reverse-engineer the public key from the address.


# Transactions and Blocks (/academy/avalanche-l1/customizing-evm/02-intro-to-evm/03-transactons-and-blocks)

---
title: Transactions and Blocks
description: Learn about another fundamental aspect of the Ethereum ecosystem - Transactions and Blocks.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: BookOpen
---

## Transactions

In the EVM, a transaction is the smallest unit of work that can be included in a block. It represents a **state transition**, modifying account data and transferring Ether across the network.

Transactions can either transfer Ether or invoke smart contracts. Each transaction includes the following components:

- **Nonce**: A unique value set by the sender to ensure the transaction is processed only once, preventing replay attacks.
- **Gas Price**: The amount the sender is willing to pay per unit of gas, typically measured in `nanoLux` (1 `nLux` = 1/(10^9) Lux). It consists of three parts:
  - **Base Gas Fee**: The minimum `nLux` required per unit of gas.
  - **Maximum Priority Gas Fee**: Additional `nLux` the sender is willing to pay on top of the base fee.
  - **Maximum Total Gas Fee**: The maximum `nLux` the sender is willing to spend per unit of gas. If the sum of the base gas fee and the priority gas fee exceeds this amount, the gas price paid will be capped at the maximum total gas fee.
- **Gas Limit**: The maximum amount of gas units the sender is willing to pay for executing the transaction. If this limit is reached, the transaction fails, preventing indefinite execution.
- **To**: The recipient's Ethereum address or the target smart contract.
- **V, R, S**: Cryptographic data used to create the sender's signature.

## Blocks

A block in the EVM is a bundle of validated transactions, grouped together and linked to the previous block. Each block contains:

- **Block Number**: The index of the block, representing its position in a zero-indexed linked list.
- **Timestamp**: The time the block was mined.
- **Transactions Root**: The Merkle root of all transactions within the block.
- **Receipts Root**: The Merkle root of all transaction receipts.
- **State Root**: A hash of the entire Ethereum state after executing all transactions in the block.
- **Parent Hash**: The hash of the previous (parent) block.
- **Gas Limit**: The maximum gas all transactions in the block can consume.
- **Gas Used**: The total gas consumed by all transactions in the block.
- **Extra Data**: An optional field for including arbitrary data up to 32 bytes.
- **Validator**: The address of the node that proposed the block.


# Different Versions of EVM (/academy/avalanche-l1/customizing-evm/02-intro-to-evm/05-different-evm-versions)

---
title: Different Versions of EVM
description: Learn about the different versions of the Ethereum Virtual Machine in the Lux ecosystem.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: BookOpen
---

## Geth

Geth (or [go-ethereum](https://github.com/ethereum/go-ethereum)) is the official implementation of an Ethereum client, written in the Go programming language. It is one of the original and most widely used Ethereum clients today. Geth handles transactions, deploys and executes smart contracts, and contains the Ethereum Virtual Machine.

## Coreth

[Coreth](https://github.com/luxfi/luxgo/tree/master/graft/coreth) is a fork of Geth maintained by Lux Network. It implements the EVM for the LUExchange-Chain and has been adapted to work with Lux Consensus.

## Subnet-EVM

[Subnet-EVM](https://github.com/luxfi/subnet-evm) is a fork of Coreth designed to facilitate launching customized EVM-based blockchains on an Lux L1. It differs from Coreth in the following ways:

- **Configurable Fees and Gas Limits**: Customizable fees and gas limits can be set in the genesis file.
- **Unified Subnet-EVM Hardfork**: All Lux hardforks are merged into a single "Subnet-EVM" hardfork.
- **Atomic Transactions and Shared Memory Removed**: Support for atomic transactions and shared memory has been removed.
- **Multicoin Contracts and State Removed**: Multicoin contracts and state tracking are no longer supported.

## Precompile-EVM

Precompile-EVM allows precompiles to be registered with Subnet-EVM without needing to fork the Subnet-EVM codebase. This simplifies common customizations to Subnet-EVM, making them more accessible and easier to maintain. It also streamlines updates for Subnet-EVM.


# Your Own EVM Blockchain (/academy/avalanche-l1/customizing-evm/04-your-evm-blockchain/00-intro)

---
title: Your Own EVM Blockchain
description: Learn how to spin up your own EVM blockchain.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Book
---

In this part of the course, we'll explore how to run your own Lux L1 with a custom EVM. Running your own EVM allows you to address specific use cases, showcasing one of the key advantages of multi-chain systems over monolithic blockchains.

## Topics

We’ll cover the following topics:

- **Lux CLI**: Learn how to configure and launch an Lux L1 using the Lux CLI.
- **Token Transfer**: Explore how to perform token transfers with Foundry.

This hands-on exercise will solidify your knowledge and allow you to observe how customizations impact EVM performance.

## Learning Objective

By the end of this section, you’ll have the skills to effectively run your own Lux L1 with a custom EVM blockchain, empowering you to start building your blockchain projects!


# Lux CLI (/academy/avalanche-l1/customizing-evm/04-your-evm-blockchain/01-avalanche-cli)

---
title: Lux CLI
description: Learn about the Lux Command-Line Interface tooling.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## What is the Lux CLI?

The Lux CLI is a command-line tool that gives developers comprehensive access to Lux's functionalities, making it easier to build and test independent blockchains.

Each Lux network includes the Primary Network, which consists of the Contract (C), Platform (P), and Exchange (X) chains. It's important to note that "Primary Network" refers to a special Lux L1 rather than a distinct, standalone network.

Your local network operates independently from both the Mainnet and Testnet Testnet. You can even run an Lux L1 offline. Local Lux networks support, but are not limited to, the following commands:

- **Start and Stop a Network**: Easily start or stop a local network.
- **Health Check**: Check the health status of each node in the network.
- **Create Blockchains**: Spin up new blockchains with custom parameters.

Managing a local network with multiple nodes can be complex, but the Lux CLI simplifies the process with user-friendly commands.

## Usage

The Precompile-EVM repository comes preloaded with the Lux CLI and Foundry, so you don’t need to install additional tools when working within Codespaces. Just use the terminal in your Codespace to run Lux CLI commands and start building.


# Create Your Blockchain (/academy/avalanche-l1/customizing-evm/04-your-evm-blockchain/02-create-your-blockchain)

---
title: Create Your Blockchain
description: Learn how to use Lux-CLI to spin up your own EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import CreateDefaultBlockchain from "@/content/common/lux-starter-kit/create-default-blockchain.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<CreateDefaultBlockchain components={defaultMdxComponents}/>

# Sending Tokens (/academy/avalanche-l1/customizing-evm/04-your-evm-blockchain/03-sending-tokens)

---
title: Sending Tokens
description: Learn how to send tokens on your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

To ensure that the blockchain is up and running, let's perform a simple token transfer to a random address, `0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc`, using Foundry:

```bash
cast send --rpc-url myblockchain --private-key $PK 0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc --value 1ether
```
To verify if the transaction was successful, check the balance of the address with the following command:


```bash
cast balance --rpc-url myblockchain 0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc
```
```bash
1000000000000000000
```
You should see that the balance of the address `0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc` is now 1 (1 * 10^18).


Congratulations! You have successfully sent tokens on your EVM blockchain. 🎉




# Set Up Development Environment (/academy/avalanche-l1/customizing-evm/03-development-env-setup/00-intro)

---
title: Set Up Development Environment
description: Start by setting up your development environment.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

It's time to set up the development environment necessary for customizing the EVM! While the primary focus of this course is teaching you about precompiles, it's also crucial to configure a development environment that ensures a smooth and efficient workflow.

In this section, we will cover the following:

- Creating a GitHub repository for our customized EVM
- Setting up a default test account in your Core Wallet
- Exploring different types of development setups
- Choosing the setup for developing precompiles

Let's get started! 🚀


# Create Codespaces (/academy/avalanche-l1/customizing-evm/03-development-env-setup/02-create-codespaces)

---
title: Create Codespaces
description: Learn how to create GitHub Codespaces.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Open Precompile-EVM Repository in a Github Codespace

Open a Codespace on the [Precompile-EVM](https://github.com/luxfi/precompile-evm/tree/lux-academy-start) Repository on the `lux-academy-start` branch by clicking the button below: 

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=lux-academy-start&repo=605560683&machine=standardLinux32gb)

Next a window opens and the Codespace is built. This may take a few minutes.



When the building is completed, you can access the Codespace through the browser IDE.

## Closing Codespaces

The codespace time out after 30 minutes of inactivity by default. So if you are not too worried about the 30 hour/month limit, just close the window or the tab. Alternatively, you can open the command prompt (Cmd + Shift + P) and issue the command: **Stop Current Codespace**.



## Reopen Codespaces

You can see your Codespaces on https://github.com/codespaces/. There you can stop them, reopen them and delete them.



# Codespace in VS Code (/academy/avalanche-l1/customizing-evm/03-development-env-setup/03-codespace-in-vscode)

---
title: Codespace in VS Code
description: Learn how to setup GitHub Codespaces.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Switch from Browser to VS Code

You can switch any time from the browser IDE to Visual Studio Code:



The first time you switch, you will be asked to install the [Codespaces extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) and connect VS Code to you GitHub account, if it is not already connceted.

# EVM Configuration (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/00-vm-configuration)

---
title: EVM Configuration
description: Learn about Virtual Machine configuration.
updated: 2024-09-27
authors: [ashucoder9]
icon: Book
---

In this part of the course, we'll explore how to optimize your EVM through chain configuration, tailoring it to fit specific use cases. Customizing EVM configurations is a key advantage of multi-chain systems.

## Exercise

In this section, you won’t need to write any Go code. Instead, we’ll adjust values in the JSON file of the genesis block.

## Topics

We will cover the following topics:

- **Genesis Block**: The foundation of any blockchain. We’ll review its components and how to customize its properties.
- **Fee Configuration**: Learn how to balance validator incentives with user affordability. This is crucial for managing network congestion and discouraging wasteful transactions on public networks.
- **Initial Token Allocation**: Understand how to define the initial token distribution in your custom EVM, setting your network up for success.
- **Preinstalled Precompiles**: Discover how to configure preinstalled precompiles to leverage features like restricting who can issue transactions or deploy contracts on your chain.

Finally, we’ll demonstrate how to run a local EVM with a custom Genesis Block. This exercise will solidify your understanding and allow you to observe the performance impact of your EVM customizations.

## Learning Objective

By the end of this section, you'll be able to effectively customize the EVM in Lux, unlocking new possibilities for your blockchain projects. Let’s dive into EVM customization and chain configuration together!


# Genesis Block (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/01-genesis-block)

---
title: Genesis Block
description: Learn about the Genesis Block.
updated: 2024-09-27
authors: [ashucoder9]
icon: BookOpen
---

## Background

Each blockchain begins with a genesis state when it is created. For instance, the Ethereum mainnet genesis block included the addresses and balances from the Ethereum pre-sale, marking the initial distribution of ether.

For Subnet-EVM and Precompile-EVM, the genesis block contains additional parameters that allow us to configure the behavior of our customized EVM to meet specific requirements. Since each blockchain has its own genesis block, you can create two blockchains with the same VM but different genesis blocks.

## Format

Here’s an example of a genesis block:

```json
{
  "config": {
    "chainId": 43214,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 15000000,
      "minBaseFee": 25000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": false, 
    "txAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": [
        "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"
      ]
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0xe4e1c0",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```
We will explore the relevant configurable parameters in the upcoming activities. Some parameters (e.g., `eip150Block`, `byzantiumBlock`) are omitted here as they are not relevant for most use cases.

This version provides a clean and concise explanation of the genesis block and its structure, keeping the focus on what's essential.


# Create Your Genesis File (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/02-create-your-genesis)

---
title: Create Your Genesis File
description: Learn how to create your own genesis file.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Callout } from 'fumadocs-ui/components/callout';

## Create File

In your Precompile-EVM project, create a file called `evm-configuration-genesis.json` in the directory `tests/precompile/genesis/` and open it. You can use the command below as a shortcut to open the file in VSCode:

```bash
code ./tests/precompile/genesis/evm-configuration-genesis.json
```

## Fill with template

Paste the following template in the new file:

```json
{
    "config": {
      "chainId":  <your-chain-id>,
      "homesteadBlock": 0,
      "eip150Block": 0,
      "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
      "eip155Block": 0,
      "eip158Block": 0,
      "byzantiumBlock": 0,
      "constantinopleBlock": 0,
      "petersburgBlock": 0,
      "istanbulBlock": 0,
      "muirGlacierBlock": 0,
      "subnetEVMTimestamp": 0,
      "feeConfig": {
        "gasLimit": <your-gas-limit>,
        "minBaseFee": <your-min-base-fee>,
        "targetGas": <your-target-gas>,
        "baseFeeChangeDenominator": 36,
        "minBlockGasCost": <your-min-block-gas-cost>,
        "maxBlockGasCost": <your-max-block-gas-cost>,
        "targetBlockRate": <your-target-block-rate>,
        "blockGasCostStep": <your-block-gas-cost-step>
      },
      "allowFeeRecipients": false
    },
    "alloc": {
      "<your-test-wallet-address>": {
        "balance": "<your-initial-balance-converted-to-hex>"
      }
    },
    "nonce": "0x0",
    "timestamp": "0x0",
    "extraData": "0x00",
    "gasLimit": <your-gas-limit>,
    "difficulty": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x0000000000000000000000000000000000000000",
    "number": "0x0",
    "gasUsed": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
  }
```

<Callout title="Warning about gasLimit" type="warn">
If you do decide to set your own gasLimit, please set all gasLimit keys equal to the same value! 

If you set the 'gasLimit' keys to different values, you will still be able to deploy a blockchain, but it will halt during initialization!
</Callout>

# Setup Your ChainID (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/03-setup-chainid)

---
title: Setup Your ChainID
description: Learn how to setup ChainID for your own blockchain.
updated: 2024-09-27
authors: [ashucoder9]
icon: Terminal
---

## What is ChainID?

The `ChainID` of an EVM blockchain is a unique identifier that distinguishes Ethereum chains from one another. Introduced in Ethereum Improvement Proposal (EIP) 155, this mechanism prevents transaction replay attacks, which could occur when the same transaction is valid across multiple chains.

## Setting the ChainID

To set the `ChainID` for your blockchain, configure it in the `genesis` JSON file at the top level with the value `99999`.

If you wish to use a custom `ChainID`, check [chainlist.org](https://chainlist.org) to ensure your proposed `ChainID` is not in use by any other network. Be sure to cross-check with Testnets as well!




# Gas Fees and Gas Limit (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/04-gas-fees-and-limit)

---
title: Gas Fees and Gas Limit
description: Learn about Gas Fees and Gas Limit in the context of the EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Background

In the context of the EVM, gas is a unit that measures the computational effort required to execute specific operations. Each operation performed by a contract or transaction on an EVM chain consumes a certain number of gas units based on its complexity. Operations that require more computational resources cost more gas. The EVM calculates the required gas units automatically, and developers are encouraged to optimize their contract code to reduce gas consumption.

The cost of executing a transaction is determined by the gas units consumed and the gas price, calculated as follows:

```
Transaction Cost = Gas Units * Gas Price
```

For EVM Lux L1s, gas payment can be configured to better suit the use case of the Lux L1. This means that the Lux L1 design can decide whether the gas fees are burned, paid to incentivize validators, or used for any other custom behavior.

## Purpose

The primary goal of setting and enforcing computational costs via gas is to prevent spam and abuse on the network. By requiring users to pay for each computational step, the network deters malicious actors from launching denial-of-service (DoS) attacks, which involve flooding the network with spurious transactions. Essentially, the gas system serves as a deterrent against such attacks.

## Gas Price and Gas Limit

Each transaction specifies the gas price and gas limit:

**`Gas Price`:** The gas price is the amount of the Lux L1's native token that the sender is willing to spend per unit of gas, typically denoted in `gwei` (1 native token = 1,000,000,000 `gwei`). A well-designed gas mechanism adapts the gas price according to network activity to protect the network from spam.

**`Gas Limit`:** The gas limit is the maximum amount of gas the sender is willing to use for the transaction. It was introduced to prevent infinite loops in contract execution. In a Turing-complete language like Solidity (the main programming language in the EVM), it is possible to write a contract with an infinite loop, either accidentally or intentionally. While an infinite loop might be a nuisance in traditional computing, it could cause significant issues in a decentralized blockchain by causing the network to hang as it attempts to process a never-ending transaction. The gas limit prevents this by halting execution once the gas consumed reaches the limit.

If a transaction exceeds the gas limit, it fails, but the fee amounting to the gas limit is still paid by the sender.


# Gas Fees Configuration (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/05-gas-fee-configuration)

---
title: Gas Fees Configuration
description: Learn how to configure gas fees in your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Configuration Format

The fees are configured in the `chainConfig` in the `feeConfig` field:

```json
{
  "config": {
    // ...
    "feeConfig": { // [!code highlight]
      "gasLimit": 15000000,
      "minBaseFee": 25000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": false
  },
  "alloc": {
    // ...
  },
  // ...
    
  "gasLimit": 0xe4e1c0,
  // ...
}
```

## Gas Configuration Parameters

### `gasLimit`

Sets the maximum amount of gas consumed per block. This restriction caps the computational capacity of a single block and thereby limits the maximum gas usage allowed for any single transaction. For reference, the LUExchange-Chain value is set to 15,000,000.

You might notice that the `gasLimit` field appears twice. This is because Lux introduced its own fee configuration under the `feeConfig` key while maintaining compatibility with the standard EVM configuration. Ensure that both fields have the same decimal and hexadecimal equivalent values.

### `targetBlockRate`

Specifies the target rate of block production in seconds. For instance, a target of 2 aims to produce a block every 2 seconds. If blocks are produced faster than this rate, it signals that more blocks are being issued to the network than anticipated, leading to an increase in base fees. For LUExchange-Chain, this value is set to 2.

### `minBaseFee`

Establishes a lower bound on the EIP-1559 base fee for a block. This minimum base fee effectively sets the minimum gas price for any transaction included in that block.

### `targetGas`

Indicates the targeted amount of gas (including block gas cost) to be consumed within a rolling 10-second window. The dynamic fee algorithm adjusts the base fee proportionally based on how actual network activity compares to this target. If network activity exceeds the `targetGas`, the base fee is increased accordingly.

### `baseFeeChangeDenominator`

Determines how much to adjust the base fee based on the difference between actual and target utilization. A larger denominator results in a slower-changing base fee, while a smaller denominator allows for quicker adjustments. For LUExchange-Chain, this value is set to 36, meaning the base fee changes by a factor of 1/36 of the parent block's base fee.

### `minBlockGasCost`

Sets the minimum amount of gas charged for the production of a block. In the LUExchange-Chain, this value is set to 0.

### `maxBlockGasCost`

Specifies the maximum amount of gas charged for the production of a block.

### `blockGasCostStep`

Defines how much to increase or decrease the block gas cost based on the time elapsed since the previous block. If a block is produced at the target rate, the block gas cost remains the same as the parent block. If the production rate deviates from the target, the block gas cost is adjusted by the `blockGasCostStep` value for each second faster or slower than the target block rate.


# Configure Gas Fees (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/06-configuring-gas-fees)

---
title: Configure Gas Fees
description: Learn how to configure gas fees in your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Benchmarks

You can take these numbers below as a benchmark:

```json
"feeConfig": {
        "gasLimit": 15000000,
        "minBaseFee": 25000000000,
        "targetGas": 15000000,
        "baseFeeChangeDenominator": 36,
        "minBlockGasCost": 0,
        "maxBlockGasCost": 1000000,
        "targetBlockRate": 2,
        "blockGasCostStep": 200000
      },
        
"gasLimit": 0xe4e1c0,
```

## Choose Your Own Values

### `gasLimit`

As previously discussed, the `gasLimit` acts as a restriction on the amount of computation that can be executed in a single block, and hence caps the maximum transaction size, as the entire transaction needs to be processed within the same block.

Your choice of `gasLimit` values should depend on the specific use case and computational demands of your application. Here are some considerations:

**High Throughput:** If your application requires a high volume of transactions, you might want to allow for more transactions (i.e., more computation) to be packed into a single block. This increases the block capacity and enables handling a higher transaction load.

**Heavy Transactions:** Transactions that involve deploying large contracts or executing complex operations tend to consume more gas. If your application involves such operations, ensure that your `gasLimit` accommodates the full execution of these heavy transactions or contract deployments.

Be cautious with setting excessively high `gasLimit` values. Larger computational allowances per block can translate to increased hardware requirements for your blockchain. Therefore, align the `gasLimit` with your use case and infrastructure requirements for validators. Avoid setting an unusually large value "just in case." For reference, consider that a typical native token transaction costs around 21,000 gas units, and the LUExchange-Chain `gasLimit` is set to 15,000,000.

### Gas Price Parameters

The following parameters affect the gas pricing and dynamic adjustments in your network:

- **`minBaseFee`**: Sets the minimum base fee per unit of gas, establishing the lower bound for transaction costs in a block.
- **`targetGas`**: Defines the target amount of gas to be consumed within a rolling 10-second window. Adjust this based on the expected network activity under normal conditions.
- **`baseFeeChangeDenominator`**: Controls how quickly the base fee adjusts in response to fluctuations in gas usage. A smaller denominator allows for faster adjustments.
- **`minBlockGasCost`**: Specifies the minimum gas cost for producing a block.
- **`maxBlockGasCost`**: Sets the maximum gas cost for producing a block.
- **`targetBlockRate`**: Determines the desired block production rate in seconds. Choose this based on your expected block issuance frequency.
- **`blockGasCostStep`**: Adjusts the block gas cost based on the deviation from the target block rate. A higher step value increases the block gas cost more rapidly with deviations.

These parameters should be selected based on the stability of gas usage in your network. Since gas fees are crucial for protecting against spam and abuse, carefully consider how these parameters will adapt to changes in network activity. The goal is to dynamically adjust transaction costs during irregular activity periods while maintaining stability under normal conditions.


# Initial Token Allocation (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/07-initial-token-allocation)

---
title: Initial Token Allocation
description: Learn about the initial token allocation and configure in your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Callout } from 'fumadocs-ui/components/callout';

## Background

`Alloc` defines the initial balances of addresses at the time of chain creation. This field should be modified according to the specific requirements of each chain.

If no genesis allocation is provided, you won't be able to interact with your new chain, as all transactions require a fee to be paid from the sender's balance. Without an initial allocation, there will be no funds available to cover transaction fees.

## Format

The `alloc` field expects key-value pairs. Keys must be valid addresses, and the balance field in each value can be either a hexadecimal or decimal number representing the initial balance of the address.

```json
{
  "config": {
    // ...
  },
  "alloc": { // [!code highlight]
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000" // 50,000,000 tokens
    }
  },
  // ...
}
```

Keys in the allocation are hex addresses without the canonical 0x prefix. Balances are denominated in `Wei` (10^18 `Wei` = 1 Whole Unit of the native token of the chain) and expressed as hex strings with the canonical 0x prefix. Use [this converter](https://www.rapidtables.com/convert/number/hex-to-decimal.html) for translating between decimal and hex numbers.

The default configuration for testing purposes allocates a significant number of tokens to the address `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC`. 

The private key for this address (as defined in the `.devcontainer`) is: `56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027`.

<Callout title="Warning" type="warn"> Never use this address or private key for anything other than testing on a local test network. The private key is publicly known, and any real funds transferred to this address are likely to be stolen. </Callout>


## Configure

Allocate tokens to two addresses:

- The well-known test address `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC`.
- Another test address that you have created (avoid using addresses associated with real funds).

```json
{
  "config": {
    // ...
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": { // [!code highlight]
      "balance": "0x295BE96E64066972000000" // 50,000,000 tokens
    },
    "<your_address>": { // [!code highlight]
      "balance": "0x295BE96E64066972000000" // 50,000,000 tokens
    }
  },
  // ...
}

```

# Build and Run Custom Genesis EVM (/academy/avalanche-l1/customizing-evm/05-genesis-configuration/08-build-and-run-custom-genesis-blockchain)

---
title: Build and Run Custom Genesis EVM
description: Learn how to build and run your blockchain with custom genesis file.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

<Steps>
<Step>

### Build Your Precompile-EVM

There's a simple build script in the Precompile-EVM we can utilize to build. First, make sure you are in the root folder of you Precompile-EVM:

```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
```

Then run the command to initiate the build script:

```bash
./scripts/build.sh
```

</Step>
<Step>

### Create your blockchain configuration

You can run your Precompile-EVM by using the Lux CLI.

First, create the configuration for your blockchain:

```bash
lux blockchain create myblockchain \
 --custom \
 --vm $VM_PATH \
 --genesis "./.devcontainer/genesis-example.json" \
 --force \
 --sovereign=false \
 --evm-token "TOK" \
 --warp \
 --icm
```

</Step>
<Step>

### Launch L1 with you customized EVM

```bash
lux blockchain deploy myblockchain --local
```

After around 1 minute, the blockchain should have been created, and additional output will appear in
the terminal. You'll also see the RPC URL of your blockchain in the terminal.

</Step>
</Steps>



# What are Precompiles? (/academy/avalanche-l1/customizing-evm/06-precompiles/01-what-are-precompiles)

---
title: What are Precompiles?
description: Learn about Precompiled Smart Contracts in EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Precompiled contracts allow the execution of code written in the low-level programming language Go from the EVM, which is significantly faster and more efficient than Solidity.

## Overview

If you're familiar with Python, you might recognize a similar concept where many Python functions and libraries are implemented in C for efficiency. Python developers can import these precompiled modules and call functions as if they were written in Python. The main difference is that the modules execute faster and more efficiently.

Precompiles can be called from a Solidity smart contract just like any other contract. The EVM maintains a list of reserved addresses mapped to precompiles. When a smart contract calls a function of a contract at one of these addresses, the EVM executes the precompile written in Go instead of the Solidity contract.

For example, if we map the address `0x030...01` to the SHA256 precompile that hashes its input using the SHA256 hash function, we can call the precompile as follows:

```solidity
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ISHA256 {
    // Computes the SHA256 hash of value
    function hashWithSHA256(string memory value) external view returns(bytes32 hash);
}

contract MyContract {  
    ISHA256 mySHA256Precompile = ISHA256(0x0300000000000000000000000000000000000001);
    
    function doSomething() public {
        bytes32 hash = mySHA256Precompile.hashWithSHA256("test");
    }
}
```
In the code above, we call the precompile using the defined interface for our SHA256 precompile within `MyContract`.

Note that there is no implementation of the precompile in Solidity itself. This will only work if the precompile is implemented in Go and registered at the address `0x030...01`.

### PrecompiledContract Interface

When implementing a precompile in the Lux L1-EVM, the following function of the `StatefulPrecompiledContract` interface must be implemented in Go:

```go
// StatefulPrecompiledContract is the interface for executing a precompiled contract
type StatefulPrecompiledContract interface {
    // Run executes the precompiled contract.
    Run(accessibleState AccessibleState, 
        caller common.Address, 
        addr common.Address, 
        input []byte, 
        suppliedGas uint64, 
        readOnly bool) 
        (ret []byte, remainingGas uint64, err error)
}
```

We will cover the meaning of "stateful" and the first parameter `accessibleState` later. For now, let's focus on the function that specifies the logic of our precompile, which provides access to the following data:

- caller: The address of the account that called the precompile.
- addr: The address of the precompile being called.
- input: All inputs encoded in a byte array.
- suppliedGas: The amount of gas supplied for the precompile call.
- readOnly: A boolean flag indicating if the interaction is only reading or modifying the state.

The precompile implementation must return the following values:

- ret: All return values encoded in a byte array.
- remainingGas: The amount of gas remaining after execution.
- err: If an error occurs, return it. Otherwise, return nil.

# Why Precompiles? (/academy/avalanche-l1/customizing-evm/06-precompiles/02-why-precompiles)

---
title: Why Precompiles?
description: Learn about why you should utilize Precompiles in your smart contracts.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Adding precompiles to the EVM offers several significant advantages, which we will outline in this chapter.

## Performance Optimization

Precompiles primarily optimize the performance of specific computations. Introducing a new precompile can greatly reduce the computational resources required for certain tasks, thereby enhancing the performance of smart contracts and decentralized applications (DApps) that rely on these tasks.

For instance, the SHA256 hash function (0x02) and the RIPEMD160 hash function (0x03) serve as examples of precompiles that significantly boost performance. Implementing these functions within a smart contract would be computationally expensive and slow, whereas as precompiles, they execute quickly and efficiently.

## Security

Incorporating a function as a precompile allows developers to leverage libraries that have been thoroughly reviewed and audited, thus reducing the risk of bugs and vulnerabilities, which enhances overall security.

For example, the ModExp (0x05) precompile safely performs modular exponentiation, a complex mathematical operation utilized in various cryptographic functions.

## Access to Go Libraries

Precompiles are implemented in Go, allowing access to the rich ecosystem of existing Go libraries. This access eliminates the need for reimplementation, which can be labor-intensive and carries the risk of introducing bugs during the translation from Go to Solidity.

Consider the implementation of the SHA256 hash algorithm to understand the complexity involved in reimplementing it in Solidity.

## Gas Efficiency

Introducing a new precompile to the EVM can enhance gas efficiency for specific computations, thereby lowering execution costs. This makes it feasible to incorporate more complex operations into smart contracts, expanding their functionality without significantly increasing transaction costs.

The identity precompile (0x04), which copies and returns input data, exemplifies this. Though simple, it provides gas efficiency by being faster and cheaper than implementing the same functionality in a standard contract.

## Advanced Features and Functionality

By adding new precompiles to the EVM, developers can introduce advanced features and functionalities, such as complex mathematical calculations, advanced cryptographic operations, and new data structures. This can unlock new possibilities for DApps and smart contracts, enabling them to execute tasks that would otherwise be too computationally demanding or technically challenging.

Precompiles for elliptic curve operations, such as ecadd (0x06), ecmul (0x07), and ecpairing (0x08), enable advanced cryptographic functionality within EVM smart contracts. These precompiles are crucial for implementing zk-SNARKs, a form of zero-knowledge proof, in Ethereum.

## Interoperability

Certain precompiles can enhance the interoperability of the EVM with other blockchains or systems. For instance, precompiles can be utilized to verify proofs from other chains or perform operations compatible with different cryptographic standards.

The BLS12-381 elliptic curve operations precompiles (0x0a through 0x13, added in the Istanbul upgrade) improve EVM interoperability by allowing operations that are compatible with the BLS signature scheme, potentially facilitating inter-blockchain communication.


# Interact with a Precompile (/academy/avalanche-l1/customizing-evm/06-precompiles/03-interact-wtih-precompile)

---
title: Interact with a Precompile
description: Learn about why you should utilize Precompiles in your smart contracts.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

So let's get to it and interact with a precompile on the LUExchange-Chain of your local network. The SHA256 precompile is already available on the LUExchange-Chain.

## Call Precompile from Foundry

In this example, we will call the SHA256 precompile to generate hash of the input string.

**Precompile Address:** `0x0000000000000000000000000000000000000002`

```bash 
cast call --rpc-url local-c --private-key $PK 0x0000000000000000000000000000000000000002 "run(string)(bytes32)" "test"
```

You should see a bytes32 hash of the input string `test` as the output. 

```bash
0xa770b926e13a31fb823282e9473fd1da9e85afe23690336770c490986ef1b1fc
```

# Overview (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/00-intro)

---
title: Overview
description: Learn how to create a Calculator precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

## Reference Implementation

In this section, we will showcase how to build a more complex precompile that offers selected simple math operations. Our calculator will support the following operations:

1. Add two numbers and return the result (3 + 5 = 8)
2. Get the next two greater numbers (7 => 8, 9)
3. Repeat a string x times (4, b => bbbb)

This is somewhat odd calculator and real-life usability might not be the best, but as you will see in a bit the operations have been chosen to demonstrate some different scenarios we might face while building precompiles.

## What You Are Building

Similar to the Calculator precompile, you will be building a precompile called **CalculatorPlus** which contains the following mathematical functions:

- **Powers of Three**: takes in as input an integer base; returns the square, cube, and 4th power of the input
- **Modulo+**: takes in as input two arguments: the dividend and the divisor. Returns how many times the dividend fits in the divisor, and the remainder.
- **Simplify Fraction**: takes in two arguments: the numerator and the denominator. Returns the simplfied version of the fraction (if the denominator is 0, we return 0)

## Overview of Steps

Compared to the process before, we will now also add tests for our precompile. Here's a quick overview of the steps we're going to follow:
 
<Steps>
<Step>
Create a Solidity interface for the precompile
</Step>
<Step>
Generate the ABI
</Step>
<Step>
Write the precompile code in Go
</Step>
<Step>
Configure and register the precompile
</Step>
<Step>
Add and run tests
</Step>
<Step>
Build and run your customized EVM
</Step>
<Step>
Connect Remix to your customized EVM and interact with the precompile
</Step>
</Steps>

This tutorial will help you understand how to create more complex precompiles. Let's begin!


# Create Solidity Interface (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/01-create-solidity-interface)

---
title: Create Solidity Interface
description: Learn how to create the Solidity interface for your calculator precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Just like in the MD5 section, we will start off by first demonstrating the Solidity interface for the Calculator precompile before guiding you on how to build the **CalculatorPlus** precompile. To start, let's take a look at the Calculator Solidity interface:

```solidity title="contracts/contracts/interfaces/ICalculator.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ICalculator {
    function add(uint value1, uint value2) external view returns(uint result);

    function nextTwo(uint value1) external view returns(uint result1, uint result2);

    function repeat(uint times, string memory text) external view returns(string memory result);
}
```

With this in mind, let's define the CalculatorPlus Solidity interface. Your interface should have the following three functions:

1. `powOfThree`: takes in an unsigned integer base, and returns three unsigned integers named secondPow, thirdPow, fourthPow . 
2. `moduloPlus`: takes in unsigned integers dividend and divisor as input, and returns two unsigned integers named multiple and remainder .
3. `simplFrac`: takes in unsigned integers named numerator and denominator, and returns two unsigned integers named simplNum and simplDenom

<Accordions>
<Accordion title="Solution">

```solidity title="solidity/interfaces/ICalculatorPlus.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ICalculatorPlus {
    function powOfThree(uint256 base) external view returns(uint256 secondPow, uint256 thirdPow, uint256 fourthPow);

    function moduloPlus(uint256 dividend, uint256 divisor) external view returns(uint256 multiple, uint256 remainder);

    function simplFrac(uint256 numerator, uint256 denominator) external view returns(uint256 simplNum, uint256 simplDenom);
}
```

</Accordion>
</Accordions>

## Generate the ABI

Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the terminal (control + \`), change to the `/contracts` directory and run the following command to compile the solidity interface to the ABI:

```bash
# Go to the upper contracts directory of your project
cd contracts

# Compile ICalculatorPlus.sol to ABI
npx solc@latest --abi ./contracts/interfaces/ICalculatorPlus.sol -o ./abis --base-path . --include-path ./node_modules

# Rename using this script or manually
mv ./abis/contracts_interfaces_ICalculatorPlus_sol_ICalculatorPlus.abi ./abis/ICalculatorPlus.abi
```

Now you should have a file called `ICalculatorPlus.abi` in the folder `/contracts/abis` with the following content:

```json title="/contracts/abis/ICalculatorPlus.abi"
[
  {
    "inputs": [
      {
        "internalType": "uint256",
        "name": "dividend",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "divisor",
        "type": "uint256"
      }
    ],
    "name": "moduloPlus",
    "outputs": [
      {
        "internalType": "uint256",
        "name": "multiple",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "remainder",
        "type": "uint256"
      }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      {
        "internalType": "uint256",
        "name": "base",
        "type": "uint256"
      }
    ],
    "name": "powOfThree",
    "outputs": [
      {
        "internalType": "uint256",
        "name": "secondPow",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "thirdPow",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "fourthPow",
        "type": "uint256"
      }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      {
        "internalType": "uint256",
        "name": "numerator",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "denominator",
        "type": "uint256"
      }
    ],
    "name": "simplFrac",
    "outputs": [
      {
        "internalType": "uint256",
        "name": "simplNum",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "simplDenom",
        "type": "uint256"
      }
    ],
    "stateMutability": "view",
    "type": "function"
  }
]
```


# Generating the Precompile (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/02-generating-precompile)

---
title: Generating the Precompile
description: Learn how to generating the precompile
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In this step, we will again utilize the precompile generation script to generate all the Go files based on the ABI for your calculator.

## Run Generation Script

Change to the root directory of your precompile-evm project and run the command to generate the go files:

```bash
# Change to root
cd ..

# Generate go files
./scripts/generate_precompile.sh --abi ./contracts/abis/ICalculatorPlus.abi --type Calculatorplus --pkg calculatorplus --out ./calculatorplus
```

Now you should have a new directory called `calculatorplus` in the root directory of your project.

If you check our the generated contract.go file you will see right away that it is much longer than in our hash function precompile from earlier. This is due to the fact that our calculator precompile has more functions and parameters. Browse through the code and see if you can spot the new elements:

```go title="contract.go"
// Code generated
// This file is a generated precompile contract config with stubbed abstract functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package calculatorplus

import (
    "errors"
    "fmt"
    "math/big"

    "github.com/luxfi/subnet-evm/accounts/abi"
    "github.com/luxfi/subnet-evm/precompile/contract"
    "github.com/luxfi/subnet-evm/vmerrs"

    _ "embed"

    "github.com/ethereum/go-ethereum/common"
)

const (
    // Gas costs for each function. These are set to 1 by default.
    // You should set a gas cost for each function in your contract.
    // Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
    // There are some predefined gas costs in contract/utils.go that you can use.
    ModuloPlusGasCost uint64 = 1 /* SET A GAS COST HERE */
    PowOfThreeGasCost uint64 = 1 /* SET A GAS COST HERE */
    SimplFracGasCost  uint64 = 1 /* SET A GAS COST HERE */
)

// CUSTOM CODE STARTS HERE
// Reference imports to suppress errors from unused imports. This code and any unnecessary imports can be removed.
var (
    _ = abi.JSON
    _ = errors.New
    _ = big.NewInt
    _ = vmerrs.ErrOutOfGas
    _ = common.Big0
)

// Singleton StatefulPrecompiledContract and signatures.
var (
    // CalculatorplusRawABI contains the raw ABI of Calculatorplus contract.
    //go:embed contract.abi
    CalculatorplusRawABI string

    CalculatorplusABI = contract.ParseABI(CalculatorplusRawABI)

    CalculatorplusPrecompile = createCalculatorplusPrecompile()
)

type ModuloPlusInput struct {
    Dividend *big.Int
    Divisor  *big.Int
}

type ModuloPlusOutput struct {
    Multiple  *big.Int
    Remainder *big.Int
}

type PowOfThreeOutput struct {
    SecondPow *big.Int
    ThirdPow  *big.Int
    FourthPow *big.Int
}

type SimplFracInput struct {
    Numerator   *big.Int
    Denominator *big.Int
}

type SimplFracOutput struct {
    SimplNum   *big.Int
    SimplDenom *big.Int
}

// UnpackModuloPlusInput attempts to unpack [input] as ModuloPlusInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusInput(input []byte) (ModuloPlusInput, error) {
    inputStruct := ModuloPlusInput{}
    err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "moduloPlus", input)

    return inputStruct, err
}

// PackModuloPlus packs [inputStruct] of type ModuloPlusInput into the appropriate arguments for moduloPlus.
func PackModuloPlus(inputStruct ModuloPlusInput) ([]byte, error) {
    return CalculatorplusABI.Pack("moduloPlus", inputStruct.Dividend, inputStruct.Divisor)
}

// PackModuloPlusOutput attempts to pack given [outputStruct] of type ModuloPlusOutput
// to conform the ABI outputs.
func PackModuloPlusOutput(outputStruct ModuloPlusOutput) ([]byte, error) {
    return CalculatorplusABI.PackOutput("moduloPlus",
        outputStruct.Multiple,
        outputStruct.Remainder,
    )
}

// UnpackModuloPlusOutput attempts to unpack [output] as ModuloPlusOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusOutput(output []byte) (ModuloPlusOutput, error) {
    outputStruct := ModuloPlusOutput{}
    err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "moduloPlus", output)

    return outputStruct, err
}

func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the ModuloPlusInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackModuloPlusInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
    var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
    packedOutput, err := PackModuloPlusOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// UnpackPowOfThreeInput attempts to unpack [input] into the *big.Int type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeInput(input []byte) (*big.Int, error) {
    res, err := CalculatorplusABI.UnpackInput("powOfThree", input)
    if err != nil {
        return new(big.Int), err
    }
    unpacked := *abi.ConvertType(res[0], new(*big.Int)).(**big.Int)
    return unpacked, nil
}

// PackPowOfThree packs [base] of type *big.Int into the appropriate arguments for powOfThree.
// the packed bytes include selector (first 4 func signature bytes).
// This function is mostly used for tests.
func PackPowOfThree(base *big.Int) ([]byte, error) {
    return CalculatorplusABI.Pack("powOfThree", base)
}

// PackPowOfThreeOutput attempts to pack given [outputStruct] of type PowOfThreeOutput
// to conform the ABI outputs.
func PackPowOfThreeOutput(outputStruct PowOfThreeOutput) ([]byte, error) {
    return CalculatorplusABI.PackOutput("powOfThree",
        outputStruct.SecondPow,
        outputStruct.ThirdPow,
        outputStruct.FourthPow,
    )
}

// UnpackPowOfThreeOutput attempts to unpack [output] as PowOfThreeOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeOutput(output []byte) (PowOfThreeOutput, error) {
    outputStruct := PowOfThreeOutput{}
    err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "powOfThree", output)

    return outputStruct, err
}

func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, PowOfThreeGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the PowOfThreeInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackPowOfThreeInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
    var output PowOfThreeOutput // CUSTOM CODE FOR AN OUTPUT
    packedOutput, err := PackPowOfThreeOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// UnpackSimplFracInput attempts to unpack [input] as SimplFracInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracInput(input []byte) (SimplFracInput, error) {
    inputStruct := SimplFracInput{}
    err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "simplFrac", input)

    return inputStruct, err
}

// PackSimplFrac packs [inputStruct] of type SimplFracInput into the appropriate arguments for simplFrac.
func PackSimplFrac(inputStruct SimplFracInput) ([]byte, error) {
    return CalculatorplusABI.Pack("simplFrac", inputStruct.Numerator, inputStruct.Denominator)
}

// PackSimplFracOutput attempts to pack given [outputStruct] of type SimplFracOutput
// to conform the ABI outputs.
func PackSimplFracOutput(outputStruct SimplFracOutput) ([]byte, error) {
    return CalculatorplusABI.PackOutput("simplFrac",
        outputStruct.SimplNum,
        outputStruct.SimplDenom,
    )
}

// UnpackSimplFracOutput attempts to unpack [output] as SimplFracOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracOutput(output []byte) (SimplFracOutput, error) {
    outputStruct := SimplFracOutput{}
    err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "simplFrac", output)

    return outputStruct, err
}

func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, SimplFracGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the SimplFracInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackSimplFracInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct            // CUSTOM CODE OPERATES ON INPUT
    var output SimplFracOutput // CUSTOM CODE FOR AN OUTPUT
    packedOutput, err := PackSimplFracOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// createCalculatorplusPrecompile returns a StatefulPrecompiledContract with getters and setters for the precompile.

func createCalculatorplusPrecompile() contract.StatefulPrecompiledContract {
    var functions []*contract.StatefulPrecompileFunction

    abiFunctionMap := map[string]contract.RunStatefulPrecompileFunc{
        "moduloPlus": moduloPlus,
        "powOfThree": powOfThree,
        "simplFrac":  simplFrac,
    }

    for name, function := range abiFunctionMap {
        method, ok := CalculatorplusABI.Methods[name]
        if !ok {
            panic(fmt.Errorf("given method (%s) does not exist in the ABI", name))
        }
        functions = append(functions, contract.NewStatefulPrecompileFunction(method.ID, function))
    }
    // Construct the contract with no fallback function.
    statefulContract, err := contract.NewStatefulPrecompileContract(nil, functions)
    if err != nil {
        panic(err)
    }
    return statefulContract
}
```

# Unpacking Multiple Inputs & Packing Multiple Outputs (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/03-unpacking-and-packing)

---
title: Unpacking Multiple Inputs & Packing Multiple Outputs
description: Learn how to unpack multiple inputs and packing multiple outputs.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Unpack/Pack Functions For Each Operation

As with the MD5 precompile, the generator created the pack/unpack functions for each operation of our Calculator and CalculatorPlus precompiles. However, you might have noticed that the generator also created some struct in each respective `contract.go` file. In the case of CalculatorPrecompile, we have:

```go title="contract.go"
type AddInput struct {
    Value1 *big.Int
    Value2 *big.Int
}

type NextTwoOutput struct {
    Result1 *big.Int
    Result2 *big.Int
}

type RepeatInput struct {
    Times *big.Int
    Text  string
}
```

The generator creates these structs whenever a function defined in the respective Solidity interface has more than one input or more than one output. These multiple values are now stored together via structs.

## Unpacking Multiple Inputs

To understand how unpacking works when structs are introduced, let's take a look at the add function in the Calculator precompile, which takes in two inputs, and the nextTwo, which takes in only one input.

```go
// UnpackAddInput attempts to unpack [input] as AddInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackAddInput(input []byte) (AddInput, error) {
    inputStruct := AddInput{}
    err := CalculatorABI.UnpackInputIntoInterface(&inputStruct, "add", input)
    return inputStruct, err
}

// UnpackNextTwoInput attempts to unpack [input] into the *big.Int type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackNextTwoInput(input []byte) (*big.Int, error) {
    res, err := CalculatorABI.UnpackInput("nextTwo", input)
    if err != nil {
        return big.NewInt(0), err
    }
    unpacked := *abi.ConvertType(res[0], new(*big.Int)).(**big.Int)
    return unpacked, nil
}
```

As you can see, both unpacker functions take a byte array as an input but the `UnpackAddInput` returns a value of the type `AddInput` (which contains two `big.Int` values) and `UnpackNextTwoInput` returns a value of the type `big.Int`.

In each case, the respective unpacking function takes in a byte array as an input. However, `UnpackAddInput` returns a value of the type `AddInput`, which is a struct that contains two `big.Int` values. `UnpackNextTwo`, meanwhile, returns an value of type `big.Int`. 

To demonstrate how one could use the output of unpacking functions like `UnpackAddInput`, below is the implementation of the add function of the Calculator precompile:

```go
func add(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, AddGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the AddInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackAddInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    var output *big.Int // CUSTOM CODE FOR AN OUTPUT

    output = big.NewInt(0).Add(inputStruct.Value1, inputStruct.Value2)

    packedOutput, err := PackAddOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

## Packing Multiple Outputs

To understand how structs affect the packing of outputs, lets refer to `PackNextTwoOutput` for the Calculator precompile:

```go
// PackHashWithMd5Output attempts to pack given hash of type [16]
// PackNextTwoOutput attempts to pack given [outputStruct] of type NextTwoOutput
// to conform the ABI outputs.
func PackNextTwoOutput(outputStruct NextTwoOutput) ([]byte, error) {
    return CalculatorABI.PackOutput("nextTwo",
        outputStruct.Result1,
        outputStruct.Result2,
    )
}
```           
        
Notice here that even though we are no longer working with singular types, the generator still is able to pack our struct so that it is of the type bytes.

As a result, we are able to return the packed version of any `NextTwoOutput` struct as bytes at the end of nextTwo.


# Implementing Precompile (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/04-implementing-precompile)

---
title: Implementing Precompile
description: Learn how to implement the precompile in `contract.go`
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In this section, we will go define the logic for our CalculatorPlus precompile; in particular, we want to add the logic for the following three functions: `powOfThree`, `moduloPlus`, and `simplFrac`.

For those worried about this section - don't be! Our solution only added 12 lines of code to `contract.go`.

## Looking at Calculator

Before we define the logic of CalculatorPlus, we first will examine the implementation of the Calculator precompile:

```go
func add(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, AddGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the AddInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackAddInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
  
    _ = inputStruct          // CUSTOM CODE OPERATES ON INPUT
  
    var output *big.Int // CUSTOM CODE FOR AN OUTPUT

    output = big.NewInt(0).Add(inputStruct.Value1, inputStruct.Value2)

    packedOutput, err := PackAddOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
// ...

func repeat(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, RepeatGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the RepeatInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackRepeatInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct          // CUSTOM CODE OPERATES ON INPUT
  
    var output string // CUSTOM CODE FOR AN OUTPUT

    output = strings.Repeat(inputStruct.Text, int(inputStruct.Times.Int64()))

    packedOutput, err := PackRepeatOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// ...

func nextTwo(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, NextTwoGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the NextTwoInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackNextTwoInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
  
    _ = inputStruct          // CUSTOM CODE OPERATES ON INPUT
  
    var output NextTwoOutput // CUSTOM CODE FOR AN OUTPUT

    output.Result1 = big.NewInt(0).Add(inputStruct, big.NewInt(1))
    output.Result2 = big.NewInt(0).Add(inputStruct, big.NewInt(2))

    packedOutput, err := PackNextTwoOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

Although the code snippet above may be long, you might notice that we added only four lines of code to the autogenerated code provided to us by Precompile-EVM! In particular, we only added lines 19, 48, 79, and 80. In general, note the following:

- Structs vs Singular Values: make sure to keep track which inputs/outputs are structs and which one are values like big.Int. As an example, in `nextTwo`, we are dealing with a big.Int type input. However, in repeat, we are passed in a input of type struct RepeatInput.
- Documentation: for both Calculator and CalculatorPlus, the big package documentation is of great reference: https://pkg.go.dev/math/big 

Now that we have looked at the implementation for the Calculator precompile, its time you define the CalculatorPlus precompile!

## Implementing moduloPlus

We start by looking at the starter code for `moduloPlus`:

```go
func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the ModuloPlusInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackModuloPlusInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
    var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
    
    packedOutput, err := PackModuloPlusOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

We want to note the following:

- `inputStruct` is the input that we want to work with (i.e. `inputStruct` contains the two numbers that we want to use for the modulo calculation)
- All of our code will go after line 15
- We want the struct output to contain the result of our modulo operation (the struct will contain the multiple and remainder)

With this in mind, try to implement `moduloPlus`.

<Accordions>
<Accordion title="Solution">

```go
func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the ModuloPlusInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackModuloPlusInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
	output.Multiple, output.Remainder = big.NewInt(0).DivMod(inputStruct.Dividend, inputStruct.Divisor, output.Remainder)

	packedOutput, err := PackModuloPlusOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Implementing powOfThree

Likewise, for `powOfThree`, we want to define the logic of the function in the custom code section. However, note that while we are working with an output struct, our input is a singular value. With this in mind, take a crack at implementing `powOfThree`:

<Accordions>
<Accordion title="Solution">

```go
func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, PowOfThreeGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the PowOfThreeInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackPowOfThreeInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output PowOfThreeOutput // CUSTOM CODE FOR AN OUTPUT

	output.SecondPow = big.NewInt(0).Exp(inputStruct, big.NewInt(2), nil)
	output.ThirdPow = big.NewInt(0).Exp(inputStruct, big.NewInt(3), nil)
	output.FourthPow = big.NewInt(0).Exp(inputStruct, big.NewInt(4), nil)

	packedOutput, err := PackPowOfThreeOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Implementing simplFrac

For implementing `simplFrac`, note the following:

- The documentation for the big package will be of use here
- Remember to take care of the case when the denominator is 0

<Accordions>
<Accordion title="Solution">

```go
func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SimplFracGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the SimplFracInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSimplFracInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct            // CUSTOM CODE OPERATES ON INPUT
	var output SimplFracOutput // CUSTOM CODE FOR AN OUTPUT

	// If denominator is 0, return both 0
	if inputStruct.Denominator.Cmp(big.NewInt(0)) == 0 {
		output.SimplDenom = big.NewInt(0)
		output.SimplNum = big.NewInt(0)
	} else {
		// First, find common denominator
		var gcd big.Int
		gcd.GCD(nil, nil, inputStruct.Numerator, inputStruct.Denominator)

		// Now, simplify fraction
		output.SimplNum = big.NewInt(0).Div(inputStruct.Numerator, &gcd)
		output.SimplDenom = big.NewInt(0).Div(inputStruct.Denominator, &gcd)
	}

	packedOutput, err := PackSimplFracOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Final Solution

Below is the final solution for the CalculatorPlus precompile:

<Accordions>
<Accordion title="Solution">

```go
// Code generated
// This file is a generated precompile contract config with stubbed abstract functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package calculatorplus

import (
	"errors"
	"fmt"
	"math/big"

	"github.com/luxfi/subnet-evm/accounts/abi"
	"github.com/luxfi/subnet-evm/precompile/contract"
	"github.com/luxfi/subnet-evm/vmerrs"

	_ "embed"

	"github.com/ethereum/go-ethereum/common"
)

const (
	// Gas costs for each function. These are set to 1 by default.
	// You should set a gas cost for each function in your contract.
	// Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
	// There are some predefined gas costs in contract/utils.go that you can use.
	ModuloPlusGasCost uint64 = 1 /* SET A GAS COST HERE */
	PowOfThreeGasCost uint64 = 1 /* SET A GAS COST HERE */
	SimplFracGasCost  uint64 = 1 /* SET A GAS COST HERE */
)

// CUSTOM CODE STARTS HERE
// Reference imports to suppress errors from unused imports. This code and any unnecessary imports can be removed.
var (
	_ = abi.JSON
	_ = errors.New
	_ = big.NewInt
	_ = vmerrs.ErrOutOfGas
	_ = common.Big0
)

// Singleton StatefulPrecompiledContract and signatures.
var (

	// CalculatorplusRawABI contains the raw ABI of Calculatorplus contract.
	//go:embed contract.abi
	CalculatorplusRawABI string

	CalculatorplusABI = contract.ParseABI(CalculatorplusRawABI)

	CalculatorplusPrecompile = createCalculatorplusPrecompile()
)

type ModuloPlusInput struct {
	Dividend *big.Int
	Divisor  *big.Int
}

type ModuloPlusOutput struct {
	Multiple  *big.Int
	Remainder *big.Int
}

type PowOfThreeOutput struct {
	SecondPow *big.Int
	ThirdPow  *big.Int
	FourthPow *big.Int
}

type SimplFracInput struct {
	Numerator   *big.Int
	Denominator *big.Int
}

type SimplFracOutput struct {
	SimplNum   *big.Int
	SimplDenom *big.Int
}

// UnpackModuloPlusInput attempts to unpack [input] as ModuloPlusInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusInput(input []byte) (ModuloPlusInput, error) {
	inputStruct := ModuloPlusInput{}
	err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "moduloPlus", input)

	return inputStruct, err
}

// PackModuloPlus packs [inputStruct] of type ModuloPlusInput into the appropriate arguments for moduloPlus.
func PackModuloPlus(inputStruct ModuloPlusInput) ([]byte, error) {
	return CalculatorplusABI.Pack("moduloPlus", inputStruct.Dividend, inputStruct.Divisor)
}

// PackModuloPlusOutput attempts to pack given [outputStruct] of type ModuloPlusOutput
// to conform the ABI outputs.
func PackModuloPlusOutput(outputStruct ModuloPlusOutput) ([]byte, error) {
	return CalculatorplusABI.PackOutput("moduloPlus",
		outputStruct.Multiple,
		outputStruct.Remainder,
	)
}

// UnpackModuloPlusOutput attempts to unpack [output] as ModuloPlusOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusOutput(output []byte) (ModuloPlusOutput, error) {
	outputStruct := ModuloPlusOutput{}
	err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "moduloPlus", output)

	return outputStruct, err
}

func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the ModuloPlusInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackModuloPlusInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
	output.Multiple, output.Remainder = big.NewInt(0).DivMod(inputStruct.Dividend, inputStruct.Divisor, output.Remainder)

	packedOutput, err := PackModuloPlusOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// UnpackPowOfThreeInput attempts to unpack [input] into the *big.Int type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeInput(input []byte) (*big.Int, error) {
	res, err := CalculatorplusABI.UnpackInput("powOfThree", input)
	if err != nil {
		return new(big.Int), err
	}
	unpacked := *abi.ConvertType(res[0], new(*big.Int)).(**big.Int)
	return unpacked, nil
}

// PackPowOfThree packs [base] of type *big.Int into the appropriate arguments for powOfThree.
// the packed bytes include selector (first 4 func signature bytes).
// This function is mostly used for tests.
func PackPowOfThree(base *big.Int) ([]byte, error) {
	return CalculatorplusABI.Pack("powOfThree", base)
}

// PackPowOfThreeOutput attempts to pack given [outputStruct] of type PowOfThreeOutput
// to conform the ABI outputs.
func PackPowOfThreeOutput(outputStruct PowOfThreeOutput) ([]byte, error) {
	return CalculatorplusABI.PackOutput("powOfThree",
		outputStruct.SecondPow,
		outputStruct.ThirdPow,
		outputStruct.FourthPow,
	)
}

// UnpackPowOfThreeOutput attempts to unpack [output] as PowOfThreeOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeOutput(output []byte) (PowOfThreeOutput, error) {
	outputStruct := PowOfThreeOutput{}
	err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "powOfThree", output)

	return outputStruct, err
}

func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, PowOfThreeGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the PowOfThreeInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackPowOfThreeInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output PowOfThreeOutput // CUSTOM CODE FOR AN OUTPUT

	output.SecondPow = big.NewInt(0).Exp(inputStruct, big.NewInt(2), nil)
	output.ThirdPow = big.NewInt(0).Exp(inputStruct, big.NewInt(3), nil)
	output.FourthPow = big.NewInt(0).Exp(inputStruct, big.NewInt(4), nil)

	packedOutput, err := PackPowOfThreeOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// UnpackSimplFracInput attempts to unpack [input] as SimplFracInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracInput(input []byte) (SimplFracInput, error) {
	inputStruct := SimplFracInput{}
	err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "simplFrac", input)

	return inputStruct, err
}

// PackSimplFrac packs [inputStruct] of type SimplFracInput into the appropriate arguments for simplFrac.
func PackSimplFrac(inputStruct SimplFracInput) ([]byte, error) {
	return CalculatorplusABI.Pack("simplFrac", inputStruct.Numerator, inputStruct.Denominator)
}

// PackSimplFracOutput attempts to pack given [outputStruct] of type SimplFracOutput
// to conform the ABI outputs.
func PackSimplFracOutput(outputStruct SimplFracOutput) ([]byte, error) {
	return CalculatorplusABI.PackOutput("simplFrac",
		outputStruct.SimplNum,
		outputStruct.SimplDenom,
	)
}

// UnpackSimplFracOutput attempts to unpack [output] as SimplFracOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracOutput(output []byte) (SimplFracOutput, error) {
	outputStruct := SimplFracOutput{}
	err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "simplFrac", output)

	return outputStruct, err
}

func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SimplFracGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the SimplFracInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSimplFracInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct            // CUSTOM CODE OPERATES ON INPUT
	var output SimplFracOutput // CUSTOM CODE FOR AN OUTPUT

	// If denominator is 0, return both 0
	if inputStruct.Denominator.Cmp(big.NewInt(0)) == 0 {
		output.SimplDenom = big.NewInt(0)
		output.SimplNum = big.NewInt(0)
	} else {
		// First, find common denominator
		var gcd big.Int
		gcd.GCD(nil, nil, inputStruct.Numerator, inputStruct.Denominator)

		// Now, simplify fraction
		output.SimplNum = big.NewInt(0).Div(inputStruct.Numerator, &gcd)
		output.SimplDenom = big.NewInt(0).Div(inputStruct.Denominator, &gcd)
	}

	packedOutput, err := PackSimplFracOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// createCalculatorplusPrecompile returns a StatefulPrecompiledContract with getters and setters for the precompile.

func createCalculatorplusPrecompile() contract.StatefulPrecompiledContract {
	var functions []*contract.StatefulPrecompileFunction

	abiFunctionMap := map[string]contract.RunStatefulPrecompileFunc{
		"moduloPlus": moduloPlus,
		"powOfThree": powOfThree,
		"simplFrac":  simplFrac,
	}

	for name, function := range abiFunctionMap {
		method, ok := CalculatorplusABI.Methods[name]
		if !ok {
			panic(fmt.Errorf("given method (%s) does not exist in the ABI", name))
		}
		functions = append(functions, contract.NewStatefulPrecompileFunction(method.ID, function))
	}
	// Construct the contract with no fallback function.
	statefulContract, err := contract.NewStatefulPrecompileContract(nil, functions)
	if err != nil {
		panic(err)
	}
	return statefulContract
}
```

</Accordion>
</Accordions>


# Setting the ConfigKey & ContractAddress (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/05-set-configkey-contractaddr)

---
title: Setting the ConfigKey & ContractAddress
description: Learn how to set the ConfigKey, ContractAddress and register the Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## ConfigKey

Just as with the MD5 precompile in the previous section, go to the `module.go` file and set a `ConfigKey`.

## Contract Address

In the same file, set a `ContractAddress`. Choose one that has not been used by other precompiles of earlier sections.

## Registration

Go to the `plugin/main.go` file and register the new precompile.

# Creating Genesis Block with precompileConfig (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/06-create-genesis-block)

---
title: Creating Genesis Block with precompileConfig
description: Learn how to create a genesis block with precompileConfig.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In order to create a new Blockchain from our customized EVM, we have to define a Genesis block just as we did in out section earlier.

To incorporate the CalculatorPlus precompile as part of the genesis block, we need to create a new genesis file and include a key for the CalculatorPlus precompile in the configuration JSON. This key, in particular, is the `configKey` that we specified in the `module.go` file of the Calculator precompile in the previous section.

Copy over `Calculator.json` into a new file called `CalculatorPlus.json` and add the necessary key-pair value to the config.

<Accordions>
<Accordion title="Solution">

```json title="CalculatorPlus.json"
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "sha256Config": {
      "blockTimestamp": 0
    },
    "calculatorConfig": {
      "blockTimestamp": 0
    },
    "calculatorplusConfig" : {
        "blockTimestamp": 0
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

</Accordion>
</Accordions>

# Testing Precompiles via Go (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/07-testing-precompile)

---
title: Testing Precompiles via Go
description: Learn how to test your Precompiles using Golang.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

> Program testing can be used to show the presence of bugs, but never to show their absence. - Edsger W. Dijkstra

Let's once again examine the functions of the Calculator precompile and what each one does (in layman terms):

- `add`: computes the sum of two numbers
- `nextTwo`: returns the next two numbers that come after the input given 
- `repeat`: repeats a string N number of times

While we spent a good amount of time in the previous sections examining Calculator Solidity interface and the Go logic, we forgot to do one thing: *test the functionality of Calculator*.

But why test? For some, it may seems pointless to test such basic functions. However, testing all functions is important because it helps validate our belief that the logic of our functions is what we intended them to be.

In this section, we will focus on utilizing three types of tests for our Calculator precompile:

1. Autogenerated Tests
2. Unit Tests
3. Fuzz Tests

# Modify Autogenerated Tests (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/08-autogenerated-tests)

---
title: Modify Autogenerated Tests
description: Learn how to modify autogenerated tests in Go.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

The autogenerated tests will help us making sure, that our precompile throw an error in case not enough gas is supplied. To start, go to calculator/contract_test.go, where you will see the following:

```go
// Code generated
// This file is a generated precompile contract test with the skeleton of test functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package calculator

import (
    "testing"

    "github.com/luxfi/subnet-evm/core/state"
    "github.com/luxfi/subnet-evm/precompile/testutils"
    "github.com/luxfi/subnet-evm/vmerrs"
    "github.com/ethereum/go-ethereum/common"
    "github.com/stretchr/testify/require"
)

// These tests are run against the precompile contract directly with
// the given input and expected output. They're just a guide to
// help you write your own tests. These tests are for general cases like
// allowlist, readOnly behaviour, and gas cost. You should write your own
// tests for specific cases.
var (
    tests = map[string]testutils.PrecompileTest{
        "insufficient gas for add should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := AddInput{}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for nextTwo should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // set test input to a value here
                var testInput *big.Int
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for repeat should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := RepeatInput{}
                input, err := PackRepeat(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
    }
)

// TestCalculatorEmptyRun tests the Run function of the precompile contract.
func TestCalculatorEmptyRun(t *testing.T) {
    // Run tests.
    for name, test := range tests {
        t.Run(name, func(t *testing.T) {
            test.Run(t, Module, state.NewTestStateDB(t))
        })
    }
}

func BenchmarkCalculatorEmpty(b *testing.B) {
    // Benchmark tests.
    for name, test := range tests {
        b.Run(name, func(b *testing.B) {
            test.Bench(b, Module, state.NewTestStateDB(b))
        })
    }
}
```

There is a lot to digest in `contract_test.go`, but the file can be divided into the following three sections:

- Unit Tests
- TestCalculatorEmptyRun
- BenchmarkCalculator

The autogenerated unit tests are stored in the variable var, which is a mapping from strings (the description of the tests cases) to individual unit tests (`testutils.PrecompileTest`). Upon inspecting the keys of each pair, you will see that all three autogenerated unit tests are checking the same thing that: `add`, `nextTwo`, and `repeat` fail if not enough gas is provided. Each test expects to fail when supplying too little gas:

```go
{
  // ...
  SuppliedGas: RepeatGasCost - 1,
  ExpectedErr: vmerrs.ErrOutOfGas.Error(),
}
```

As of currently, if you attempt to build and run the test cases, you will not get very far because there is one step we need to do to: pass in arguments for each autogenerated unit test. For each variable testInput defined in each unit test, add an argument. What argument to put down does not matter, it just needs to be a valid argument. An example of what arguments to put in can be found below:

```go
var (
    tests = map[string]testutils.PrecompileTest{
        "insufficient gas for add should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := AddInput{big.NewInt(1), big.NewInt(1)}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for nextTwo should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // set test input to a value here
                // var testInput *big.Int
                testInput := big.NewInt(1)
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for repeat should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := RepeatInput{big.NewInt(1), "EGS"}
                input, err := PackRepeat(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
    }
)
```

Now run the test by running the following command from the project root:

```bash
./scripts/build_test.sh
```

# Adding Unit Tests (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/09-unit-tests)

---
title: Adding Unit Tests
description: Learn how to add unit tests.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Although the autogenerated units tests were useful in finding whether if the gas requirements of our functions were being fulfilled, we are yet to test the actual logic of our functions. We can add more unit tests by simply adding more mappings to the tests variable.

To start, lets define the tests that we want to write for each function within our Calculator precompile:

- `add`: check that **add(1, 2)** returns 3
- `nextTwo`: check that **nextTwo(1)** returns 2, 3
- `repeat`: check that **repeat(2, "EGS")** returns "EGSEGS"

With this in mind, lets add the three units tests to the tests variable! Below is a code excerpt which shows the three unit tests incorporated:

```go
var (
    expectedNextTwoOutcome, _ = PackNextTwoOutput(NextTwoOutput{big.NewInt(2), big.NewInt(3)})
    expectedRepeatOutcome, _  = PackRepeatOutput("EGSEGS")
    expectedAddOutcome        = common.LeftPadBytes(big.NewInt(3).Bytes(), common.HashLength)

    tests = map[string]testutils.PrecompileTest{
        "insufficient gas for add should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := AddInput{big.NewInt(1), big.NewInt(1)}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for nextTwo should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // set test input to a value here
                // var testInput *big.Int
                testInput := big.NewInt(1)
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for repeat should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := RepeatInput{big.NewInt(1), "EGS"}
                input, err := PackRepeat(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "testing add": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                value1 := big.NewInt(1)
                value2 := big.NewInt(2)
                testInput := AddInput{value1, value2}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedAddOutcome,
        },
        "testing nextTwo": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                testInput := big.NewInt(1)
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedNextTwoOutcome,
        },
        "testing repeat": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                baseString := "EGS"
                timesToRepeat := big.NewInt(2)
                input, err := PackRepeat(RepeatInput{timesToRepeat, baseString})
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedRepeatOutcome,
        },
    }
)
```


# Adding Fuzz Tests (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/10-fuzz-tests)

---
title: Adding Fuzz Tests
description: Learn how to add Fuzz tests.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Units tests are useful when comparing the outcome of a predetermined input with the expected outcome. If we wanted to check that our function works as expected for all given inputs, the only way to show this would be to test every possible input.

However, this is not possible for types such as uint256, as it would require us to test for 2^256 possible inputs. Even if we tested 1 input per second (or 2, 3, 4, 1000, etc.), this process would outlast the universe itself.

Rather than testing every possible output, we can strengthen our confidence of the expected behavior of a function by testing a random sample of inputs. By testing randomly, we can test for inputs that we wouldn't have originally thought of and are able to see how our function behaves over a range of values.

However, given that generating random inputs is not deterministic, we cannot use the tests variable itself. Rather, we will need to leverage the `TestCalculatorRun` function:

```go
// TestCalculatorEmptyRun tests the Run function of the precompile contract.
func TestCalculatorRun(t *testing.T) {
    // Run tests.
    for name, test := range tests {
        t.Run(name, func(t *testing.T) {
            test.Run(t, Module, state.NewTestStateDB(t))
        })
    }
}
```

The `TestCalculatorRun` function, by default, iterates through each unit test defined in the tests variable on runs said tests. However, we are not limited to just using `TestCalculatorRun` for the unit tests in tests. We can expand the functionality of `TestCalculatorRun` by adding our fuzz tests.

In particular, we can define the following logic for `TestCalculatorRun`:

- Iterate N number of times
- For each iteration, pick two numbers in the range from 0 to n
- After picking two random numbers, create a unit test with the two random numbers as inputs and execute said unit test

With this logic in mind, below is the code for how we would go about implementing fuzzing in `TestCalculatorRun`:

```go
// TestCalculatorRun tests the Run function of the precompile contract.
func TestCalculatorRun(t *testing.T) {
    // Run tests.
    for name, test := range tests {
        t.Run(name, func(t *testing.T) {
            test.Run(t, Module, state.NewTestStateDB(t))
        })
    }
    // Defining own test cases here
    N := 1_000
    n := new(big.Int).Exp(big.NewInt(2), big.NewInt(int64(128)), nil)

    // Fuzzing N times
    for i := 0; i < N; i++ {
        // Adding randomization test here
        randomInt1, err := rand.Int(rand.Reader, n)
        randomInt2, err := rand.Int(rand.Reader, n)
        // Expected outcome
        expectedRandOutcome := common.LeftPadBytes(big.NewInt(0).Add(randomInt1, randomInt2).Bytes(), common.HashLength)

        // Pack add input
        randTestInput := AddInput{randomInt1, randomInt2}
        randInput, err := PackAdd(randTestInput)
        require.NoError(t, err)

        randTest := testutils.PrecompileTest{
            Caller:      common.Address{1},
            Input:       randInput,
            SuppliedGas: AddGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedRandOutcome,
        }

        t.Run("Testing random sum!", func(t *testing.T) {
            randTest.Run(t, Module, state.NewTestStateDB(t))
        })

    }

}
```


# Testing CalculatorPlus (/academy/avalanche-l1/customizing-evm/08-calculator-precompile/11-test-calculatorplus)

---
title: Testing CalculatorPlus
description: Learn how to test CalculatorPlus precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Callout } from 'fumadocs-ui/components/callout';

Now that we have gone through an example of how to test the Calculator precompile, it is time that you develop your own tests for CalculatorPlus.

Rather than explicitly tell you what test cases to write, we decided to leave that to you. After all, testing is a subjective profession - a test suite that fits one security needs might be inadequate for someone else.

However, if you want an idea for what to test for, the following are some recommendations:

- Unit Tests: create some unit tests involving values that you can come up with. Ideally, write 3-5 unit tests for each function. 
- Fuzz Tests: test more than 1000 random inputs for each function

<Callout title="Note">For both unit and fuzz tests, make sure to account for the case when the denominator is equal to 0 in `simplFrac`.</Callout>

# Overview (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/00-intro)

---
title: Overview
description: Learn how to create a Hash Function Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---
import {Step, Steps} from 'fumadocs-ui/components/steps';

## What We're Building

In this section, we'll create a precompile for the MD5 hash function. By utilizing the existing Go library for this hash function, we can avoid reimplementing the algorithm in Solidity and take advantage of Go's superior efficiency.

<Accordions>
<Accordion title="What is a Hash Function?">

A hash function is a special type of function that takes input data of any size (such as a letter, a word, the text of a book, or even all combined texts available on the internet) and converts it into a fixed-size output. This output, known as a hash value, represents the original data. The process is often referred to as "hashing."

Hash functions possess several key properties:

- **Deterministic**: Given the same input, a hash function will always produce the same output. For instance, hashing the word "apple" a thousand times will yield the same hash value each time.
- **Fixed Size**: Regardless of the input data size—whether it's a single character or an entire novel—the hash function always produces an output (the hash value) of a consistent length.
- **Fast Computation**: Hash functions are designed to be quick and efficient, returning a hash value with minimal computational resources and time.
- **Preimage Resistance**: It's computationally infeasible to retrieve the original input data from the hash value alone. This property is especially crucial in cryptographic hash functions for data security.
- **Lux Effect**: A small change to the input should cause significant changes in the output, making the new hash value appear uncorrelated with the old one. For example, hashing "apple" and "Apple" should produce completely different hash values.
- **Collision Resistance**: It is highly unlikely for two different pieces of input data to yield the same hash value. However, due to the limited length of hash values, collisions are theoretically possible. A good hash function minimizes the occurrence of such collisions.

Hash functions are utilized in various applications across computer science, including data retrieval, data integrity verification, password storage, and in blockchain technology for cryptocurrencies like Bitcoin.

</Accordion>
</Accordions>

## Reference Implementation

To aid your understanding of building precompiles, we will compare each step with a reference example: a precompile for the SHA256 hash function. Both precompiles are quite similar, featuring a single function that returns the hashed value.

## Overview of Steps

Here's an overview of the steps involved:
<Steps>
<Step>
Create a Solidity interface for the precompile.
</Step>
<Step>
Generate the ABI.
</Step>
<Step>
Write the precompile code in Go.
</Step>
<Step>
Configure and register the precompile.
</Step>
<Step>
Build and run your customized EVM.
</Step>
<Step>
Connect Remix to your customized EVM and interact with the precompile.
</Step>
</Steps>
Let's get started!


# Create an MD5 Solidity Interface (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/01-create-solidity-interface)

---
title: Create an MD5 Solidity Interface
description: Learn how to create an MD5 Solidity Interface
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

The first step is defining the interface that will wrap the precompile implementation and that other contracts and users will interact with. In addition to declaring the way users can interact with our MD5 precompile, defining the MD5 interface will also allow us to utilize a generator script. A precompile consists of many files, and generating boilerplate Go files will make implementing the precompile much easier.

## SHA-256 Precompile Interface

Before defining the MD5 interface, we will first look at the interface of the very similar SHA-256 precompile. This reference implementation is included in the repository we have created earlier.

```solidity title="contracts/contracts/interfaces/ISHA256.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ISHA256 {
    /// Compute the hash of value
    /// @param value the value to be hashed
    /// @return hash the hash of the value
    function hashWithSHA256(string memory value) external view returns(bytes32 hash);
    }
```

ISHA256 contains a single function `hashWithSHA256`. `hashWithSHA256` takes in a value of type string, which is the value which is to be hashed, and outputs a 32-byte hash.

## Creating the Solidity Interface For The MD5 Precompile

Now it's your turn to define a precompile interface!

Create the interface for the MD5 hash function. Start by going into the same directory where `ISHA256.sol` lives (`contracts/contracts/interfaces/`) and create a new file named `IMD5.sol`. Note that:

&rarr; MD5 returns a 16-byte hash instead of a 32-byte hash

&rarr; Make sure to name all parameters and return values

<Accordions>
<Accordion title="Solution">

```solidity title="contracts/contracts/interfaces/IMD5.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface IMD5 {
    function hashWithMD5(string memory value) external view returns (bytes16 hash);
}
```

</Accordion>
</Accordions>

## Generate the ABI

Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the integrated VS Code terminal (control + \`), and change to the `/contracts` directory.

```bash
cd contracts
```

Run the command to compile the solidity interface to the ABI:

```bash
npx solc@latest --abi ./contracts/interfaces/IMD5.sol -o ./abis --base-path . --include-path ./node_modules
```

Rename the file:

```bash
mv ./abis/contracts_interfaces_IMD5_sol_IMD5.abi ./abis/IMD5.abi
```

Now, you should have a file called `IMD5.abi` in the folder `/contracts/abis` with the following content:

```json
[
    {
        "inputs": [
            {
                "internalType": "string",
                "name": "value",
                "type": "string"
            }
        ],
        "name": "hashWithMD5",
        "outputs": [
            {
                "internalType": "bytes16",
                "name": "hash",
                "type": "bytes16"
            }
        ],
        "stateMutability": "view",
        "type": "function"
    }
]
```


# Generate the Precompile (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/02-generate-the-precompile)

---
title: Generate the Precompile
description: Learn how to generate your precompile.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Terminal
comments: true
---

import { File, Files, Folder } from 'fumadocs-ui/components/files';

In the last section, we created the ABI for our precompile contract. Now, we'll use the precompile generation script provided by the precompile-evm template to generate a boilerplate code in go for the precompile implementation that will be wrapped in the solidity interface we created in the previous step.

## Running the Generation Script

To start, go to the root directory of your precompile-evm project: 

```bash
cd ..
```

Now generate the files necessary for the precompile.

```bash
./scripts/generate_precompile.sh --abi ./contracts/abis/IMD5.abi --type Md5 --pkg md5 --out ./md5
```

Now you should have a new directory in your root directory called `md5`:

<Files>
  <File name="LICENSE" />
  <File name="README.md" />
  <Folder name="contracts">
    <File name="..." />
  </Folder>
  <File name="go.mod" />
  <File name="go.sum" />
  <Folder name="sha256">
    <File name="..." />
  </Folder>
  <Folder name="md5" defaultOpen>
    <File name="README.md" />
    <File name="config.go" />
    <File name="config_test.go" />
    <File name="contract.abi" />
    <File name="contract.go" />
    <File name="contract_test.go" />
    <File name="module.go" />
  </Folder>
  <Folder name="plugin">
    <File name="main.go" />
  </Folder>
  <Folder name="scripts">
    <File name="build.sh" />
    <File name="..." />
  </Folder>
  <Folder name="tests">
    <File name="..." />
  </Folder>
</Files>

### `contract.go`

For the rest of this chapter, we'll work with the `md5/contract.go` file. If you generated the Go files related to your precompile, `contract.go` should look like the code below.

Do not be intimidated if much of this code does not make sense to you. We'll cover the different parts and add some code to implement the logic of our MD5 precompile.

```go
// Code generated
// This file is a generated precompile contract config with stubbed abstract functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package md5

import (
	"errors"
	"fmt"
	"math/big"

	"github.com/luxfi/subnet-evm/accounts/abi"
	"github.com/luxfi/subnet-evm/precompile/contract"
	"github.com/luxfi/subnet-evm/vmerrs"

	_ "embed"

	"github.com/ethereum/go-ethereum/common"
)

const (
	// Gas costs for each function. These are set to 1 by default.
	// You should set a gas cost for each function in your contract.
	// Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
	// There are some predefined gas costs in contract/utils.go that you can use.
	HashWithMD5GasCost uint64 = 1 /* SET A GAS COST HERE */
)

// CUSTOM CODE STARTS HERE
// Reference imports to suppress errors from unused imports. This code and any unnecessary imports can be removed.
var (
	_ = abi.JSON
	_ = errors.New
	_ = big.NewInt
	_ = vmerrs.ErrOutOfGas
	_ = common.Big0
)

// Singleton StatefulPrecompiledContract and signatures.
var (

	// Md5RawABI contains the raw ABI of Md5 contract.
	//go:embed contract.abi
	Md5RawABI string

	Md5ABI = contract.ParseABI(Md5RawABI)

	Md5Precompile = createMd5Precompile()
)

// UnpackHashWithMD5Input attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackHashWithMD5Input(input []byte) (string, error) {
	res, err := Md5ABI.UnpackInput("hashWithMD5", input)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}

// PackHashWithMD5 packs [value] of type string into the appropriate arguments for hashWithMD5.
// the packed bytes include selector (first 4 func signature bytes).
// This function is mostly used for tests.
func PackHashWithMD5(value string) ([]byte, error) {
	return Md5ABI.Pack("hashWithMD5", value)
}

// PackHashWithMD5Output attempts to pack given hash of type [16]byte
// to conform the ABI outputs.
func PackHashWithMD5Output(hash [16]byte) ([]byte, error) {
	return Md5ABI.PackOutput("hashWithMD5", hash)
}

// UnpackHashWithMD5Output attempts to unpack given [output] into the [16]byte type output
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackHashWithMD5Output(output []byte) ([16]byte, error) {
	res, err := Md5ABI.Unpack("hashWithMD5", output)
	if err != nil {
		return [16]byte{}, err
	}
	unpacked := *abi.ConvertType(res[0], new([16]byte)).(*[16]byte)
	return unpacked, nil
}

func hashWithMD5(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, HashWithMD5GasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the HashWithMD5Input.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackHashWithMD5Input(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct // CUSTOM CODE OPERATES ON INPUT

	var output [16]byte // CUSTOM CODE FOR AN OUTPUT
	packedOutput, err := PackHashWithMD5Output(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// createMd5Precompile returns a StatefulPrecompiledContract with getters and setters for the precompile.

func createMd5Precompile() contract.StatefulPrecompiledContract {
	var functions []*contract.StatefulPrecompileFunction

	abiFunctionMap := map[string]contract.RunStatefulPrecompileFunc{
		"hashWithMD5": hashWithMD5,
	}

	for name, function := range abiFunctionMap {
		method, ok := Md5ABI.Methods[name]
		if !ok {
			panic(fmt.Errorf("given method (%s) does not exist in the ABI", name))
		}
		functions = append(functions, contract.NewStatefulPrecompileFunction(method.ID, function))
	}
	// Construct the contract with no fallback function.
	statefulContract, err := contract.NewStatefulPrecompileContract(nil, functions)
	if err != nil {
		panic(err)
	}
	return statefulContract
}
```


# Packing and Unpacking (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/03-unpack-input-pack-output)

---
title: Packing and Unpacking
description: Learn how to unpack inputs and pack outputs.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

In this first segment of examining the `contract.go` file generated for us, we will go over the packing and unpacking functions in this file.   

## The Notion of Packing

Those eager to implement the MD5 algorithm might be wondering why we're discussing packing. However, there is good reason to discuss packing, and it comes down to the specification of the `staticcall` function in Solidity.

We begin by referring to the example of calling the SHA-256 precompiled contract:

```go
(bool ok, bytes memory out) = address(2).staticcall(abi.encode(numberToHash));
```

As seen above, the `staticcall` function accepts input in bytes format, generated by `abi.encode`, and returns a boolean value indicating success, along with a bytes format output.

Therefore, our precompiled contract should be designed to accept and return data in bytes format, involving the packing and unpacking of values. Since packing is a deterministic process, there's no concern about data corruption during translation. However, some preprocessing or postprocessing is necessary to ensure the contract functions correctly.

## Unpacking Inputs

In `contract.go`, the function `UnpackHashWithMd5Input` unpacks our data and converts it into a type relevant to us. It takes a byte array as an input and returns a Go string. We will look at more complex precompiles that have multiple functions that may take multiple inputs later.

```go
// UnpackHashWithMD5Input attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackHashWithMD5Input(input []byte) (string, error) {
    res, err := Md5ABI.UnpackInput("hashWithMD5", input)
    if err != nil {
        return "", err
    }
    unpacked := *abi.ConvertType(res[0], new(string)).(*string)
    return unpacked, nil
}
```

## Packing Outputs

Ignoring `hashWithMD5` for now, note that whatever value `hashWithMD5` outputs, we will need to postprocess it (i.e. pack it). `PackHashWithMD5Output` does just this, taking in an input of type [16]byte and outputting a byte array which can be returned by `staticcall`.

```go
// PackHashWithMd5Output attempts to pack given hash of type [16]byte
// to conform the ABI outputs.
func PackHashWithMd5Output(hash [16]byte) ([]byte, error) {
    return Md5ABI.PackOutput("hash_with_md5", hash)
}
```

This may seem trivial, but if our Solidity interface defined our function to return a uint or string, the type of our input to this function would differ accordingly.


# Implement the Precompile (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/04-implementing-precompile)

---
title: Implement the Precompile
description: Learn how to implement the Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Now, we'll implement the logic of the precompile in Go. We'll hash our string using the MD5 algorithm.

## SHA-256 Precompile Implementation

Before defining the logic of our MD5 precompile, let's look at the logic of the function `hashWithSHA256` (located in `sha256/contract.go`), which computes the SHA-256 hash of a string:

```go title="sha256/contract.go"
import (
    "crypto/sha256"
    //...
)

// ...

func hashWithSHA256(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, HashWithSHA256GasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the HashWithSHA256Input.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackHashWithSHA256Input(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct // CUSTOM CODE OPERATES ON INPUT

    var output [32]byte // CUSTOM CODE FOR AN OUTPUT

    output = sha256.Sum256([]byte(inputStruct))
    
    packedOutput, err := PackHashWithSHA256Output(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

As you can see, we're performing the following steps:

- Line 1: Importing the sha256 function from the crypto library (at the top of the Go file)
- Line 15: Unpacking the input to the variable inputStruct. It doesn't make sense that the variable has Struct in its name, but you will see why it is done like this when we have multiple inputs in a later example
- Line 24: Calling the sha256 function and assign its result to the output variable
- Line 26: Packing the output into a byte array
- Line 32: Returning the packed output, the remaining gas and nil, since no error has occurred

## Implementing the MD5 Precompile in `contract.go`

Go ahead and implement the `md5/contract.go` for the MD5 precompile. You should only have to write a few lines of code. If you're unsure which function to use, the following documentation might help: [Go Documentation Crypto/md5](https://pkg.go.dev/crypto/md5#Sum)

<Accordions>
<Accordion title="Solution">

```go title="md5/contract.go"
import (
	"crypto/md5"
	// ...
)

// ...

func hashWithMD5(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func hashWithMD5(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, HashWithMD5GasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the HashWithMD5Input.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackHashWithMD5Input(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct // CUSTOM CODE OPERATES ON INPUT

	var output [16]byte // CUSTOM CODE FOR AN OUTPUT
	output = md5.Sum([]byte(inputStruct))

	packedOutput, err := PackHashWithMD5Output(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

To solve this task, we did the following things:

- Import the md5 function from the crypto library
- Unpack the input to a variable inputStruct (It does not make sense that the variable has Struct in its name, but you will see why it is done like this when we have multiple inputs in a later example)
- Call the md5 function and assign it's result to the output variable
- Pack the output into a byte array
- Return the packed output, the remaining gas and nil, since no error has occurred

</Accordion>
</Accordions>

# ConfigKey, ContractAddress, and Genesis (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/05-configkey-and-contractaddr)

---
title: ConfigKey, ContractAddress, and Genesis
description: Learn how to set ConfigKey, ContractAddress, and update the genesis configuration.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Terminal
---

## Config Key

The precompile config key is used to configure the precompile in the `chainConfig`. It's set in the `module.go` file of our precompile.

The generator chooses an initial value that should be sufficient for many cases. In our case:

```go title="md5/module.go"
// ConfigKey is the key used in json config files to specify this precompile precompileconfig.
// must be unique across all precompiles.
const ConfigKey = "md5Config"
```
This key is used for each precompile in the geneis configuration to set the activation timestamp of the precompile.

## Contract Address

Each precompile has a unique contract address we can use to call it. This is the address we used earlier to instantiate the precompile in our solidity code or in remix when we interacted with the sha256 precompile.

```go title="md5/module.go"
// ContractAddress is the defined address of the precompile contract.
// This should be unique across all precompile contracts.
// See precompile/registry/registry.go for registered precompile contracts and more information.

var ContractAddress = common.HexToAddress("{ASUITABLEHEXADDRESS}") // SET A SUITABLE HEX ADDRESS HERE
```

The `0x01` range is reserved for precompiles added by Ethereum.

The `0x02` range is reserved for precompiles provided by Lux.

The `0x03` range is reserved for custom precompiles.

Lets set our contract address to `0x0300000000000000000000000000000000000002`

```go title="md5/module.go"
var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000002") // SET A SUITABLE HEX ADDRESS HERE
```

## Update Genesis Configuration
Now that the `ConfigKey` and `ContractAddress` are set, we need to update the genesis configuration to register the precompile.

```json title=".devcontainer/genesis-example.json"
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "sha256Config": {
      "blockTimestamp": 0
    },
    "md5Config": { // [!code highlight:3]
      "blockTimestamp": 0
    } 
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

# Register Your Precompile (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/06-register-precompile)

---
title: Register Your Precompile
description: Learn how to register your precompile.
updated: 2024-09-27
authors: [owenwahlgren]
icon: Terminal
---

The next step in developing our precompile is to **register it with precompile-evm**. Take a look at `plugin/main.go`. You should see the following file:

```go title="plugin/main.go"
// (c) 2019-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package main

import (
    "fmt"

    "github.com/luxfi/luxgo/version"
    "github.com/luxfi/subnet-evm/plugin/evm"
    "github.com/luxfi/subnet-evm/plugin/runner"

    // Each precompile generated by the precompilegen tool has a self-registering init function
    // that registers the precompile with the subnet-evm. Importing the precompile package here
    // will cause the precompile to be registered with the subnet-evm.
    // ADD YOUR PRECOMPILE HERE
    //_ "github.com/luxfi/precompile-evm/{yourprecompilepkg}"
)

const Version = "v0.1.4"

func main() {
    versionString := fmt.Sprintf("Precompile-EVM/%s Lux L1-EVM/%s [LuxGo=%s, rpcchainvm=%d]", Version, evm.Version, version.Current, version.RPCChainVMProtocol)
    runner.Run(versionString)
}
```

As of now, we do not have any precompile registered. To reigster a precompile, simply import the precompile package in the `plugin/main.go` file.

```go title="plugin/main.go"
// (c) 2019-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package main

import (
    "fmt"

    "github.com/luxfi/luxgo/version"
    "github.com/luxfi/subnet-evm/plugin/evm"
    "github.com/luxfi/subnet-evm/plugin/runner"

    // Each precompile generated by the precompilegen tool has a self-registering init function
    // that registers the precompile with the subnet-evm. Importing the precompile package here
    // will cause the precompile to be registered with the subnet-evm.
    _ "github.com/luxfi/precompile-evm/sha256"// [!code highlight:2]
    _ "github.com/luxfi/precompile-evm/md5" 
)

const Version = "v0.1.4"

func main() {
    versionString := fmt.Sprintf("Precompile-EVM/%s Lux L1-EVM/%s [LuxGo=%s, rpcchainvm=%d]", Version, evm.Version, version.Current, version.RPCChainVMProtocol)
    runner.Run(versionString)
}
```


# Build and Run (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/07-build-and-run)

---
title: Build and Run
description: Learn how to build and run your custom VM on a local network.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Terminal
---

Time to build and run your customized EVM. Follow the steps below to build and run your custom VM on a local network.

<Steps>
<Step>

### Build Your Custom VM

There's a simple build script in the Precompile-EVM we can utilize to build. First, make sure you are in the root folder of you Precompile-EVM:

```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
```

Then run the command to initiate the build script:

```bash
./scripts/build.sh
```

If you do not see any error, the build was successful.

</Step>
<Step>

### Create your blockchain configuration

You can run you customized Precompile-EVM by using the Lux CLI.

First, create the configuration for your blockchain with custom VM.

```bash
lux blockchain create myblockchain \
 --custom \
 --vm $VM_PATH \
 --genesis "./.devcontainer/genesis-example.json" \
 --force \
 --sovereign=false \
 --evm-token "TOK" \
 --warp \
 --icm
```

</Step>
<Step>

### Launch L1 with you customized EVM

Next, launch the Lux L1 with your custom VM:

```bash
lux blockchain deploy myblockchain --local
```

After around 1 minute the blockchain should have been created and some more output should appear in
the terminal. You'll also see the RPC URL of your blockchain in the terminal.
</Step>
</Steps>


# Interact with Precompile (/academy/avalanche-l1/customizing-evm/07-hash-function-precompile/08-interact-with-md5)

---
title: Interact with Precompile
description: Interact with the MD5 precompile we just deployed.
updated: 2024-08-27
authors: [owenwahlgren]
icon: Terminal
---

## Call Precompile from Foundry

Now we will call our MD5 precompile to generate a bytes16 hash of the input string.

**MD5 Precompile Address:** `0x0300000000000000000000000000000000000002`

```bash 
cast call --rpc-url myblockchain --private-key $PK 0x0300000000000000000000000000000000000002 "hashWithMD5(string)(bytes16)" "test"
```

You should see the bytes16 hash of the input string `test` as the output. 

```bash
0x098f6bcd4621d373cade4e832627b4f6
```

# What are Stateful Precompiles? (/academy/avalanche-l1/customizing-evm/09-stateful-precompiles/00-intro)

---
title: What are Stateful Precompiles?
description: Learn about Stateful Precompiles in Lux L1 EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

When building the MD5 and Calculator precompiles, we emphasized their behavior. We focused on building precompiles that developers could call in Solidity to perform some algorithm and then simply return a result.

However, one aspect that we have yet to explore is the statefulness of precompiles. Simply put, precompiles can store data which is persistent. To understand how this is possible, recall the interface that our precompile needed to implement:

```go
// StatefulPrecompiledContract is the interface for executing a precompiled contract
type StatefulPrecompiledContract interface {
    // Run executes the precompiled contract.
    Run(accessibleState AccessibleState, 
        caller common.Address, 
        addr common.Address, 
        input []byte, 
        suppliedGas uint64, 
        readOnly bool) 
        (ret []byte, remainingGas uint64, err error)
}
```

We also examined all parameters except for the `AccessibleState` parameter. As the name suggests, this parameter lets us access the blockchain's state. Looking at the interface of `AccessibleState`, we have the following:

```go
// AccessibleState defines the interface exposed to stateful precompile contracts
type AccessibleState interface {
    GetStateDB() StateDB
    GetBlockContext() BlockContext
    GetSnowContext() *snow.Context
}
```

Looking closer, we see that `AccessibleState` gives us access to **StateDB**, which is used to store the state of the EVM. However, as we will see throughout this section, `AccessibleState` also gives us access to other useful parameters, such as `BlockContext` and `snow.Context`.

## StateDB

The parameter we will use the most when it comes to stateful precompiles, StateDB, is a key-value mapping that maps:

- **Key**: a tuple consisting of an address and the storage key of the type Hash
- **Value**: any data encoded in a Hash, also called a word in the EVM

A Hash in go-ethereum is a 32-byte array. In this context, we do not refer to hashing in the cryptographic sense. Rather, "hashing a value" means encoding it to a hash, a 32-byte array usually represented in hexadecimal digits in Ethereum.

```go
const (
    // HashLength is the expected length of the hash
    HashLength = 32
)

// Hash represents the 32 byte of arbitrary data.
type Hash [HashLength]byte

// Example of a data encoded in a Hash: 
// 0x00000000000000000000000000000000000000000048656c6c6f20576f726c64
Below is the interface of StateDB:
// StateDB is the interface for accessing EVM state
type StateDB interface {
    GetState(common.Address, common.Hash) common.Hash
    SetState(common.Address, common.Hash, common.Hash)

    SetNonce(common.Address, uint64)
    GetNonce(common.Address) uint64

    GetBalance(common.Address) *big.Int
    AddBalance(common.Address, *big.Int)

    CreateAccount(common.Address)
    Exist(common.Address) bool

    AddLog(addr common.Address, topics []common.Hash, data []byte, blockNumber uint64)
    GetPredicateStorageSlots(address common.Address) ([]byte, bool)

    Suicide(common.Address) bool
    Finalise(deleteEmptyObjects bool)

    Snapshot() int
    RevertToSnapshot(int)
}
```

As you can see in the interface of the **StateDB**, the two functions for writing to and reading from the EVM state all work with the Hash type.

1. The function **GetState** takes an address and a Hash (the storage key) as inputs and returns the Hash stored at that slot.
2. The function **SetState** takes an address, a Hash (the storage key), and another Hash (data to be stored) as inputs.

We can also see that the **StateDB** interface allows us to read and write account balances of the native token (via GetBalance/SetBalance), check whether an account exists (via Exist), and some other methods.

## BlockContext

`BlockContext` provides info about the current block. In particular, we can get the current block number and the current block timestamp. Below is the interface of `BlockContext`:

```go
// BlockContext defines an interface that provides information to a stateful precompile about the current block.
// The BlockContext may be provided during both precompile activation and execution.
type BlockContext interface {
    Number() *big.Int
    Timestamp() *big.Int
}
```

An example of how we could leverage `BlockContext` in precompiles: *building a voting precompile that only accepts votes within a certain time frame*.

## snow.Context

`snow.Context` gives us info regarding the environment of the precompile. In particular, `snow.Context` tells us about the state of the network the precompile is hosted on. Below is the interface of `snow.Context`:

```go
// Context is information about the current execution.
// [NetworkID] is the ID of the network this context exists within.
// [ChainID] is the ID of the chain this context exists within.
// [NodeID] is the ID of this node
type Context struct {
    NetworkID uint32
    Lux L1ID  ids.ID
    ChainID   ids.ID
    NodeID    ids.NodeID
    PublicKey *bls.PublicKey

    XChainID    ids.ID
    CChainID    ids.ID
    LUXAssetID ids.ID

    Log          logging.Logger
    Lock         sync.RWMutex
    Keystore     keystore.BlockchainKeystore
    SharedMemory atomic.SharedMemory
    BCLookup     ids.AliaserReader
    Metrics      metrics.OptionalGatherer

    WarpSigner warp.Signer

    // chain consensus attributes
    ValidatorState validators.State // interface for Platform-Chain validators
    // Chain-specific directory where arbitrary data can be written
    ChainDataDir string
}
```

# Interacting with StringStore Precompile (/academy/avalanche-l1/customizing-evm/09-stateful-precompiles/01-interacting-with-precompile)

---
title: Interacting with StringStore Precompile
description: Learn how to interact with StringStore Stateful precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Rather than understanding the statefulness of precompiles only in theory, we can also play around with an example of a stateful precompile to learn how they work in practice.

In this section, we'll interact with the **StringStore** precompile, a precompiled smart contract that stores a string.

## Checking the Genesis JSON

As part of all Lux Academy branches, your Precompile-EVM should include the **StringStore/** folder along with all other relevant files for StringStore to be recognized by Precompile-EVM. This includes a genesis JSON for StringStore.

Go to `tests/precompile/genesis/` and double-check that you have a `StringStore.json` folder in said directory. This JSON files will instantiate both the **SHA256** precompile and **StringStore**.

```json title="StringStore.json"
{
    "config": {
      "chainId": 99999,
      // ...
      "stringStoreConfig" : {
        "blockTimestamp": 0,
        "defaultString": "Cornell"
     }
    },
    // ...
}
```

## Building the EVM with StringStore Precompile

The **lux-academy-start** branch already contains the StringStore and SHA256 precompile. If you are working from that branch, you can simply use the built binary from your latest exercise without making any changes.

To verify, check if the **stringstore** directory is in your workspace and if the precompile is noted in the `plugin/main.go` file. If not, switch to the **lux-academy-start** branch and build the VM there.

## Start the Lux Network

Use the Lux-CLI to start the server and the network. Use the provided genesis file `stringstore.json` mentioned above when you start the network.

If all goes well, you will have successfully deployed a blockchain containing both the StringStore and SHA256 precompile.

## Connecting Core

Similar to previous chapters, navigate to the **Add Network** section in the Core Wallet. You can find the RPC URL in the Lux-CLI logs or by executing the command: `lux blockchain list --deployed`

Note: Make sure the RPC URL ends with **/rpc**. The RPC URL should look something like this: http://127.0.0.1:9650/ext/bc/P9nKPGPoAfFGkdvD3Ac6YxZieaG8ahpbR9xZosrWNPbJCzByu/rpc

Once you have added the blockchain network, switch Core Wallet to your blockchain.

## Interact through Remix

We will now load in the Solidity interface letting us interact with the **StringStore** precompile. To do this, open the link below, which will open a Remix workspace containing the StringStore precompile: [Workspace](https://remix.ethereum.org/#url=https://github.com/luxfi/precompile-evm/blob/lux-academy-start/contracts/contracts/interfaces/IStringStore.sol&lang=en&optimize=false&runs=200&evmVersion=null&version=soljson-v0.8.26+commit.8a97fa7a.js)

As usual, we will need to compile our Solidity interface.

1. Click the **Solidity** logo on the left sidebar.
2. In the new page, you will see a **Compile IStringStore.sol** button. After clicking the button, a green checkmark should appear next to the Solidity logo.
3. Next, go to the **Environment** tab and select the **Injected Provider** option. If successful, a text saying **Custom [99999] Network** will appear below. If not, change your network.
4. Enter the precompile address (find it in `precompile/stringstore/module.go`) and click **At Address**.

First, we will call the `getString` function. By default, `getString` will return whatever was specified in the genesis JSON. Since we set our StringStore precompile to store the string **Cornell**, it'll return this value.



As you might have noticed, we can also set the string that **StringStore** stores. For example, if we wanted to change the string to Lux, we would type Lux in the box next to `setString` method, press the `setString` button, and then you would see in the Remix terminal a message displaying the success of your transaction.

If we call `getString` again, you will see that the string has been changed to Lux.

Congrats, you've just interacted with the stateful **StringStore** precompile 🎉

<Callout type="info">In contrast to the precompiles we have built earlier, the StringStore precompile has access to the EVM state. This way we can utilize precompile not only to perform calculations, but also persist something to the EVM state. This allows us to move even larger portions of our dApp from the solidity smart contract layer to the precompile layer. </Callout>


# Creating Counter Precompile (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/00-intro)

---
title: Creating Counter Precompile
description: Learn how to create a Stateful Counter Precompiles in Lux L1 EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

## What We Are Building

It's time to build our first stateful precompile. In particular, we'll build a counter that keeps track of an integer. Our Counter precompile will have the following logic:

- Users are able to get the current value of the counter
- Users are able to set a new value to the counter
- Users are able to increment the value of the counter

To help you understand, we've provided a reference stateful precompile: **StringStore**. As the name suggests, StringStore stores a string that users can change. This string is stored in the EVM state.

## Overview of Steps

Compared to the process before, we must also add tests for our precompile. Here's a quick overview of the steps we'll follow:

1. Create a Solidity interface for the precompile and generate the ABI
2. Generate the precompile Go boilerplate files
3. Write the precompile code in Go with access to the EVM state
4. Set the initial state in the configurator and register the precompile
5. Add and run tests
6. Build and run your customized EVM
7. Connect Remix to your customized EVM and interact with the counter

This tutorial will help you create more complex precompiles. Let's begin!


# Create Solidity Interface (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/01-create-solidity-interface)

---
title: Create Solidity Interface
description: Learn how to create a solidity interface for your counter precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Now, we'll create a Solidity interface for our Stateful Precompile.

## StringStore Solidity Interface

To start, let's look at the interface of the **StringStore** precompile:

```solidity title="contracts/contracts/interfaces/IStringStore.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface IStringStore {
    function getString() external view returns (string memory value);
    function setString(string memory value) external;
}
```

As seen above, we have the following two functions defined:

1. `getString`: retreives the string from the stateful precompile
2. `setString`: sets a string in the stateful precompile

## Create Solidity Interface for Counter

Create an interface for the counter in the same directory called `ICounter.sol`. Your interface should have the following three functions declared:

1. `getCounter`: returns the counter value from the stateful precompile
2. `incrementCounter`: when called, this function increments the current counter
3. `setCounter`: takes in a value, and sets it as the counter of the stateful precompile

For any argument/return value, make sure it is named as `value`.

<Accordions>
<Accordion title="Solution">

```solidity
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ICounter {

    function getCounter() external view returns (uint value);
    function incrementCounter() external;
    function setCounter(uint value) external;

}
```

</Accordion>
</Accordions>

## Generate the ABI

Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the terminal (control + \`), change to the `/contracts` directory, and run the command to compile the solidity interface to ABI:

```bash
# Move to contracts directory
cd contracts

# Compile ICounter.sol to ABI
npx solc@latest --abi ./contracts/interfaces/ICounter.sol -o ./abis --base-path . --include-path ./node_modules

# Rename 
mv ./abis/contracts_interfaces_ICounter_sol_ICounter.abi ./abis/ICounter.abi
```


# Store Data in EVM State (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/02-store-data-in-evm)

---
title: Store Data in EVM State
description: Learn how to store data in the EVM state.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Like all stateful machines, the EVM provides us with a way to save data. In particular, the EVM exposes a key-value mapping we can leverage to create stateful precompiles. The specifics of this mapping are as follows:

- Key: a tuple consisting of an address and the storage key of the type Hash
- Value: any data encoded in a Hash, also called a word in the EVM

## Storage Slots

Each storage slot is uniquely identified by the combination of an address and a storage key. To keep things organized, smart contracts and precompiles use their own address and a storage key to store data related to them. 

Look at the reference implementation `StringStore`. The storage key is defined in the second variable group in `contract.go`:

```go
// Singleton StatefulPrecompiledContract and signatures.
var (

    // StringStoreRawABI contains the raw ABI of StringStore contract.
    //go:embed contract.abi
    StringStoreRawABI string

    StringStoreABI = contract.ParseABI(StringStoreRawABI)

    StringStorePrecompile = createStringStorePrecompile()

    // Key that defines where our string will be stored
    storageKeyHash = common.BytesToHash([]byte("storageKey"))
)
```

We can use any string as our storage key. Then we convert it to a byte array and convert it to the hex representation.

> The common.BytesToHash is not hashing the string, but converting it to a 32 byte array in hex representation.

If we store multiple variables in the EVM state, we will define multiple keys here. Since we only use a single storage slot in this example, we can just call it `storageKey`.

At this point, we are not restricted in what state we can access from the precompile. We have access to the entire `stateDB` and can modify the entire EVM state including data other precompiles saved to state or balances of accounts. **This is very powerful, but also potentially dangerous**.

## Converting the Value to Hash Type

Since the StateDB only stores data of the type *Hash*, we need to convert all values to the type *Hash* before passing it to the **stateDB**.

### Converting Numbers

To convert numbers of type `big.Int`, we can utilize a function from the common package:

```go
valueHash := common.BigToHash(value)
```

Since the `big.Int` data structure already is 32-bytes long, the conversion is straightforward.

```go
// BigToHash sets byte representation of b to hash.
// If b is larger than len(h), b will be cropped from the left.
func BigToHash(b *big.Int) Hash { return BytesToHash(b.Bytes()) }
```

### Converting Strings

Converting strings is more challenging, since they are variable in length. Let's see an example:

```go
input := "Hello World"
```

To start, let's convert input into type bytes:

```go
inputAsBytes := []byte(input) 
// [72 101 108 108 111 32 87 111 114 108 100]
```

This is how you would convert input to type bytes in Go. Notice that the comment in the code snippet is the byte-representation of input, where each integer represents a byte. Right now, inputAsBytes is of length 11. We want it to be of length 32. Therefore, we pad `inputAsBytes`, adding however many zeros to the front until `inputAsBytes` has 32 integers:

```go
inputPadded := common.LeftPadBytes(inputAsBytes, common.HashLength) 
// [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 72 101 108 108 111 32 87 111 114 108 100]
```

In Go, we would do that using the function common.LeftPadBytes, which takes the byte array to be padded and the desired length. The desired length is supplied with the common.HashLength variable, which has the value 32. As seen in the comment, inputPadded is now of length 32. 

In the next step, we convert the bytes to a Hash with the function `common.BytesToHash`:

```go
inputHash := common.BytesToHash(inputPadded) 
// 0x00000000000000000000000000000000000000000048656c6c6f20576f726c64
```

## Helper Functions

To make the code reusable and keep the precompile function clean, it makes sense to create helper functions for converting and storing the data. The first one we'll see is StoreString:

```go
// StoreString sets the value of the storage key "storageKey" in the contract storage.
func StoreString(stateDB contract.StateDB, newValue string) {
    newValuePadded := common.LeftPadBytes([]byte(newValue), common.HashLength)
    newValueHash := common.BytesToHash(newValuePadded)
    stateDB.SetState(ContractAddress, storageKeyHash, newValueHash)
}
```

`StoreString` takes in the underlying key-value mapping, known as **StateDB**, and the new value, and updates the current string stored to be the new one. `StoreString` takes care of any type conversions and state management for us. Focusing now on `setString`, defining the logic is relatively easy. All we need to do is pass in **StateDB** and our string to `StoreString`.

Thus, we have the following:

```go
func setString(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, SetStringGasCost); err != nil {
        return nil, 0, err
    }
    if readOnly {
        return nil, remainingGas, vmerrs.ErrWriteProtection
    }
    // attempts to unpack [input] into the arguments to the SetStringInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackSetStringInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    // Get K-V Mapping
    currentState := accessibleState.GetStateDB()

    // Set the value
    StoreString(currentState, inputStruct)

    // this function does not return an output, leave this one as is
    packedOutput := []byte{}

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```


# Implementing setCounter (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/03-implement-set-counter)

---
title: Implementing setCounter
description: Learn how to implement the setCounter method.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Having seen how strings are stored in `StringStore`, its time for us to store integers with Counter. The thought process for this section can be defined as follows:

- Define the storage hash for our counter
- Implement `StoreCounterValue`, a helper function which acts like `StoreString` in the previous
- Implement `setCounter`

<Accordions>
<Accordion title="Solution">

```go title="contract.go"
// storageKeyHash
storageKeyHash = common.BytesToHash([]byte("counterValue"))

// StoreGreeting sets the value of the storage key in the contract storage.
func StoreCounterValue(stateDB contract.StateDB, value *big.Int) {
	// Convert uint to left padded bytes
	inputPadded := common.LeftPadBytes(value.Bytes(), 32)
	inputHash := common.BytesToHash(inputPadded)

	stateDB.SetState(ContractAddress, storageKeyHash, inputHash)
}

//setCounter sets the counter value in the contract storage.
func setCounter(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SetCounterGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// attempts to unpack [input] into the arguments to the SetCounterInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSetCounterInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE

	// Get the current state
	currentState := accessibleState.GetStateDB()

	// Set the value
	StoreCounterValue(currentState, inputStruct)

	// this function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

# Read Data From EVM State (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/04-read-date-from-evm)

---
title: Read Data From EVM State
description: Learn how to read the data from EVM state.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

In the section about storing data in the EVM, we learned about how to store our string in the EVM State. An equally important skill is how to read data from the EVM state.

In this section, we'll learn about how to retrieve our string from the EVM state.

## Defining Helper Function

Just like with setting the string in the EVM state, there are some conversions we'll have to perform to our string. In particular, we'll need to unhash the value stored in StateDB to get our original string. Thus, our helper function can be defined as follows:

```go
// GetString returns the value of the storage key "storageKey" in the contract storage,
// with leading zeroes trimmed.
func GetString(stateDB contract.StateDB) string {
    // Get the value set at recipient
    value := stateDB.GetState(ContractAddress, storageKeyHash)
    return string(common.TrimLeftZeroes(value.Bytes()))
}
```

With our helper function defined, we can implement the logic for `getString`. This will consists of retrieving the underlying key-value mapping and then passing it to `GetString`.

```go
func getString(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, GetStringGasCost); err != nil {
        return nil, 0, err
    }
    // no input provided for this function

    // CUSTOM CODE STARTS HERE

    var output string // CUSTOM CODE FOR AN OUTPUT

    currentState := accessibleState.GetStateDB()
    output = GetString(currentState)

    packedOutput, err := PackGetStringOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

# Implementing getCounter & increment (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/05-implement-getcounter-increment)

---
title: Implementing getCounter & increment
description: Learn how to implement getCounter and increment.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Having seen how to retrieve strings from the EVM state with the StoreString precompile, we are now ready to implement `getCounter`. Also, now that we are familiar with reading and writing to the EVM state, we can implement increment, which requires both read and write operations.

## Implementing getCounter

For `getCounter`, the following thought process is helpful:

- Create a helper function `GetCounterValue`, which takes in the current StateDB and returns the integer stored at the `storageKeyHash`
- In `getCounter`, get the current StateDB and pass it to `GetCounterValue`

<Accordions>
<Accordion title="Solution">

```go
// GetCounterValue gets the value of the storage key in the contract storage.
func GetCounterValue(stateDB contract.StateDB) *big.Int {
	// Get the value
	value := stateDB.GetState(ContractAddress, storageKeyHash)

	// Convert bytes to uint
	return new(big.Int).SetBytes(value.Bytes())
}

func getCounter(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, GetCounterGasCost); err != nil {
		return nil, 0, err
	}
	// no input provided for this function

	// Get the current state
	currentState := accessibleState.GetStateDB()
	// Get the value set at recipient
	value := GetCounterValue(currentState)

	packedOutput, err := PackGetCounterOutput(value)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Implementing increment

For increment, the following thought process is helpful:

- Get the current StateDB and pass it to GetCounterValue
- Once you have the current counter, increment it by one
- Store the new counter with StoreCounterValue

<Accordions>
<Accordion title="Solution">

```go
func incrementCounter(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, IncrementCounterGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// no input provided for this function

	// CUSTOM CODE STARTS HERE
	// Get the current state
	currentState := accessibleState.GetStateDB()

	// Get the value of the counter
	value := GetCounterValue(currentState)

	// Set the value
	StoreCounterValue(currentState, value.Add(value, big.NewInt(1)))

	// this function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

# Setting Base Gas Fees of Your Precompile (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/06-setting-base-gasfees)

---
title: Setting Base Gas Fees of Your Precompile
description: Learn how to set the base gas fees of your precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Gas is used for spam prevention. If our precompile is accessible to everyone on our Lux L1, it is important to set the gas cost in a way that lets users economically utilize it in their apps, yet prevents spammers from spamming our blockchain with calls to the precompile.

In this section, we'll modify the default values of the gas costs of our Calculator precompile. By default, all user-defined functions have a gas cost of 1. While this is good news for the average user, allowing users to call computationally expensive functions can leave our blockchain vulnerable to Denial-of-Service (DoS) attacks. 

We can find the default gas cost values for our functions in calculator/contract.go. Following the import statements, you should see:

```go title-"calculator/contract.go"
const (
    // Gas costs for each function. These are set to 1 by default.
    // You should set a gas cost for each function in your contract.
    // Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
    // There are some predefined gas costs in contract/utils.go that you can use.
    AddGasCost     uint64 = 1 /* SET A GAS COST HERE */
    NextTwoGasCost uint64 = 1 /* SET A GAS COST HERE */
    RepeatGasCost  uint64 = 1 /* SET A GAS COST HERE */
)
```

The variables `AddGasCost`, `NextTwoGasCost`, and `RepeatGasCost` are the gas costs of the `add`, `nextTwo`, and `repeat` functions, respectively. As you can see, they are currently set to 1.

However, changing the gas cost is as easy as changing the values themselves. As an example, change the gas costs to 7.


# Setting ConfigKey and ContractAddress (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/07-set-configkey-contractaddr)

---
title: Setting ConfigKey and ContractAddress
description: Learn how to set the ConfigKey and ContractAddress, and Register the Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## ConfigKey

Just as with the MD5 precompile in the previous section, go to the `module.go` file and set a ConfigKey.

## Contract Address

In the same file, set a ContractAddress. Choose one that has not been used by other precompiles of earlier sections.

# Initial State (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/08-initial-state)

---
title: Initial State
description: Setting the Initial State.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Throughout this chapter, we've covered storing variables in the EVM state. However, all of this was through the use of StringStore/Counter Solidity interface. An important part of stateful precompiles is the ability to initialize values stored by our precompiled contracts.

In the next few chapters, we'll see how to initialize the values of our precompiled contracts by manually setting the values or allowing for the values to be defined in the `genesis.json` file.

# Defining Default Values via Golang (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/09-define-default-values-via-go)

---
title: Defining Default Values via Golang
description: Learn how to set the default values of precompiled contracts using Go.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In this section, we'll cover defining default values of precompiled contracts using Go. We'll refer to StringStore for this section.

## Configure Function

To start, go to `StringStore/module.go` and scroll to the end of the file. There, you will find the Configure function:

```go
// Configure configures [state] with the given [cfg] precompileconfig.
// This function is called by the EVM once per precompile contract activation.
// You can use this function to set up your precompile contract's initial state,
// by using the [cfg] config and [state] stateDB.
func (*configurator) Configure(chainConfig precompileconfig.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, blockContext contract.ConfigurationBlockContext) error {
    config, ok := cfg.(*Config)
    if !ok {
        return fmt.Errorf("incorrect config %T: %v", config, config)
    }
    // CUSTOM CODE STARTS HERE
    return nil
}
```

Configure handles the initialization of a precompiled contract. We want to use Configure to define the default value for the string we are storing. 

But how? Configure gives us access to the StateDB (as one of the function parameters) and also lets us call any functions defined in `contract.go`. For example, if we wanted the default string to be "EGS," then we would just have to write one line of code:

```go
// Configure configures [state] with the given [cfg] precompileconfig.
// This function is called by the EVM once per precompile contract activation.
// You can use this function to set up your precompile contract's initial state,
// by using the [cfg] config and [state] stateDB.
func (*configurator) Configure(chainConfig precompileconfig.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, blockContext contract.ConfigurationBlockContext) error {
    config, ok := cfg.(*Config)
    if !ok {
        return fmt.Errorf("incorrect config %T: %v", config, config)
    }
    // CUSTOM CODE STARTS HERE
    StoreString(state, "EGS")

    return nil
}
```

We have just set a default value for our precompiled contract.

# Defining Default Values via Genesis (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/10-define-default-values-via-genesis)

---
title: Defining Default Values via Genesis
description: Learn how to set the default values of precompiled contracts using genesis JSON file.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In the last section, we saw how to initialize the default values of our precompiled contracts via the Configure function. While straightforward, it would be ideal for us (and developers who don't write in Go) to initialize default values via the genesis JSON. Here's how to do just that.

## Modifying config.go

The first step is to extract the value from the JSON file. Go to `config.go` and look at the Config struct:

```go
// Config implements the precompileconfig.Config interface and
// adds specific configuration for StringStore.
type Config struct {
    precompileconfig.Upgrade
    // CUSTOM CODE STARTS HERE
    // Add your own custom fields for Config here
}
```

Within the Config struct, we can find another struct: the Upgrade struct. It is not necessary to look at the definition of this struct. However, it is useful to know that this struct allows for the `blockTimestamp` key to be parsed in our `genesis.json` file. 

```go
"stringStoreConfig" : {
    "blockTimestamp": 0,
}
```

To pass in default values via the genesis JSON, we must complete the following:

- Define a key-value in the genesis JSON
- Update our Config struct so it is able to parse our new key-value

In the case of StringStore, after defining blockTimestamp, we will add another key-pair for our default string:

```go
"stringStoreConfig" : {
    "blockTimestamp": 0,
    "defaultString": "EGS"
}
```

Next, we will want to update our Config struct:

```go
type Config struct {
    precompileconfig.Upgrade
    // CUSTOM CODE STARTS HERE
    // Add your own custom fields for Config here
    DefaultString string `json:"defaultString,omitempty"`
}
```

In the above snippet, we are defining a new field of type string named `DefaultString`. With respect to its initialization, the value of `DefaultString` is derived from the JSON key `defaultString` from our genesis JSON (the value `json:"defaultString,omitempty"` tells Go to ignore the JSON field if we do not define it in our genesis JSON).

At this point, we have defined our new key-value pair in the genesis JSON and incorporated the logic so that precompile-evm can parse the new key-value.

However, one step remains. Although precompile-evm can parse the new key-value, we are not actually utilizing it anywhere. Our last-step is to update `Configure` method in `module.go` so it can read our new key-value pair.

```go
func (*configurator) Configure(chainConfig contract.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, _ contract.BlockContext) error {
    config, ok := cfg.(*Config)
    if !ok {
        return fmt.Errorf("incorrect config %T: %v", config, config)
    }
    // CUSTOM CODE STARTS HERE
    StoreString(state, config.DefaultString)

    return nil
}
```


# Testing Your Precompile (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/11-testing-precompile-hardhat)

---
title: Testing Your Precompile
description: Learn how to test your precompile using Hardhat.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Just like with the Calculator precompile, we want to test the functionality of our precompile to make sure it behaves as intended.

Although we can write tests in Go, this is not the only way we can test our precompile. We can leverage Hardhat, a popular smart contract testing framework, for testing.

In this section, we'll cover writing the smart contract component of our tests and setting up our testing environment so that precompile-evm can execute these tests for us.

## Structure of Testing with Hardhat

For `StringStore`, we'll need to complete the following tasks in order to leverage Hardhat:

1. Define the Genesis JSON file we want to use for testing
2. Tell precompile-evm what Hardhat script to use to test `StringStore` 
3. Write the smart contract that will hold the test cases for us
4. Write the actual script that will execute the Hardhat tests for us

## Defining the Genesis JSON

The easiest part of this tutorial, we will need to define the genesis state of our testing environment. For all intents and purposes, you can copy the genesis JSON that you used in the Defining Default Values section and paste it in `precompile-evm/tests/precompile/genesis`, naming it `StringStore.json` (it is important that you name the genesis file the name of your precompile).

## Telling Precompile-EVM What To Test

The next step is to modify `suites.go` and update the file so that precompile-evm can call the Hardhat tests for StringStore. Go to `precompile-evm/tests/precompile/solidity` and find `suites.go`. Currently, your file should look like the following:

```go title="suites.go"
// Copyright (C) 2019-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.
// Implements solidity tests.
package solidity

import (
    "context"
    "time"

    "github.com/luxfi/subnet-evm/tests/utils"
    ginkgo "github.com/onsi/ginkgo/v2"
)

var _ = ginkgo.Describe("[Precompiles]", ginkgo.Ordered, func() {
    utils.RegisterPingTest()
    // Each ginkgo It node specifies the name of the genesis file (in ./tests/precompile/genesis/)
    // to use to launch the subnet and the name of the TS test file to run on the subnet (in ./contract-examples/tests/)

    // ADD YOUR PRECOMPILE HERE
    /*
        ginkgo.It("your precompile", ginkgo.Label("Precompile"), ginkgo.Label("YourPrecompile"), func() {
            ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
            defer cancel()
​
            // Specify the name shared by the genesis file in ./tests/precompile/genesis/{your_precompile}.json
            // and the test file in ./contracts/tests/{your_precompile}.ts
            // If you want to use a different test command and genesis path than the defaults, you can
            // use the utils.RunTestCMD. See utils.RunDefaultHardhatTests for an example.
            utils.RunDefaultHardhatTests(ctx, "your_precompile")
        })
    */
})
```

If you view the comments generated, you will already see a general structure for how we can declare our tests for precompiles. Let's take this template and use it to declare the tests for StringStore!

```go title="suites.go"
// Copyright (C) 2019-2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.
// Implements solidity tests.
package solidity

import (
    "context"
    "time"

    "github.com/luxfi/subnet-evm/tests/utils"
    ginkgo "github.com/onsi/ginkgo/v2"
)

var _ = ginkgo.Describe("[Precompiles]", ginkgo.Ordered, func() {
    utils.RegisterPingTest()
    // Each ginkgo It node specifies the name of the genesis file (in ./tests/precompile/genesis/)
    // to use to launch the subnet and the name of the TS test file to run on the subnet (in ./contract-examples/tests/)

    // ADD YOUR PRECOMPILE HERE
    /*
        ginkgo.It("your precompile", ginkgo.Label("Precompile"), ginkgo.Label("YourPrecompile"), func() {
            ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
            defer cancel()
​
            // Specify the name shared by the genesis file in ./tests/precompile/genesis/{your_precompile}.json
            // and the test file in ./contracts/tests/{your_precompile}.ts
            // If you want to use a different test command and genesis path than the defaults, you can
            // use the utils.RunTestCMD. See utils.RunDefaultHardhatTests for an example.
            utils.RunDefaultHardhatTests(ctx, "your_precompile")
        })
    */

    ginkgo.It("StringStore", ginkgo.Label("Precompile"), ginkgo.Label("StringStore"), func() {
        ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
        defer cancel()

        utils.RunDefaultHardhatTests(ctx, "StringStore")
    })
})
```

Again, the naming conventions are important. We recommend you use the same name as your precompile whenever possible.

## Defining Test Contract

In contrast to using just Go, Hardhat allows us to test our precompiles using Solidity.

To start, create a new file called `StringStoreTest.sol` in `precompile-evm/contract/contracts`. We can start defining our file by including the following:

```solidity title="StringStoreTest.sol"
// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;

import "ds-test/src/test.sol"; 
import {IStringStore} from "../contracts/interfaces/IStringStore.sol";
```

As of right now, there are two important things to note.

We are first importing `test.sol`, a testing file that includes a range of assertion functions to assert that our outputs are as expected. In particular, these assertion functions are methods of the DSTest contract.

Next, we are importing the interface of the StringStore precompile that we want to test.

With this in mind, let's fill in the rest of our test file:

```solidity title="StringStoreTest.sol"
contract StringStoreTest is DSTest {

    IStringStore stringStore = IStringStore(0x0300000000000000000000000000000000000005);

    function step_getString() public {
        assertEq(stringStore.getString(), "Cornell");
    }

    function step_getSet() public {
        string memory newStr = "Apple";
        stringStore.setString(newStr);
        assertEq(stringStore.getString(), newStr);
    }
}
```

In the contract `StringStoreTest`, we are inheriting the DSTest contract so that we can leverage the provided assertion functions. Afterward, we are declaring the variable stringStore so that we can directly call the StringStore precompile. Next, we have the two testing functions.

Briefly looking at the logic of each test function:

- `step_getString`: We are testing that the getString function returns the default string defined in the genesis JSON (in this example, the default string is set to "Cornell")
- `step_getSet`: We are assigning a new string to our precompile and making sure that setString does so correctly

We now want to note the following two details regarding Solidity test functions in Hardhat:

- Any test functions that you want to be called must start with the prefix "step"
- The assertion function you use to check your outputs is `assertEq`

With our Solidity test contract defined, let's write actual Hardhat script! 

## Writing Your Hardhat Script

To start, go to `precompile-evm/contracts/test` and create a new file called `StringStore.ts`. It is important to name your TypeScript file the same name as your precompile. Here are the steps to take when defining our Hardhat script:

1. Specify the address at which our precompile is located
2. Deploy our testing contract so that we can call the test functions
3. Tell Hardhat to execute said test functions

To make our lives even easier, Lux L1-EVM (a library that Precompile-EVM leverages) has helper functions to call our test functions simply by specifying the names of the test functions. You can find the helper functions here: https://github.com/luxfi/subnet-evm/blob/master/contracts/test/utils.ts.

In the end, our testing file will look as follows:

```ts title="StringStore.ts"
// (c) 2019-2022, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

import { ethers } from "hardhat"
import { test } from "@luxfi/subnet-evm-contracts"
import { factory } from "typescript"

const STRINGSTORE_ADDRESS = "0x0300000000000000000000000000000000000005"

describe("StringStoreTest", function() {
    this.timeout("30s")

    beforeEach("Setup DS-Test", async function () {
        const stringStorePromise = ethers.getContractAt("IStringStore", STRINGSTORE_ADDRESS)

        return ethers.getContractFactory("StringStoreTest").then(factory => factory.deploy())
        .then(contract => {
          this.testContract = contract
          return contract.deployed().then(() => contract)
        })
    })

    test("Testing get function", "step_getString")

    test("Testing get and set function", "step_getSet")
})
```

## Running Your Hardhat Test

To run your HardHat tests, first change to the root directory of precompile-evm and run the following command:

```bash
./scripts/build.sh
```

Afterward, run the following command:

```bash
GINKGO_LABEL_FILTER=StringStore ./scripts/run_ginkgo.sh
```

The variable `GINKGO_LABEL_FILTER` simply tells precompile-evm which tests suite from `suites.go` to execute. Execute the `StringStore` test suite.

However, if you have multiple precompiles to test, set `GINKGO_LABEL_FILTER` equal to "Precompile." You should see something like the following:

```bash title="Combined output"
  StringStoreTest
    ✓ Testing get function (4126ms)
    ✓ Testing get and set function (4070ms)

  2 passing (12s)

  < Exit [It] StringStore - /Users/Rodrigo.Villar/go/src/github.com/luxfi/precompile-evm/tests/precompile/solidity/suites.go:40 @ 07/19/23 15:37:03.574 (16.134s)
• [16.134 seconds]
------------------------------
[AfterSuite] 
/Users/Rodrigo.Villar/go/pkg/mod/github.com/luxfi/subnet-evm@v0.5.2/tests/utils/command.go:85
  > Enter [AfterSuite] TOP-LEVEL - /Users/Rodrigo.Villar/go/pkg/mod/github.com/luxfi/subnet-evm@v0.5.2/tests/utils/command.go:85 @ 07/19/23 15:37:03.575
  < Exit [AfterSuite] TOP-LEVEL - /Users/Rodrigo.Villar/go/pkg/mod/github.com/luxfi/subnet-evm@v0.5.2/tests/utils/command.go:85 @ 07/19/23 15:37:03.575 (0s)
[AfterSuite] PASSED [0.000 seconds]
------------------------------

Ran 2 of 3 Specs in 50.822 seconds
SUCCESS! -- 2 Passed | 0 Failed | 0 Pending | 1 Skipped
PASS
```

Congrats, you can now write Hardhat tests for your stateful precompiles!


# Build Your Precompile (/academy/avalanche-l1/customizing-evm/10-stateful-counter-precompile/12-build-your-precompile)

---
title: Build Your Precompile
description: Learn how to build and run your precompile as a custom EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Build Your Custom VM

There's a simple build script in the Precompile-EVM we can utilize to build. First, make sure you are in the root folder of you Precompile-EVM:

```bash
cd $GOPATH/src/github.com/luxfi/precompile-evm
```

Then run the command to initiate the build script:

```bash
./scripts/build.sh
```

If you do not see any error, the build was successful.

## Run a Local Network with Your Custom VM

You can run you customized Precompile-EVM by using the Lux CLI.

First, create the configuration for your blockchain with custom VM.

```bash
lux blockchain create myblockchain --custom --vm $LUXGO_PLUGIN_PATH/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy --genesis ./.devcontainer/genesis-example.json
```

<Callout type="info">
Make sure you replace the binary name with the actual binary name of your Precompile-EVM, and genesis file with the actual path to your genesis file.
</Callout>

Next, launch the Lux L1 with your custom VM:

```bash
lux blockchain deploy myblockchain
```

After around 1 minute the blockchain should have been created and some more output should appear in the terminal. You'll also see the RPC URL of your blockchain in the terminal.

# Interoperability between blockchain (/academy/avalanche-l1/interchain-messaging/02-interoperability/01-interopability-between-blockchains)

---
title: Interoperability between blockchain
description: Learn about interoperability and it's importance in multichain systems
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="eLHOElbSw1k" />

Interoperability between blockchains refers to the ability of different blockchain networks to communicate and interact with one another in a seamless and coordinated manner. It allows these separate blockchain systems to share data, assets, or functionalities, enabling them to work together as if they were part of a single unified network.

These interactions can take many forms, including:

- Asset Bridging (Tokens, NFTs, etc.)
- DAO Voting across Chains
- Cross-Chain Liquidity Pools

As you will see soon, these different interactions are based on the same fundamentals of blockchains
exchanging messages. You can learn about some of them in the recording of this panel:

<YouTube id="Ef90eCRY5z0" />

## What you will learn

In this section, you will explore the following topics:

- **Source, Message, and Destination:** What is a message and what are the roles of the source and destination blockchain in interoperability?
- **Multi-Chain Systems:** A quick recap of multi-chain systems
- **Interoperability in Multi-Chain Systems:** Learn about the importance of interoperability to multi-chain systems

# Source, Message and Destination (/academy/avalanche-l1/interchain-messaging/02-interoperability/02-source-message-destination)

---
title: Source, Message and Destination
description:  Learn about interoperability and it's importance in multichain systems.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Interoperability is achieved by enabling blockchains to pass messages to one another. Each message originates from a source chain and is sent to one or more destination chains. These messages encode arbitrary data that can attest some event on the source chains, such as the deposit of an asset or the result of a vote.

<div class="flex space-x-8">
    <div class="flex-1">
        ![](/common-images/teleporter/source.png)
        # Source
        - Origin of communication
        - Sender calls contract
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/message.png)
        # Message
        - Contains source, destination, and encoded data
        - Signature guarantees  authenticity
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/destination.png)
        # Destination
        - Submission of message as transaction
        - Verifies signatures
    </div>
</div>

## Source Chain

The source chain in a cross-blockchain communication system refers to the original blockchain where data, assets, or information originate before being communicated to another blockchain. It acts as the starting point for initiating cross-chain interactions. When a user intends to communicate with another blockchain, they utilize protocols or smart contracts to initiate the communication process from the source chain.

## Message

The message is the data structure that will be sent to to the destination chain. It contains some metadata, the encoded message, and a signature. The signature attests the authenticity of the message, meaning that whatever the message claims has actually happened on the source chain. 

## Destination Chain

Conversely, the destination chain is the recipient blockchain where the communicated data, assets, or instructions will be received and processed. Validators, nodes, or protocols associated with the cross-blockchain communication system on the destination chain receive and authenticate the information relayed from the source chain. Once validated, the destination chain processes the data or executes the specified instructions.

<Quiz quizId="301"/>


# Recap of Multi-Chain Networks (/academy/avalanche-l1/interchain-messaging/02-interoperability/03-multi-chain-networks)

---
title: Recap of Multi-Chain Networks
description:  Learn about interoperability and it's importance in multichain systems
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---



Lux is a multi-chain network, meaning the network has multiple chains being validated in parallel, while other networks, such as Bitcoin and Ethereum only have single chain.

This feature provides greater scalability, independence, and customizability. Each blockchain is optimized for specialized use cases, boosting the network's overall performance.

## Transactions per Second (TPS) and Time to Finality (TTF)

To measure the performance of a blockchain, we can use two primary metrics: Time to finality (measured in seconds) and throughput (measured in transactions per second, TPS). To illustrate, we can think of a highway an as analogy.

![](/common-images/consensus/tps-vs-ttf.png)

Having a short time to finality is a short highway, taking a direct route from origin (submitting a transaction) to destination (finalization of the transaction) without any unnecessary detours. A finalized transaction is irreversibly written to the ledger. Once a transaction is final, users can be sure it has executed.

Having high transaction throughput is like having many lanes on the highway, meaning many cars (transactions) can use it at the same time. When building blockchain systems, we want to achieve high throughput.

## Scaling For The Masses

Different blockchain networks use different scaling approaches, such as Layer 2s, including roll-ups. Networks aim to maximize the throughput. Multi-chain systems have a simple, but incredible effective way of scaling. By running independent chains in parallel, the overall network can reach a massive combined throughput.

![](/common-images/multi-chain-architecture/combined-throughput.png)

While roll-ups may enable a very high-throughput of a single chain, they can never outcompete the combined throughput of a multi-chain system. This is because there's no limit to the number of chains that can run in parallel.

<Quiz quizId="302"/>


# Interoperability in Multi-Chain Systems (/academy/avalanche-l1/interchain-messaging/02-interoperability/04-interoperability-in-multi-chain-systems)

---
title: Interoperability in Multi-Chain Systems
description:  Learn about interoperability and it's importance in multichain systems
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Interoperability is crucial for multi-chain systems, as the price for easy scalability is fragmentation. However, this interoperability is equally important to all blockchain systems. Even though more dApps are based on the same chain in single-chain systems, many of them require interaction with other chains for liquidity or governance. Therefore, coming up with secure and efficient interoperability solutions is crucial for the entire blockchain space.

![](/common-images/multi-chain-architecture/vm-variety.png)

Lux, as a multi-chain system, provides flexibility on the execution and application layer but
also offers a standardized messaging protocol. The necessary cryptographic algorithms are
implemented in LuxGo, enabling cross-Lux L1 communication out of the box, even when the
application and execution layers of the chains may be completely different. The VMs can utilize
these modules to sign and verify messages, making interoperability between Lux L1s much easier
than between unrelated chains from different networks.

# Finality Importance in Interoperabile Systems (/academy/avalanche-l1/interchain-messaging/02-interoperability/05-finality-and-interoperability)

---
title: Finality Importance in Interoperabile Systems
description:  Learn about interoperability and it's importance in multichain systems
updated: 2024-06-10
authors: [andyvargtz]
icon: BookOpen
---

Finality is crucial for building cross-chain applications and interoperable systems because it ensures that transactions on the source chain are confirmed and immutable, therefore whatever action is triggered on the destination chain can securely be executed knowing the source chain won't revert the state induced by that cross chain message.


# Trusted Third Parties (/academy/avalanche-l1/interchain-messaging/02-interoperability/06-trusted-third-parties)

---
title: Trusted Third Parties
description: Learn about the challenges of cross-chain communication.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

# "Cross-chain communication is impossible without a trusted third party, contrary to common beliefs in the blockchain community"
- A. Zamyatin et al. in [SoK: Communication Across Distributed Ledgers](https://eprint.iacr.org/2019/1128.pdf)

Signature Schemes give us the tool to ensure the authenticity of message, but who will send these messages? Can we build a cross-chain communication protocol that does not introduce additional trust assumption?

The paper [SoK: Communication Across Distributed Ledgers](https://eprint.iacr.org/2019/1128.pdf) looks into this question and states that a CCC protocol must have the following attributes:

- **Effectiveness:** all relevant transactions are posted on their respective chains at the desired time
- **Atomicity:** either all transactions were posted on their respective chains at the desired time, or no transactions were posted at all 
- **Timeliness:** all transactions will eventually be posted on their respective chains

It is possible to create a cross-chain communication protocol that adheres to the three attributes mentioned above? Can a correct CCC protocol that is trustless exist?

In SoK, the researchers come to the conclusion that such a trustless, correct CCC protocol is impossible. Using computational complexity theory, the trustless, correct CCC protocol problem can be reduced into the Fair Exchange problem, a problem that has been proven to have no solution.

We see this also in practice. Many bridges and cross-chain communications often rely on some centralized infrastructure that observes the source chain and then delivers the message to the destination chain. Their users need to trust this setup, often involving a set of third-party bridge validators.

However, there might be a smart trick we can use. We'll explore this in the next section about Lux Warp Messaging.

# Lux Starter Kit (/academy/avalanche-l1/interchain-messaging/03-avalanche-starter-kit/01-avalanche-starter-kit)

---
title: Lux Starter Kit
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

The Lux Starter Kit provides a pre-configured GitHub Codespace environment with everything you need to develop cross-chain applications on Lux. This environment comes with:

- Foundry for smart contract development
- Docker support for running the ICM relayer
- Required VS Code extensions
- All necessary development tools

## What You Will Learn

In this section, you will:

- Launch your own GitHub Codespace
- Set up your Core wallet and get test tokens
- Configure your development environment
- Learn basic Foundry commands for contract interaction

By the end of this section, you'll have a fully configured environment ready for cross-chain development with Interchain Messaging

# Initial Setup (/academy/avalanche-l1/interchain-messaging/03-avalanche-starter-kit/02-set-up)

---
title: Initial Setup
description: Environment and Wallet Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import Link from 'next/link';
import { cn } from '@/utils/cn';
import { buttonVariants } from '@/components/ui/button.tsx'
import { Step, Steps } from 'fumadocs-ui/components/steps';

The Lux Starter Kit contains everything you need to get started quickly with Lux. The kit provides a self-contained environment with Foundry so you can follow the course without the need of installing anything else other than launching the environment.

In this course we will run the Lux Starter Kit in a hosted environment on Github. This is the quickest way to get started.

<Steps>
<Step>

### Create a Codespace

The quickest way to get started is using GitHub Codespaces, which provides a pre-configured development environment:

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=interchain-messaging&repo=769886086&machine=standardLinux32gb)

Wait a few minutes for the environment to build. You must be logged into GitHub to use Codespaces.

Alternatively, you can clone the repository:

<Link
    href="https://github.com/luxfi/lux-starter-kit/tree/interchain-messaging"
    className={cn(
    buttonVariants({ variant: 'default', className: 'mt-4' }),
    )}
    target='_blank'
>Open Lux Starter Kit</Link>

</Step>
<Step>

### Install Dependencies

Once your Codespace is ready, install the project dependencies:

```bash
forge install

# Optional: Mute Foundry nightly warning
export FOUNDRY_DISABLE_NIGHTLY_WARNING=1
```

</Step>
<Step>

### Set Up Core Wallet

1. Install Core wallet:
   - Visit [Core wallet website](https://core.app/download)
   - Download and install for your OS
   - Create a new wallet or import existing one

<Callout type="warn" title="If you created your wallet account with gmail or any other auth provider you will not have a private key" />

2. Get your [wallet credentials](https://support.lux.network/en/articles/8832783-core-extension-how-do-i-export-my-private-key):
   - Open Core wallet
   - Click your account name (top right)
   - Select "View Private Key"
   - Enter your password
   - Copy your:
     - Account address (0x...)
     - Private key (0x...)

<Callout type="warn" title="The private key is for testing only. Never use it in production or share it with anyone. Do not use a private key holding real funds on testnet, separate mainnet and testnet keys!" />

</Step>
<Step>

### Configure Environment

1. Create your environment file:
```bash
cp .env.example .env
```

2. Add your Core wallet credentials to `.env`:
```bash
# Your private key for signing transactions (for testing only, never use in production)
PK=your_private_key_here

# Your funded address (the address derived from your private key)
FUNDED_ADDRESS=your_funded_address_here

# Teleporter and chain configuration
# Testnet LUExchange-Chain, Dispatch & Echo have the same address, but this might no be the case for other L1s
TELEPORTER_REGISTRY_FUJI_DISPATCH=0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228
TELEPORTER_REGISTRY_FUJI_C_CHAIN=0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228

# Blockchain IDs pre-filled
FUJI_DISPATCH_BLOCKCHAIN_ID_HEX=0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7
FUJI_C_CHAIN_BLOCKCHAIN_ID_HEX=0x31233cae135e3974afa396e90f465aa28027de5f97f729238c310d2ed2f71902

# Incentevize a Relayer
FEE_TOKEN_ADDRESS=your_example_erc20_address
```

3. Load the environment:
```bash
source .env
```

4. Verify your configuration:
```bash
# Should show your wallet address
echo $FUNDED_ADDRESS
```

<Callout type="warn" title="The private key is for testing only. Never use it in production or share it with anyone. Do not use a private key holding real funds on testnet, separate mainnet and testnet keys!" />

</Step>
</Steps>

# Close and Reopen Codespace (/academy/avalanche-l1/interchain-messaging/03-avalanche-starter-kit/03-close-and-reopen-codespace)

---
title: Close and Reopen Codespace
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CloseAndReopen from "@/content/common/codespaces/close-and-reopen-codespace.mdx";

<CloseAndReopen />

# Getting Test Tokens (/academy/avalanche-l1/interchain-messaging/03-avalanche-starter-kit/04-networks)

---
title: Getting Test Tokens
description: Fund your wallet for development
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Before you can deploy contracts or send transactions, you'll need test tokens on both the Testnet LUExchange-Chain and Dispatch networks.

## Getting Test Tokens

1. Open Core wallet and switch to Testnet Testnet:
   - Click the network selector (top of window)
   - Select "Testnet (LUExchange-Chain)"

2. Get test tokens:
   - **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive tokens automatically on LUExchange-Chain and Dispatch
   - **Alternative:** Use external faucets:
     - Testnet LUExchange-Chain: [Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code **lux-academy**
     - Dispatch: [Faucet](https://core.app/tools/testnet-faucet/?subnet=dispatch&token=dispatch)

3. Verify your balances inside of the codespace, you should have **2 LUX** and **2 DIS**:
```bash
# Check balance on Testnet LUExchange-Chain
cast balance $FUNDED_ADDRESS --rpc-url testnet-c

# Check balance on Dispatch
cast balance $FUNDED_ADDRESS --rpc-url testnet-dispatch
```

You can also check your balance from the core extension, don't forget to toggle **testnet mode** inside the advanced settings.

## Available Networks

For this course, we'll be using two testnet networks:

### Testnet LUExchange-Chain
- RPC URL: https://api.lux-test.network/ext/bc/C/rpc
- Chain ID: 43113
- Native Token: LUX
- Teleporter Messenger: 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf
- Teleporter Registry: 0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228

### Dispatch Testnet
- RPC URL: https://subnets.lux.network/dispatch/testnet/rpc
- Chain ID: 779672
- Native Token: DISP
- Teleporter Messenger: 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf
- Teleporter Registry: 0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228

<Callout type="info">
Both networks are configured with the same Teleporter Messenger and Registry address for seamless cross-chain communication.
</Callout>

# Contract Development with Foundry (/academy/avalanche-l1/interchain-messaging/03-avalanche-starter-kit/05-foundry-quickstart)

---
title: Contract Development with Foundry
description: Deploy and interact with smart contracts
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Now that your environment is set up and funded, let's understand the key Foundry commands we'll be using throughout this tutorial.

## Understanding Foundry Commands

### forge create
The `forge create` command is used for deploying smart contracts. Key aspects:
- Requires an RPC URL to specify which network to deploy to
- Needs a private key for transaction signing
- Can handle constructor arguments if your contract needs them
- Returns the deployed contract's address
- Supports contract verification on block explorers

### cast send
`cast send` is used for state-changing interactions with contracts. This includes:
- Sending transactions that modify contract state
- Calling functions that require gas
- Approving token transfers
- Executing contract functions with parameters
- Requires private key for transaction signing

### cast call
`cast call` is for read-only operations that don't modify state:
- Reading contract state variables
- Calling view/pure functions
- Doesn't require gas or transaction signing
- Returns function results immediately
- Useful for verifying contract state

## Development Best Practices

1. Always test with small transactions first
2. Save contract addresses in environment variables
3. Double-check network configurations and addresses
4. Monitor transactions in block explorers
5. Keep private keys secure and never commit them

## Learn More

For more detailed information:
- [Foundry Book](https://book.getfoundry.sh/)
- [Lux Documentation](https://docs.lux.network/)
- [Teleporter Documentation](https://docs.lux.network/build/cross-chain/teleporter/overview)

# ICM Basics (/academy/avalanche-l1/interchain-messaging/04-icm-basics/01-icm-basics)

---
title: ICM Basics
description: Learn about the Lux Interchain Messaging basics.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="7QZ7_qZfQOA" />

Teleporter enables you to send messages from one blockchain to another blockchain in the Lux network by simply calling the `sendCrossChainMessage` on the `TeleporterMessenger` contract. This invokes a smart contract on another Lux L1, where the called contract implements the `ITeleporterReceiver` interface to receive messages on the destination Lux L1. We will look at what happens under the hood in a later chapter.

![](/common-images/teleporter/teleporter-source-destination.png)

## What You Will Learn

In this section, you will go through the following topics:

- **Recap: Bytes, Encoding, and Decoding:** Understand how data is encoded and decoded in bytes
- **Sending messages:** Write your first simple sender contract
- **Receiving messages:** Write your first simple receiver contract

## Exercise
You will apply your learned knowledge by building your first Cross-Chain application! This application will be deployed on two chains: the Testnet testnet (LUExchange-Chain) and the Dispatch test L1.

Therefore, you will deploy two contracts:

- **Sender on Testnet LUExchange-Chain:** Send a message with a simple string
- **Receiver on Dispatch test L1:** Receives the message and saves the most recent string

At the end of the section, you will be adapting the example to build an 'Adder'. This application is similar to the example above, but the message will include a number. The receiving contract keeps track of the sum of all sent numbers. 


# Recap of Bytes, Encoding and Decoding (/academy/avalanche-l1/interchain-messaging/04-icm-basics/02-recap-bytes-encoding-decoding)

---
title: Recap of Bytes, Encoding and Decoding
description: Recap message encoding/decoding.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

When we send an interchain message, we are just sending a single value of type bytes. This value can contain multiple values of various types (e.g. string, uint & address) using encoding and decoding. 

In this section we will recap these topics:

- **Bytes:** What is this data type and why are we using it? 
- **Encoding:** How do we turn values into bytes?
- **Decoding:** How can we turn the bytes back into the values?

We will use these concepts a lot going forward for our messages we send, so make sure you read this carefully.

## Bytes
In Solidity, the bytes data type serves as a versatile container for encoding multiple values of different types into a single unified value. You can think of it as a flexible box that can hold various forms of data, such as integers, text, images, or any binary information. The bytes data type allows you to mix and match these different types of data and put them all in one box.

This makes it a pragmatic choice for encapsulating diverse data and data type ensures that all the data is efficiently packaged into a single unit for transfer, and recipients can decode and extract the individual components as needed.

## Encoding & Decoding

In Solidity we can use the functions `abi.encode()` and `abi.decode()` for encoding and decoding. These are part of the solidity language, so we do not need to import anything to use them.

![Encoding and Decoding](/common-images/solidity/encoding-decoding.png)

### Encoding
When we encode data, we convert it into a byte array. This is useful when we want to send data from one contract to another. We can encode multiple values into a single byte array, which can then be decoded by the receiving contract.

```solidity
string memory someString = "test";
uint someNumber = 42;

bytes message = abi.encode(someString, someNumber);
```

This single value message here we can now use as a message for Teleporter.

### Decoding
When we decode data, we convert it from a byte array back into its original form. This is useful when we receive data from another contract. We can decode the byte array into its original values.

```solidity
( 
  string memory someString,
  uint someNumber
) = abi.decode(message, (string, uint));
```

This will give us back the original values that we encoded before. Note that we do need to know the types of the values and their order that we encoded to decode them correctly.

<Quiz quizId="303"/>

# Sending a Message (/academy/avalanche-l1/interchain-messaging/04-icm-basics/03-sending-a-message)

---
title: Sending a Message
description: Learn to send messages with Lux Interchain Messaging.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Sending a message is nothing more than a simple contract call to the Interchain Messaging messenger contract.

<img src="/common-images/teleporter/teleporter-source.png" width="400" class="mx-auto"/>

The dApp on the Source L1 has to call the `sendCrossChainMessage` function of the Interchain Messaging contract. The Interchain Messaging contract implements the `ITeleporterMessenger` interface below. Note that the dApp itself does not have to implement the interface.

```solidity title="/lib/icm-contracts/contracts/teleporter/ITeleporterMessenger.sol"
pragma solidity 0.8.18;

struct TeleporterMessageInput {
    bytes32 destinationBlockchainID;
    address destinationAddress;
    TeleporterFeeInfo feeInfo;
    uint256 requiredGasLimit;
    address[] allowedRelayerAddresses;
    bytes message;
}

struct TeleporterFeeInfo {
    address feeTokenAddress;
    uint256 amount;
}

/**
 * @dev Interface that describes functionalities for a cross chain messenger.
 */
interface ITeleporterMessenger {
    /**
     * @dev Emitted when sending a interchain message cross chain.
     */
 	event SendCrossChainMessage(
        uint256 indexed messageID,
        bytes32 indexed destinationBlockchainID,
        TeleporterMessage message,
        TeleporterFeeInfo feeInfo
    );

    /**
     * @dev Called by transactions to initiate the sending of a cross L1 message.
     */
	function sendCrossChainMessage(TeleporterMessageInput calldata messageInput)
        external
        returns (uint256);

}
```

The `sendCrossChainMessage` function takes `TeleporterMessageInput` struct as an input. In that multiple values are contained: This data will then be included in the payload of the Warp message:

- **`destinationChainID`:** The blockchainID in hex where the contract that should receive the message is deployed. This is not the EVM chain ID you may know from adding a network to a wallet, but the blockchain ID on the Platform-Chain. The Platform-Chain uses the transaction ID of the transaction that created those blockchain on the Platform-Chain for the chain ID, e.g.: 0xd7cdc6f08b167595d1577e24838113a88b1005b471a6c430d79c48b4c89cfc53
- **`destinationAddress`:** The address of the contract that should receive the message
- **`feeInfo`:** A struct consisting of a contract address of an ERC20 which the fee is paid in as well as the amount of tokens to be paid as an incentive for the relayer. We will look at this later in more detail.
- **`requiredGasLimit`:** The amount of gas the delivery of the message requires. If the relayer provides the required gas, the message will be considered delivered whether or not its execution succeeds, such that the relayer can claim their fee reward.
- **`allowedRelayerAddresses`:** An array of addresses of allowed relayers. An empty allowed relayers list means anyone is allowed to deliver the message. We will look at this later in more detail.
- **`message`:** The message to be sent as bytes. The message can contain multiple encoded values. DApps using Interchain Messaging are responsible for defining the exact format of this payload in a way that can be decoded on the receiving end. The message can hold multiple values that be encoded in a single bytes object. For example, applications may encode multiple method parameters on the sending side, then decode this data in the contract implementing the receiveTeleporterMessage function and call another contract with the parameters from there.

<Quiz quizId="304"/>

# Sender Contract (/academy/avalanche-l1/interchain-messaging/04-icm-basics/04-create-sender-contract)

---
title: Sender Contract
description: Create a contract to send messages with Teleporter.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Lets start by deploying our sender contract on LUExchange-Chain. It will be responsible for calling the the TeleporterMessenger contract, encoding our message and sending it to the destination chain. 

<Steps>
<Step>
### Read the Sender Contract

The following contract is located inside `contracts/interchain-messaging/send-receive` directory. Read through the contract below and and understand what is happening:

```solidity title="contracts/interchain-messaging/send-receive/senderOnCChain.sol"
// (c) 2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol"; // [!code highlight]

contract SenderOnCChain {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf); // [!code highlight]

    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress, string calldata message) external {
        messenger.sendCrossChainMessage( // [!code highlight]
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7, // [!code highlight]
                destinationAddress: destinationAddress, 
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(message)
            })
        );
    }
}
```

The key things to understand:

- **Importing ITeleporterMessenger (Line 8):** We are importing the `ITeleporterMessenger` Interface we looked at in the previous activity.
- **Defining teleporterMessenger contract (Line 12):** We are defining a `teleporterMessenger` contract using the imported interface. It is important to note, that our cross-chain dApp is not implementing the interface itself, but initializes a contract using that interface.
- **Sending the message (Line 21):** We are sending the message by calling the function of our `teleporterMessenger`. As an input we are defining a `TeleporterMessageInput`. The `destinationChainId` should be set to the Dispatch test L1's blockchain ID. We will need to provide the address of the receiving contract on the Dispatch test L1 as a parameter to the function, since we have not deployed it yet and don't know the address at this time.   
- **No fees (Line 25):** In this exercise we are not providing any fees to the relayer for relaying the message. This is only possible since the relayer we are running here is configured to pick up any message even if it does not provide any rewards.
- **Encoding the Message (Line 31):** The `TeleporterMessageInput` defines a message as an array of bytes. For now we will just simply encode the string with `abi.encode()`. In the future activities, you will see how we can encode multiple values of any type in that message.
- **Hardcoded destinationBlockchainId:** For this course, we are using Dispatch, but normally you will have to replace the `destinationBlockchainID` with whatever chain you want to send a message to.

</Step>
<Step>

### Deploy Sender Contract

To deploy a contract using Foundry use the following command:

```bash
forge create --rpc-url testnet-c --private-key $PK --broadcast contracts/interchain-messaging/send-receive/senderOnCChain.sol:SenderOnCChain
```
```
[⠊] Compiling...
[⠒] Compiling 2 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 81.53ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9 // [$SENDER_ADDRESS]
Transaction hash: 0xcde7873e9e3c68fb00a2ad6644dceb64a01a41941da46de5a0f559d6d70a1638
```
</Step>
<Step>

### Save Sender Address

Then save the sender contract address in an environment variable:

```bash
export SENDER_ADDRESS={your-sender-address}
```

</Step>
</Steps>

# Receiving a Message (/academy/avalanche-l1/interchain-messaging/04-icm-basics/05-receiving-a-message)

---
title: Receiving a Message
description: Learn to receive messages with Lux Interchain Messaging.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

To receive a message we need to enable our cross-L1 dApps to being called by the Interchain Messaging contract.



The Interchain Messaging does not know our contract and what functions it has. Therefore, our dApp on the destination L1 has to implement the ITeleporterReceiver interface. It is very straight forward and only requires a single method for receiving the message that then can be called by the Interchain Messaging contract:

```solidity
pragma solidity 0.8.18;

/**
 * @dev Interface that cross-chain applications must implement to receive messages from Teleporter.
 */
interface ITeleporterReceiver {
    /**
     * @dev Called by TeleporterMessenger on the receiving chain.
     *
     * @param originChainID is provided by the TeleporterMessenger contract.
     * @param originSenderAddress is provided by the TeleporterMessenger contract.
     * @param message is the TeleporterMessage payload set by the sender.
     */
    function receiveTeleporterMessage(
        bytes32 originChainID,
        address originSenderAddress,
        bytes calldata message
    ) external;
}
```

The function receiveTeleporterMessage has three parameters:

- **`originChainID`**: The chainID where the message originates from, meaning where the user or contract called the `sendCrossChainMessage` function of the Interchain Messaging contract
- **`originSenderAddress`**: The address of the user or contract that called the `sendCrossChainMessage` function of the Interchain Messaging contract on the origin L1
- **`message`**: The message encoded in bytes

An example for a contract being able to receive Interchain Messaging messages and storing these in a mapping could look like this:

```solidity
pragma solidity 0.8.18;

import "https://github.com/luxfi/teleporter/blob/main/contracts/src/Teleporter/ITeleporterMessenger.sol";
import "https://github.com/luxfi/teleporter/blob/main/contracts/src/Teleporter/ITeleporterReceiver.sol";

contract MessageReceiver is ITeleporterReceiver {
    // Messages sent to this contract.
    struct Message {
        address sender;
        string message;
    }
  
  	mapping(bytes32 => Message) private _messages;

    ITeleporterMessenger public immutable teleporterMessenger;

    // Errors
    error Unauthorized();

    constructor(address teleporterMessengerAddress) {
        teleporterMessenger = ITeleporterMessenger(teleporterMessengerAddress);
    }

    /**
     * @dev See {ITeleporterReceiver-receiveTeleporterMessage}.
     *
     * Receives a message from another chain.
     */
    function receiveTeleporterMessage(
        bytes32 originChainID,
        address originSenderAddress,
        bytes calldata message
    ) external {
      	// Only the Interchain Messaging receiver can deliver a message.
        if (msg.sender != address(teleporterMessenger)) {
            revert Unauthorized();
        }
      
        string memory messageString = abi.decode(message, (string));
        _messages[originChainID] = Message(originSenderAddress, messageString);
    }

}
```

This contract stores the last `Message` and it's sender of each chain it has received. When it is instantiated, the address of the Interchain Messaging contract is supplied to the constructor. The contract implements the `ITelepoterReceiver` interface and therefore we also implement the `receiveTeleporterMessage` function. 

<Quiz quizId="305"/>

# Receiver Contract (/academy/avalanche-l1/interchain-messaging/04-icm-basics/06-create-receiver-contract)

---
title: Receiver Contract
description: Create a contract to receive messages with Teleporter.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Now it's time to deploy our receiver contract to our L1. It will implement the callback for the `TeleporterMessenger` contract when the message is received, decoding our message and storing the last received string. 

<Steps>
<Step>

### Read the Receiver Contract

The following contract is located inside `contracts/interchain-messaging/send-receive` directory. Read through the contract below and and understand what is happening:

```solidity title="contracts/interchain-messaging/send-receive/receiverOnDispatch.sol"
// (c) 2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    string public lastMessage;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message.
        require(msg.sender == address(messenger), "ReceiverOnDispatch: unauthorized TeleporterMessenger");

        // Store the message.
        lastMessage = abi.decode(message, (string));
    }
}
```

**The key things to understand:**
- **Importing Interchain Messaging contracts (L8, L9):** We are importing the `ITeleporterMessenger` and `ITeleporterReceiver` interface we looked at in the previous activity.
- **Inheriting from ITeleporterReceiver (L11):** We are inheriting the interface that will require us to implement the `receiveTeleporterMessage()` function.
- **Defining the lastMessage variable (L14):** Setting the `lastMessage` variable as `public`, will make that variable readable from the outside without the need of a `getValue` function.
- **Implementing receiveTeleporterMessage (L16):** We implement the function that will be called when the message is received. Please note that we are not checking who calls that function for now. So anyone can pretend to deliver messages for now.
- **Decode message (L21):** We decode the message using `abi.decode(message, (string))`, which takes the bytes array as the first input and a tuple of the types of the encoded data in the message. Since our message only contains a single value, the tuple only has one value.

</Step>
<Step>

### Deploy Receiver Contract

To deploy a contract using Foundry use the following command:

```bash
forge create --rpc-url testnet-dispatch --private-key $PK contracts/interchain-messaging/send-receive/receiverOnDispatch.sol:ReceiverOnDispatch --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 2 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 158.51ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922 // [$RECEIVER_ADDRESS]
Transaction hash: 0x48a1ffaa8aa8011f842147a908ff35a1ebfb75a5a07eb37ae96a4cc8d7feafd7
```

<Step>
</Step>

### Save Receiver Contract Address

Then save the receiver contract address in an environment variable:

```bash
export RECEIVER_ADDRESS={your-receiver-address}
```

</Step>
</Steps>

# Send a Message (/academy/avalanche-l1/interchain-messaging/04-icm-basics/07-send-a-message)

---
title: Send a Message
description: Send your first Cross-Chain message with Teleporter.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

The final step, is to send the message between the two chains. Assuming everything went smooth so far, your local C-chain and your Lux L1 will have their corresponding parts of the sender/receiver deployed on them.

<Steps>
<Step>

### Send a Message

```bash
cast send --rpc-url testnet-c --private-key $PK $SENDER_ADDRESS "sendMessage(address,string)" $RECEIVER_ADDRESS "Hello"
```

A relayer will now take the message and deliver it to the destination.

</Step>
<Step>

### Verify Message was Received

Now let's check if the "Hello" string sent from our C-chain was actually stored properly on the `lastMessage` variable on our Lux L1. Run the following command replacing the receiver contract address.

```bash
cast call --rpc-url testnet-dispatch $RECEIVER_ADDRESS "lastMessage()(string)"
```

If the output says `Hello` then the message was successfully delivered and processed.

</Step>
</Steps>


Congratulations 🎉 You have just sent your first cross-chain message. This will be one of many to come!

# Adapt the contract (/academy/avalanche-l1/interchain-messaging/04-icm-basics/08-adapting-the-contract-exercise)

---
title: Adapt the contract
description: Assignment- Modify the Cross-Chain Messenger.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

To create a deeper understanding of the concepts, now change the provided contracts. Instead of sending a string, now send a number and add up the numbers on the destination chain:

Once you finished with the assignment you can review the correct answer at `/contracts/interchain-messaging/send-receive-assignment-solution` in the [Lux-Starter-Kit](https://github.com/luxfi/lux-starter-kit/tree/interchain-messaging/contracts/interchain-messaging/send-receive-assignment-solution)


# Two-Way Communication (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/01-two-way-communication)

---
title: Two-Way Communication
description: Learn about roundtrip messages.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

When we send messages with Interchain Messaging, we can check if a message has been delivered, but we do not get any feedback wether the message has been processed correctly or any return value. If we wanted to achieve this, we need to send a message back from the receiver to the original sender.

![](/common-images/teleporter/two-way-communication.png)

## What You Will Learn

In this section, you will go through the following topics:

- **Sender & Receiver:** Understand how we need to change the contracts to send a message back
- **Send & Track:** Send a roundtrip message and follow the logs
- **Adapt the example:** Take what you learned and adapt the example

## Exercises
You will apply your learned knowledge by building your first Cross-Chain application! This application will be deployed on two chains: the Testnet testnet (LUExchange-Chain) and the Dispatch test L1.

Therefore, you will deploy two contracts:

- **Sender on Testnet LUExchange-Chain:** Send a message with a simple string
- **Receiver on Dispatch test L1:** Receives the message, adds something to the string and send it back

At the end of the section, you will be adapting the example to build a cross-chain Lux L1 dApp that send a number to a contract on another Lux L1 then receives the result of a mathematical operation. This application is similar to the example above, but the message will include a number. The receiving contract will perform a mathematical operation. 

# Sender Contract (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/02-sender-contract)

---
title: Sender Contract
description: Adapt the sender contract to also receive messages
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

The sender contract has now two tasks: 

- **Send a message to the receiver**: Same as in the last example
- **Receive a message back from the receiver**: Now our sender contract needs to be able to receive a message back from the receiver.

Therefore, we need to change the sender contract to be able to receive a message back. We will need to implement the same interface `ITeleporterReceiver` as the receiver contract and implement the `receiveTeleporterMessage` function. 

```solidity title="contracts/interchain-messaging/send-roundtrip/senderOnCChain.sol"
// (c) 2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol"; // [!code highlight]

contract SenderOnCChain is ITeleporterReceiver { // [!code highlight]
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    string public roundtripMessage;

    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress) external {
        messenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode("Hello")
            })
        );
    }

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external { // [!code highlight:7]
        // Only the Interchain Messaging receiver can deliver a message.
        require(msg.sender == address(messenger), "SenderOnCChain: unauthorized TeleporterMessenger");

        // Store the message.
        roundtripMessage = abi.decode(message, (string));
    }
}
```

# Create the Sender Contract (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/03-create-sender-contract)

---
title: Create the Sender Contract
description: Deploy roundtrip sender contract
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Go ahead and deploy the sender contract on the LUExchange-Chain. 

<Steps>
<Step>

### Deploy the Sender Contract

```bash
forge create --rpc-url testnet-c --private-key $PK contracts/interchain-messaging/send-roundtrip/senderOnCChain.sol:SenderOnCChain --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 165.79ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0xA4cD3b0Eb6E5Ab5d8CE4065BcCD70040ADAB1F00 // [$SENDER_ADDRESS]
Transaction hash: 0x4f41cf829fbc525b64d9773c41dc9fabb3b93dfd03bf6c1568dcc4a4c6bdeb1a
```
</Step>
<Step>

### Update the Sender Address

Overwrite the `SENDER_ADDRESS` environment variable with the new address:

```bash
export SENDER_ADDRESS={your-sender-address}
```
</Step>
</Steps>

# Receiver Contract (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/04-receiver-contract)

---
title: Receiver Contract
description: Adapt the receiver contract to send messages back
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

The receiver contract now has two tasks: 

- **Receive a message from the sender**: Same as in the [last example](/academy/interchain-messaging/04-icm-basics/05-receiving-a-message)
- **Send a message back to the sender**: Now our receiver contract needs to be able to send a message back to the sender.

Therefore, we need to change the receiver contract to be able to send a message back. We will need to instantiate a `TeleporterMessenger` and call the `sendCrossChainMessage()` function. 

```solidity title="contracts/interchain-messaging/send-roundtrip/receiverOnDispatch.sol"
// (c) 2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol"; // [!code highlight]
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf); // [!code highlight]

    function receiveTeleporterMessage(bytes32 sourceBlockchainID, address originSenderAddress, bytes calldata message)
        external
    {
        // Only the Interchain Messaging receiver can deliver a message.
        require(msg.sender == address(messenger), "ReceiverOnDispatch: unauthorized TeleporterMessenger");

        // Send Roundtrip message back to sender
        string memory response = string.concat(abi.decode(message, (string)), " World!");

        messenger.sendCrossChainMessage( // [!code highlight:9]
            TeleporterMessageInput({
                // Blockchain ID of LUExchange-Chain
                destinationBlockchainID: sourceBlockchainID,
                destinationAddress: originSenderAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(response)
            })
        );
    }
}
```



# Create the Receiver Contract (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/05-create-the-receiver-contract)

---
title: Create the Receiver Contract
description: Deploy roundtrip receiver contract
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Go ahead and deploy the receiver contract:

<Steps>
<Step>

### Deploy the Receiver Contract

```bash
forge create --rpc-url testnet-dispatch --private-key $PK contracts/interchain-messaging/send-roundtrip/receiverOnDispatch.sol:ReceiverOnDispatch --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 101.71ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 // [$RECEIVER_ADDRESS]
Transaction hash: 0x11df9e14bdae4af60a618a900faa955d75e0ce7dd0f2ccc1ea6a764c149ef805
```

</Step>
<Step>

### Update the Receiver Address

Update the `RECEIVER_ADDRESS` environment variable with the new address:
```bash
export RECEIVER_ADDRESS={your-receiver-address}
```

</Step>
</Steps> 

# Send a Roundtrip Message (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/06-send-a-roundtrip-message)

---
title: Send a Roundtrip Message
description: Send roundtrip message
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Alright, now let's send the message:

<Steps>
<Step>
### Send the Message:

```bash 
cast send --rpc-url testnet-c --private-key $PK $SENDER_ADDRESS "sendMessage(address)" $RECEIVER_ADDRESS
```

</Step>
<Step>

### Verify Message Receipt

To check whether the message has been received, we can call the `roundtripMessage()` function on the sender contract. 

```bash
cast call --rpc-url testnet-c $SENDER_ADDRESS "roundtripMessage()(string)"
```
If successful, you should see the following output:
```bash
"Hello World!"
```

</Step>
{/* TODO: Add instructions for setting up and running the relayer in Docker before this section
<Step>

### Check the Relayer Logs

To understand in more detail what happened, check out the relayer logs:

```bash
lux interchain relayer logs
```

</Step>
*/}
</Steps>


# Adapt the Contracts (/academy/avalanche-l1/interchain-messaging/05-two-way-communication/07-adapt-the-contracts)

---
title: Adapt the Contracts
description: Assignment - Modify the roundtrip messenger dApp
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Taking what you've learned in the previous chapter, adapt the sender to send a number instead of a string. The receiver should now multiply the number by 2 and send it back to the sender. The sender saves the result in a public variable.

# Interchain Messaging Registry (/academy/avalanche-l1/interchain-messaging/07-icm-registry/01-icm-registry)

---
title: Interchain Messaging Registry
description: Learn about the Interchain Messaging Registry to manage multiple Interchain Messaging versions.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

When sending a message from the source chain we are calling the Interchain Messaging contract:

<img src="/common-images/teleporter/teleporter-source.png" width="400" class="mx-auto"/>

The TeleporterMessenger contract is non-upgradable. Once a version of the contract is deployed it cannot be changed. This is with the intention of preventing any changes to the deployed contract that could potentially introduce bugs or vulnerabilities. However, there could still be new versions of TeleporterMessenger contracts needed to be deployed in the future.

So far we used a fixed address for the TeleporterMessenger in all of our contracts. It is hardcoded in our contract. This is not a good practice, as it makes the contract less flexible and harder to upgrade.

```solidity
contract SenderOnCChain {

    ITeleporterMessenger public immutable teleporterMessenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf); // [!code highlight]

    function sendMessage(
        address destinationAddress,
        string calldata message
    ) external {
        teleporterMessenger.sendCrossChainMessage(
            // ...
        );
    }
}
```

While we could manually update the address of the used TeleporterMessenger in our contract, TeleporterRegistry provides us an easy way to use the latest version of TeleporterMessenger.

## What you will learn

In this section, you will explore the following topics:

- How the Interchain Messaging Registry works
- How to retrieve the latest version of the TeleporterMessenger on a blockchain


# How the ICM Registry works (/academy/avalanche-l1/interchain-messaging/07-icm-registry/02-how-the-icm-registry-works)

---
title: How the ICM Registry works
description: Learn about the different functionality available in the Interchain Messaging Registry.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

TeleporterRegistry keeps track of TeleporterMessenger contract versions. Cross-Lux L1 dApps can request the latest or a specific version of the TeleporterMessenger:

<img src="/common-images/teleporter/teleporter-registry.png" width="600" class="mx-auto"/>

Internally the TeleporterRegistry maintains a mapping of TeleporterMessenger contract versions to their addresses.

<img src="/common-images/teleporter/teleporter-registry-class-diagram.png" width="400" class="mx-auto"/>

Each registry's mapping of version to contract address is independent of registries on other blockchains, and chains can decide on their own registry mapping entries. So the contract of version 4 on one chain does not have to be equal to that version on another chain.

```solidity title="/lib/icm-contracts/contracts/teleporter/registry/TeleporterRegistry.sol"

contract TeleporterRegistry {
    // .... 
  
    // The latest protocol version. 0 means no protocol version has been added, and isn't a valid version.
    uint256 public latestVersion;

    // Mappings that keep track of the protocol version and corresponding contract address.
    mapping(uint256 version => address protocolAddress) private _versionToAddress;
    mapping(address protocolAddress => uint256 version) private _addressToVersion;
  
   // ...
}
```
In the `TeleporterRegistry` contract, the `latestVersion` state variable returns the highest version number that has been registered in the registry. The `getLatestTeleporter` function returns the `ITeleporterMessenger` that is registered with the corresponding version. Version zero is an invalid version, and is used to indicate that a `TeleporterMessenger` contract has not been registered yet.

```solidity title="/lib/icm-contracts/contracts/teleporter/registry/TeleporterRegistry.sol"
contract TeleporterRegistry {
    // .... 
  
  	// Mappings that keep track of the protocol version and corresponding contract address.
    mapping(uint256 version => address protocolAddress) private _versionToAddress;
  
    // The latest protocol version. 0 means no protocol version has been added, and isn't a valid version.
    uint256 public latestVersion;

    function getLatestTeleporter() external view returns (ITeleporterMessenger) {
        return ITeleporterMessenger(getAddressFromVersion(latestVersion));
    }

    function getAddressFromVersion(uint256 version) public view returns (address) {
        require(version != 0, "TeleporterRegistry: zero version");
        address protocolAddress = _versionToAddress[version];
        require(protocolAddress != address(0), "TeleporterRegistry: version not found");
        return protocolAddress;
    }
  
    // ...
}
```

If a cross-Lux L1 dApps prefers a specific version, it can also call directly the `getAddressFromVersion` function:

```solidity title="/lib/icm-contracts/contracts/teleporter/registry/TeleporterRegistry.sol"
contract TeleporterRegistry {
  	// Mappings that keep track of the protocol version and corresponding contract address.
    mapping(uint256 version => address protocolAddress) private _versionToAddress;
  
    // .... 
  
    function getAddressFromVersion(uint256 version) public view returns (address) {
        require(version != 0, "TeleporterRegistry: zero version");
        address protocolAddress = _versionToAddress[version];
        require(protocolAddress != address(0), "TeleporterRegistry: version not found");
        return protocolAddress;
    }
  
    // ...
}
```

If you are interested in the entire implementation, check it out [here](https://github.com/luxfi/teleporter/blob/main/contracts/teleporter/registry/TeleporterRegistry.sol).

<Quiz quizId="308"/>

# Interact with the ICM Registry (/academy/avalanche-l1/interchain-messaging/07-icm-registry/03-interact-with-the-registry)

---
title: Interact with the ICM Registry
description: Retrieve latest Interchain Messaging version using the Registry.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

The ICM Registry is already deployed on Testnet LUExchange-Chain, Dispatch, and Echo networks. You can use it to keep track of the latest ICM messenger version and its address.

### Retrieve Latest ICM Messenger Version

Let's interact with the Registry by getting the latest version of the Interchain Messaging Messenger deployed on Testnet LUExchange-Chain:

```bash
cast call --rpc-url testnet-c $TELEPORTER_REGISTRY_FUJI_C_CHAIN "latestVersion()(uint256)" 
```

The response should be something like this:

```bash
1
```

# Retrieving Interchain Messenger from the Registry (/academy/avalanche-l1/interchain-messaging/07-icm-registry/04-retrieving-icm-from-registry)

---
title: Retrieving Interchain Messenger from the Registry
description: Use Registry in a Cross-Chain dApp.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Let's now integrate the registry into a smart contract. Let's go back to the very simple string sending contract from the beginning:

```solidity title="contracts/interchain-messaging/registry/SenderOnCChainWithRegistry.sol"
pragma solidity ^0.8.18;

import "@teleporter/upgrades/TeleporterRegistry.sol"; // [!code highlight]
import "@teleporter/ITeleporterMessenger.sol";

contract SenderOnCChain {
    // The Interchain Messaging registry contract manages different Interchain Messaging contract versions. // [!code highlight:3]
    TeleporterRegistry public immutable teleporterRegistry = TeleporterRegistry(0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228);

    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress, string calldata message) external {
        ITeleporterMessenger messenger = teleporterRegistry.getLatestTeleporter();  // [!code highlight]

        messenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(message)
            })
        );
    }
}
```

The key things to understand:

- We are importing the `ITeleporterRegistry.sol` interface
- We have a variable for the registry address instead of the messenger address
- Before sending the message we get the latest version from the registry


# Verify if Sender is Interchain Messaging (/academy/avalanche-l1/interchain-messaging/07-icm-registry/05-verify-sender-is-icm)

---
title: Verify if Sender is Interchain Messaging
description: Safety verification of the message sender
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

We can also leverage the registry to check if `msg.sender` is a registered Interchain Messaging contract. Previously, we hardcoded this check in the contract:

```solidity
import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    string public lastMessage;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message. // [!code highlight:2]
        require(msg.sender == address(messenger), "ReceiverOnDispatch: unauthorized TeleporterMessenger");

        // Store the message.
        lastMessage = abi.decode(message, (string));
    }
}
```

If there was now a new Interchain Messaging contract version that would be used for sending messages, we would have to update the contract.

Instead, we can use the registry to check if the sender is a registered Interchain Messaging contract. 

```solidity
pragma solidity ^0.8.18;

import "@teleporter/upgrades/TeleporterRegistry.sol";
import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatchWithRegistry is ITeleporterReceiver {
    // The Interchain Messaging registry contract manages different Interchain Messaging contract versions.
    TeleporterRegistry public immutable teleporterRegistry = // [!code highlight:2]
        TeleporterRegistry(0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228); 

    string public lastMessage;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only a Interchain Messaging Messenger registered in the registry can deliver a message. // [!code highlight:3]
        // Function throws an error if msg.sender is not registered.
        teleporterRegistry.getVersionFromAddress(msg.sender);

        // Store the message.
        lastMessage = abi.decode(message, (string));
    }
}

# Invoking Functions (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/01-invoking-functions)

---
title: Invoking Functions
description: Learn how to invoke functions on destination.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="fl9bF7xzHXc" />

Well done, you successfully learned how to send simple data back and forth between blockchains. In this section we will look further and invoke a smart contract function on the destination chain. 

![](/common-images/teleporter/invoking-functions.png)

## What You Will Learn

In this section, you will go through the following topics:

- **Encoding:** Most smart contract functions have multiple parameters. So the first thing we will learn is how to encode multiple values in the message
- **Specify which function to call:** Most smart contracts have multiple functions. We will learn how to specify which function to call and encode different parameters depending on which function is been called

## Exercise

In this section you will apply the learned knowledge by building a cross-chain dApp where multiple functions are called on the destination chain.

- Build a Calculator that takes two parameters and adds them up
- Modify the Calculator to support more functions that can be called from the source Lux L1


# Encoding of multiple Values (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/02-encoding-multiple-values)

---
title: Encoding of multiple Values
description: Learn how to encode multiple function parameters
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

In this section, we will learn how to pack multiple values into a single message.

![](/common-images/teleporter/message-multiple-parameters.png)

We can use `abi.encode()` to encode multiple values into a single byte array:

```solidity
bytes message = abi.encode(
      someString,
      someNumber,
      someAddress
  );
```

Here we can see how the function `abi.encode()` is used to turn multiple values `(someString, someNumber & someAddress)` of various types `(string, uint & address)` into a single value of the type bytes called `message`. This bytearray can then be sent to the destination chain using the Teleporter. 

```solidity
function sendMessage(address destinationAddress) external returns (uint256 messageID) {
  string someString = "test";
  uint someNumber = 43;
  address someAddress = address(0);

  bytes message = abi.encode( // [!code highlight:4]
      someString,
      someNumber,
      someAddress
  );

  return teleporterMessenger.sendCrossChainMessage(
      TeleporterMessageInput({
        destinationChainID: destinationChainID,
        destinationAddress: destinationAddress,
        feeInfo: TeleporterFeeInfo({
          feeTokenAddress: feeContractAddress,
          amount: adjustedFeeAmount
        }),
        requiredGasLimit: requiredGasLimit,
        allowedRelayerAddresses: new address[](0),
        message: message // [!code highlight]
      })
  );
}
```

The receiving contract can then decode the byte array back into its original values:

```solidity
function receiveTeleporterMessage(
  bytes32 originChainID,
  address originSenderAddress,
  bytes calldata message
) external {
  // Only the Interchain Messaging receiver can deliver a message.
  if (msg.sender != address(teleporterMessenger)) {
    revert Unauthorized();
  }

  // Decoding the function parameters // [!code highlight:6]
  (
    string someString,
    uint256 someNumber,
    address someAddress
  ) = abi.decode(message, (string, uint256, address));
  
  // Calling the internal function
  _someFunction(someString, someNumber, someAddress) // [!code highlight]
  
}

function _someFunction(string someString, uint256 someNumber, address someAddress) private {
  // Do something
}
```


Here we are using `abi.decode()` to unpack the three values `(someString, someNumber & someAddress)` from the parameter `message` of the type `bytes`. As you can see, we need to provide the message as well as the types of values encoded in the message. It is important to note the types must be the same order as parameters to `abi.decode()`. 

```solidity
(
  string memory someString,
  uint someNumber,
  address someAddress
) = abi.decode(message, (string, uint, address));  // [!code highlight]
``` 
<Quiz quizId="306"/>

# Create Simple Calculator Sender (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/03-create-simple-calculator-sender)

---
title: Create Simple Calculator Sender
description: Create a contract that sends multiple parameters of a function
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Now, our goal is to create a dApp that works as a cross-Lux L1 Calculator, receiving multiple parameters and using those for a calculation. For now our calculator will only have the `Sum` function.

<Steps>
<Step>

### Create Sender Contract

On the Testnet LUExchange-Chain, we need to create the sender part of our cross-chain calculator. This will send two numbers (uint) to the receiver contract on the Dispatch test L1. 

```solidity title="contracts/interchain-messaging/invoking-functions/SimpleCalculatorSenderOnCChain.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";

contract SimpleCalculatorSenderOnCChain {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    function sendAddMessage(address destinationAddress, uint256 num1, uint256 num2) external {
        teleporterMessenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: encodeAddData(num1, num2)
            })
        );
    }

    //Encode helpers
    function encodeAddData(uint256 a, uint256 b) public pure returns (bytes memory) {
        bytes memory paramsData = abi.encode(a, b); // [!code highlight]
        return paramsData;
    }
}

```

To increase the readability of the code, we have created a helper function `encodeAddData` that encodes the two numbers into a single byte array.

</Step>
<Step>

### Deploy the Sender Contract

Deploy the sender contract on the Testnet LUExchange-Chain:

```bash
forge create --rpc-url testnet-c --private-key $PK contracts/interchain-messaging/invoking-functions/SimpleCalculatorSenderOnCChain.sol:SimpleCalculatorSenderOnCChain --broadcast
```
```
[⠊] Compiling...
[⠒] Compiling 1 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 84.20ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x789a5FDac2b37FCD290fb2924382297A6AE65860 // [$SENDER_ADDRESS]
Transaction hash: 0xd6cb47dd4ff38e4447711ebbec8b646b93f492f48e80b51719f860984cc25413
```
</Step>
<Step>

### Save the Sender Contract Address

Overwrite the `SENDER_ADDRESS` environment variable with the new address:

```bash
export SENDER_ADDRESS={your-sender-address}
```

</Step>
</Steps>

# Create Simple Calculator Receiver (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/04-create-simple-calulcator-receiver)

---
title: Create Simple Calculator Receiver
description: Create a contract that receives multiple parameters and execute a function
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

On the Dispatch test L1, we need to create the receiver part of our cross-chain calculator. It will receive two numbers and store the result. 

<Steps>
<Step>

### Create Receiver Contract

```solidity title="contracts/interchain-messaging/invoking-functions/SimpleCalculatorReceiverOnDispatch.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract SimpleCalculatorReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    uint256 public result_num;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message.
        require(
            msg.sender == address(teleporterMessenger), "CalculatorReceiverOnDispatch: unauthorized TeleporterMessenger"
        );

        (uint256 a, uint256 b) = abi.decode(message, (uint256, uint256)); // [!code highlight:2]
        _calculatorAdd(a, b);
    }

    function _calculatorAdd(uint256 _num1, uint256 _num2) internal {
        result_num = _num1 + _num2;
    }
}

```

</Step>
<Step>

### Deploy the Receiver Contract

Deploy the receiver contract on the Dispatch test L1:

```bash
forge create --rpc-url testnet-dispatch --private-key $PK contracts/interchain-messaging/invoking-functions/SimpleCalculatorReceiverOnDispatch.sol:SimpleCalculatorReceiverOnDispatch --broadcast
```

```
[⠊] Compiling...
[⠒] Compiling 1 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 44.12ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9 // [$RECEIVER_ADDRESS]
Transaction hash: 0x2d40c53b493556463a28c458e40bc455a248df69a10679bef84145974b7424f3
```

</Step>
<Step>

### Save the Receiver Contract Address

Overwrite the `RECEIVER_ADDRESS` environment variable with the new address:

```bash
export RECEIVER_ADDRESS={your-receiver-address}
```
</Step>
</Steps>


# Call simple Calculator (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/05-call-simple-calculator)

---
title: Call simple Calculator
description: Execute a function in one chain from another chain
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Alright, now let's call our Calculators:

<Steps>
<Step>

### Call the Sender Contract

```bash 
cast send --rpc-url testnet-c --private-key $PK $SENDER_ADDRESS "sendAddMessage(address, uint256, uint256)" $RECEIVER_ADDRESS 2 3
```

We need to call the `sendAddMessage` function on the sender contract with the address of the receiver contract and the two numbers we want to add. If you didn't export the sender and receiver address, you will get an executionr reverted error.

For this example we will add 2 + 3.

</Step>
<Step>

### Verify Message Receipt

To check wether the message has been received, we can call the `result_num()` function on the `Receiver` contract. 

```bash
cast call --rpc-url testnet-dispatch $RECEIVER_ADDRESS "result_num()(uint)"
```

```bash
5
```
2 + 3 = 5. Our cross-chain calculation was successful!
</Step>
</Steps>


# Encoding the Function Name (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/06-encoding-function-name)

---
title: Encoding the Function Name
description: Work with multiple functions in a single Cross-Chain dApp
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Great work. We can now pack multiple values into a message. In this section, we will learn how to encode the function name and, depending on it, its parameters in the message. Let's imagine a more advanced calculator that not only has a single `add` function but also a `concatenate` function, that lets you concatenate two strings. 

For the add function we need to encode two numbers. For the concatenate function we need to encode two strings. How can we go about this? The concept is easy: It's like packing an envelope into another envelope:

![](/common-images/teleporter/message-function-call.png)

## Ecoding the Function Name and Parameters

The first step is to create a `CalculatorAction` enum that specifies the different functions that can be called on the calculator. 

```solidity title="contracts/interchain-messaging/invoking-functions/CalculatorActions.sol"
pragma solidity ^0.8.18;

enum CalculatorAction {
    add,
    concatenate
}
```

In the next step we can add this to our `encode helpers` in the sender contract:

```solidity title="contracts/interchain-messaging/invoking-functions/CalculatorSenderOnCChain.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "./CalculatorActions.sol"; // [!code highlight]

contract CalculatorSenderOnCChain {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    function sendAddMessage(address destinationAddress, uint256 num1, uint256 num2) external {
        teleporterMessenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: encodeAddData(num1, num2) // [!code highlight]
            })
        );
    }

    function sendConcatenateMessage(address destinationAddress, string memory text1, string memory text2) external {
        teleporterMessenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: encodeConcatenateData(text1, text2) // [!code highlight]
            })
        );
    }

    // Encode helpers
    function encodeAddData(uint256 a, uint256 b) public pure returns (bytes memory) {
        bytes memory paramsData = abi.encode(a, b); // [!code highlight:2]
        return abi.encode(CalculatorAction.add, paramsData);
    }

    function encodeConcatenateData(string memory a, string memory b) public pure returns (bytes memory) {
        bytes memory paramsData = abi.encode(a, b); // [!code highlight:2]
        return abi.encode(CalculatorAction.concatenate, paramsData);
    }
}
```

As you can see here we are calling `abi.encode` twice in the encode helpers. The first time we encode the function parameters and the second time we encode the function name with the byte array containing parameters.

## Decode the Function Name and Parameters

Let's now look at the receiver:

```solidity title="contracts/interchain-messaging/invoking-functions/CalculatorReceiverOnDispatch.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";
import "./CalculatorActions.sol";

contract CalculatorReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);
    uint256 public result_num;
    string public result_string;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message.
        require(
            msg.sender == address(teleporterMessenger), "CalculatorReceiverOnDispatch: unauthorized TeleporterMessenger"
        );

        // Decoding the Action type: // [!code highlight:2]
        (CalculatorAction actionType, bytes memory paramsData) = abi.decode(message, (CalculatorAction, bytes)); 

        // Route to the appropriate function. // [!code highlight:10]
        if (actionType == CalculatorAction.add) {
            (uint256 a, uint256 b) = abi.decode(paramsData, (uint256, uint256));
            _calculatorAdd(a, b);
        } else if (actionType == ...) {
            (string memory text1, string memory text2) = abi.decode(paramsData, (string, string));
            _calculatorConcatenateStrings(text1, text2);
        } else {
            revert("CalculatorReceiverOnDispatch: invalid action");
        }
    }

    function _calculatorAdd(uint256 _num1, uint256 _num2) internal {
        result_num = _num1 + _num2;

    }

    function _calculatorConcatenateStrings(string memory str1, string memory str2) internal {
        bytes memory str1Bytes = bytes(str1);
        bytes memory str2Bytes = bytes(str2);

        bytes memory combined = new bytes(str1Bytes.length + str2Bytes.length + 1);

        for (uint256 i = 0; i < str1Bytes.length; i++) {
            combined[i] = str1Bytes[i];
        }
        combined[str1Bytes.length] = " ";
        for (uint256 i = 0; i < str2Bytes.length; i++) {
            combined[str1Bytes.length + i + 1] = str2Bytes[i];
        }

        result_string = string(combined);
    }
}
```

You can see that we first decode the `CalculatorAction` enum:

```solidity
// Decoding the Action type: 
(CalculatorAction actionType, bytes memory paramsData) = abi.decode(message, (CalculatorAction, bytes)); 
```

Then based on the function name we decide how to unpack the parameters

```solidity
// Route to the appropriate function. 
if (actionType == CalculatorAction.add) {
    (uint256 a, uint256 b) = abi.decode(paramsData, (uint256, uint256)); // [!code highlight]
    _calculatorAdd(a, b);
} else if (actionType == ...) {
    (string memory text1, string memory text2) = abi.decode(paramsData, (string, string)); // [!code highlight]
    _calculatorConcatenateStrings(text1, text2);
} else {
    revert("CalculatorReceiverOnDispatch: invalid action");
}
```

For the `add` function we decode two numbers and for the `concatenate` function we decode two strings. After the decoding we call the appropriate internal function.

## Try it Out

Deploy the sender and receiver contracts and try out the `add` and `concatenate` functions. 

<Steps>
<Step>

### Deploy the Sender Contract

```bash
forge create --rpc-url testnet-c --private-key $PK contracts/interchain-messaging/invoking-functions/CalculatorSenderOnCChain.sol:CalculatorSenderOnCChain --broadcast
```
```
[⠃] Compiling...
[⠆] Compiling 2 files with Solc 0.8.18
[⠰] Solc 0.8.18 finished in 240.23ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x8B3BC4270BE2abbB25BC04717830bd1Cc493a461 // [$SENDER_ADDRESS]
Transaction hash: 0xf9cce28a714764bb265bba7522bfd10d620fa0cb0f5dae26de2ac773b0a878ee
```

</Step>
<Step>

### Save the Sender Address:

```bash
export SENDER_ADDRESS={your-sender-address}
```

</Step>
<Step>

### Deploy the Receiver Contract:

```bash
forge create --rpc-url testnet-dispatch --private-key $PK contracts/interchain-messaging/invoking-functions/CalculatorReceiverOnDispatch.sol:CalculatorReceiverOnDispatch --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 148.40ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9 // [$RECEIVER_ADDRESS]
Transaction hash: 0xa8efb88abfef486d2caba30cb4146b1dc56a0ee88c7fb4c46adccdf1414ae39e
```
</Step>
<Step>

### Save the Receiver address:

```bash
export RECEIVER_ADDRESS={your-receiver-address}
```

</Step>
<Step>

### Call the Functions

Now you can call the `sendAddMessage` and `sendConcatenateMessage` functions on the sender contract and see the results on the receiver contract. 

```bash
cast send --rpc-url testnet-c --private-key $PK $SENDER_ADDRESS "sendAddMessage(address, uint, uint)" $RECEIVER_ADDRESS 1 2
```

</Step>
<Step>

### Verify the Result:

```bash
cast call --rpc-url testnet-dispatch $RECEIVER_ADDRESS "result_num()(uint)"
```

</Step>
</Steps>

<Quiz quizId="307"/>


# Extend the Calculator (/academy/avalanche-l1/interchain-messaging/06-invoking-functions/07-extend-calculator)

---
title: Extend the Calculator
description: Assignment- Extend calculator functionality
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

Now let's add a third feature to the calculator: adding three numbers. We want you to practice handling different amounts of parameters depending on the action to perform, so your task will be to add a `tripleSum` function that sums up three values of the type uint. 

You will need to:

- Add the `trippleSum` action to the enum file
- Add a new encode helper and send function to the sender contract
- Add a new route to the receiver and implement the `tripleSum` function

Check out the solution under `contracts/interchain-messaging/invoking-functions` in the Lux-Starter-Kit on the **interchain-messaging** branch.


# Lux Warp Messaging (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/01-avalanche-warp-messaging)

---
title: Lux Warp Messaging
description: Learn about Lux Warp Messaging, the Cross-Chain communication primitives on Lux.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="95KB-JhQS2Y" />

Lux Warp Messaging (AWM) was developed to make all Lux blockchains natively interoperable. Ideally, this solution would introduce as few trust assumptions as possible, meaning the blockchains would not depend on a third-party or intermediary that could risk centralization or single-point failures. 

AWM allows Lux L1s to communicate with one another via authenticated messages by providing signing and verification primitives in LuxGo. These are used by the blockchain VMs to sign outgoing messages and verify incoming messages. Any Virtual Machine (VM) on Lux can integrate AWM to send and receive messages across Lux L1s. 

Therefore, AWM is not EVM specific, but rather a general cross-Lux L1 communication protocol.

## What you will learn

In this section, you will go through the following topics:

- **Platform-Chain:** What is the role of the Platform-Chain in Lux Warp Messaging?
- **Warp Message Format:** What does a Warp message consist of?
- **Warp Message Signing:** How does AWM utilize the multi-signature scheme BLS to create aggregated signatures?
- **Warp Message Signature Verification:** How are the signatures of warp messages verified?
- **Trust Assumptions:** What trust assumptions does AWM introduce?

# Recap Platform-Chain (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/02-p-chain)

---
title: Recap Platform-Chain
description: Recap about the Platform-Chain main functionality of handling validator operations.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import PChain from "@/content/common/primary-network/p-chain.mdx";

<PChain />

<Quiz quizId="311"/>


# Warp Message Format (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/03-warp-message-format)

---
title: Warp Message Format
description: Learn about the structure of a Warp Message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Warp Messages have a minimal message format that only contains the absolute necessary data for the transportation:

- **NetworkID:** The ID of the Network (Mainnet, Testnet Test Network, Local Test Network). This is included as a security mechanisms, so messages from the Testnet Test Network cannot be replayed on the Mainnet.
- **SourceChainID:** The chainID where the message originates from. This is not the EVM chain ID you may know from adding a network to a wallet, but the blockchain ID on the Platform-Chain. The Platform-Chain uses the transaction ID of the transaction that created those blockchain on the Platform-Chain for the chain ID, e.g.: 0xd7cdc6f08b167595d1577e24838113a88b1005b471a6c430d79c48b4c89cfc53
- **SourceAddress:** The address of the message sender
- **Payload:** The payload of the message

Every Warp message can be uniquely identified by its ID: the SHA256 hash of the serialized message (NetworkID, SourceChainID, SourceAddress & Payload).

The fields above are actually an UnsignedMessage. Hence, it has not been attached an aggregated signature yet. We will examine this in the following sections. 


# AWM Relayer (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/04-awm-relayer)

---
title: AWM Relayer
description: Learn the basic AWM role and configuration.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

The AWM Relayer is an application run independently of the blockchain clients. Anyone can run their own AWM Relayer to create a communication channel between two Lux L1s, and there can be multiple relayers for the same communication channel. There is an open source implementation anyone can use [here](https://github.com/luxfi/awm-relayer). 

[AvaCloud](https://www.avacloud.io) also offers their own hosted relayers.



The AWM Relayers are responsible for picking up the messages at the source Lux L1, aggregating the BLS signatures from a sufficiently large share of the source Lux L1's validators and submitting a transaction on the destination Lux L1.

It is up to the cross-chain application to decide if they allow any relayer to be part of the delivery process, or whether to restrict participation to certain Relayers.

## AWM Relayer Config

The AWM Relayer can be configured so that it is reusable for different networks (Mainnet, Testnet Testnet, Local) and communication channels between Lux L1s. The following configurations are available:

```json title="https://github.com/luxfi/awm-relayer/blob/main/sample-relayer-config.json"
{
  "info-api": {
    "base-url": "https://api.lux-test.network"
  },
  "p-chain-api": {
    "base-url": "https://api.lux-test.network"
  },
  "source-blockchains": [
    {
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "yH8D7ThNJkxmtkuv2jgBa4P1Rn3Qpr4pPr7QYNfcdoS6k6HWp",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "https://api.lux-test.network/ext/bc/C/rpc"
      },
      "ws-endpoint": {
        "base-url": "wss://api.lux-test.network/ext/bc/C/ws"
      },
      "message-contracts": {
        "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
          "message-format": "teleporter",
          "settings": {
            "reward-address": "0x5072..."
          }
        }
      }
    }
  ],
  "destination-blockchains": [
    {
      "subnet-id": "7WtoAMPhrmh5KosDUsFL9yTcvw7YSxiKHPpdfs4JsgW47oZT5",
      "blockchain-id": "2D8RG4UpSXbPbvPCAWppNJyqTG2i2CAXSkTgmTBBvs7GKNZjsY",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "https://subnets.lux.network/dispatch/testnet/rpc"
      },
      "account-private-key": "0x7493..."
    }
  ]
}
```

- **Info API URL:** An RPC endpoint where the AWM Relayer can access the Info API to retrieve the information about the network
- **Platform-Chain API URL:** An RPC endpoint where the AWM Relayer can access the Platform-Chain to retrieve the validators of the source Lux L1
- **Source Lux L1 Configs:** An array of configurations for the source Lux L1s where the messages are picked up from
- **Destination Lux L1 Configs:** An array of configurations for the destination Lux L1s where the messages are delivered to

# Dataflow (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/05-dataflow)

---
title: Dataflow
description: Learn the complete flow of a Cross-Chain message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Looking at the bigger picture, the data flow of an interchain message can be described as follows:

 
<Steps>
<Step>
 
### Message Initialization
Cross-Chain dApp initiating the message calls the Interchain Messaging Contract on the source Lux L1
 
</Step>
 
<Step>
 
### Warp Precompile
The Interchain Messaging contracts interacts with the AWM precompile of the EVM
 
</Step>

<Step>
 
### Message Relaying
An AWM Relayer relays the message to the destination Chain. It periodically checks the source Lux L1 for outgoing messages and delivers these by calling the Interchain Messaging contract on the destination Lux L1.
 
</Step>

<Step>
 
### Signature Verification
The Interchain Messaging contract on the destination chain interacts with AWM to verify the signature of the message and whether it has been signed by a sufficiently large stake share of the source Lux L1's validator set.
 
</Step>

<Step>
 
### Destination Contract Call
The Interchain Messaging contract then calls the destination dApp contract 

</Step>

<Step>
 
### Message Processing
The dApp decodes the message payload and processes it accordingly.

</Step>
</Steps>

As you noticed in the `Teleporter Basics` chapter most of the cross-chain communication has been abstracted away from the dApp developer. The only interfaces for them are:

- **Sending a message:** Simply calling the Interchain Messaging contract on the source chain
- **Receiving a message:** Being able to be called by the Interchain Messaging on the destination chain

To start, we will assume there is always an AWM Relayer to deliver our messages without any incentives. Let's dive deeper into the sending and receiving of messages in the next sections.

<Quiz quizId="312"/>

# Message Pickup (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/06-message-pickup)

---
title: Message Pickup
description: Learn about the role of the Relayer when picking up the message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

When the AWM Relayer detects a new message, it collects the signatures of that message from the validators of the source Lux L1. The validator uses the BLS private key corresponding to their  BLS public key (registered on the Platform-Chain) to create a signature for the unsigned warp message we've learned about earlier (in the Warp Message Format).

![](/common-images/awm/relayer-pickup.png)

The AWM Relayer does not necessarily need to collect the signature of all validators. It only needs to ensure that the validators of the collected signatures represent a sufficiently large share of the total stake of the Lux L1. It is up to the receiving Lux L1 to determine what the threshold is.

## New Outgoing Messages

How does a AWM Relayer learn about new messages? The AWM Relayer has two options to check for outgoing warp message on the source Lux L1:

- **Polling:** The AWM Relayer periodically checks the source chain for new outgoing messages. 
- **Notification:** The AWM Relayer is triggered whenever a new outgoing message is detected by a node. 

## AWM Relayer Source Lux L1 Configuration

For the source Lux L1s, the AWM Relayer offers the following configuration:

```json
"source-blockchains": [
    {
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "yH8D7ThNJkxmtkuv2jgBa4P1Rn3Qpr4pPr7QYNfcdoS6k6HWp",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "https://api.lux-test.network/ext/bc/C/rpc"
      },
      "ws-endpoint": {
        "base-url": "wss://api.lux-test.network/ext/bc/C/ws"
      },
      "message-contracts": {
        "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
          "message-format": "teleporter",
          "settings": {
            "reward-address": "0x5072..."
          }
        }
      }
    }
  ],
```

- **subnet-id:** The id of the source Lux L1
- **blockchain-id:** The chainId of the source Lux L1's blockchain that should be checked for outgoing messages
- **vm:** A string specifying the virtual machine of the source Lux L1's blockchain. Currently, only the evm is supported, but this field has been added in anticipation of communication between blockchains powered by different virtual machines in the future.
- **rpc-endpoint:** The host of a node that can be queried for outgoing messages 
- **ws-endpoint:** The websocket endpoint of a node that can be queried for outgoing messages 
- **message-contracts:** A map with the address of the Interchain Messaging contract as key and the following config parameters as values:
    - **message-format:** A string specifying the format. Currently, only the format "teleporter" exists, but this field has been added in anticipation of multiple formats in the future
    - **settings:** A dictionary with settings for this Interchain Messaging contract 
    - **reward-address:** The address rewards are paid out to

<Quiz quizId="313"/>

# Message Delivery (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/07-message-delivery)

---
title: Message Delivery
description: Learn about the role of the Relayer for delivering the message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Next, the AWM Relayer delivers the message with the aggregated signature by simply submitting a transaction to the destination Lux L1. The transaction is propagated through the validator set of the destination blockchain just as any other regular transaction would be.

In order to submit the transaction, the AWM Relayer needs access to the private key of a wallet holding the gas token of the destination blockchain to sign the transaction.

![](/common-images/awm/relayer-delivery.png)

When the validators verify the transaction, they perform the following steps:

<Steps>
<Step>
 
### Query the Platform-Chain:
The verifying validators of the destination L1 each query the validator set of the source Lux L1 with its stake weights and BLS Public Keys.

</Step>
 
<Step>
 
### Verify Sufficient Stake Weight:
First, the verifying validators are checking if the combined stake weight of the validators that have signed the Warp message is large enough to accept the message (e.g. validators representing 50% of the total stake have signed the message). The required stake weight to accept a message from a source chain can be set arbitrarily by the destination chain. An Lux L1 may require 50% for chain A and 90% for chain B. If the stake weight of the validators of the aggregate signature is insufficient the message is rejected.

</Step>

<Step>
 
### Aggregate BLS Public Keys:
The verifying validators of the destination L1 aggregate the BLS Public Keys of the source L1 validators that signed the message. 

</Step>
 
<Step>
 
### Verify BLS Multi-Signature:
The aggregated signature (created by the AWM Relayer) is now being verified using the aggregated BLS Public Key (aggregated by the destination L1 validators). If the verification fails (e.g. the AWM Relayer modified the message), the message is rejected.

</Step>

<Step>
 
### Message Execution:
If the verification is successful, the message is executed. 

</Step>

</Steps>


## Why doesn't the AWM Relayer also aggregate the BLS Public Keys?

The BLS public key aggregation has to be done by every validator of the destination L1. Some may ask why we don't perform this action off-chain through the AWM Relayer and attach it to the message (similar to the BLS signature aggregation).

Even though this would make the verification much faster, there is a security issue here. How can we be sure that the aggregated public key actually represents the public keys of the signing validators? How do we know that the AWM Relayer did not just create a bunch of public keys and an aggregated signature of these?

The only way to verify that is to aggregate the public keys of the signing validators and compare it to the one sent by the AWM Relayer. Therefore, it is pointless to attach it to the message.

<Quiz quizId="314"/>


# Load Considerations (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/08-load-considerations)

---
title: Load Considerations
description: Learn which chains experience a load increase when sending a Cross-Chain message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Let's take a moment and determine where AWM takes up load:

- **Source Lux L1**: Validators sign the message
- **Relayer**: Signature aggregation
- **Destination Lux L1**: Validators verify the message using the BLS Public Key registry on the Platform-Chain

There is no record of the network communication, the signatures, or the message itself on the Platform-Chain. It solely functions as a registry of the BLS public keys where the destination Lux L1 validators read from. Since they each already validate the primary network, they are already tracking the Platform-Chain.

Thus, sending messages from one Lux L1 to another does not put any load on the Platform-Chain or another part of the Primary Network. This is a crucial feature, as there is no bottleneck or dependencies between Lux L1s for cross-chain communication. 


# Trust Assumptions (/academy/avalanche-l1/interchain-messaging/08-avalanche-warp-messaging/09-trust-assumption-of-awm)

---
title: Trust Assumptions
description: Learn where the trust relays when using AWM.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Lux Warp Messaging uses a trick: The trusted third party is the validator set of the source L1. We are already trusting them, or else we wouldn't communicate with that L1. 

The only thing that needs to be ensured is that there is always an AWM Relayer doing the signature aggregation and delivery of the warp message. Since it will have to pay gas on the destination chain, the sender needs to make sure it has enough incentives to do so. Either those incentives come from the sender itself, or from the receiving L1 if it has an inherent interest to onboard users to its chain. You will learn how users can incentivize AWM Relayers with ERC20 tokens with Interchain Messaging in following chapters. 

Generally, if there were no relayer available, anyone could run a AWM Relayer and deliver their own messages.

# Relayer Introduction (/academy/avalanche-l1/interchain-messaging/09-running-a-relayer/01-relayer-introduction)

---
title: Relayer Introduction
description: Learn how to run and manage a AWM Relayer.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

As you now know Interchain Messaging requires a running relayer to deliver the warp messages underlying it, so far we just assumed a relayer is running. However, in a production environment, you will either need to run a relayer yourself or have someone else run it for you.



In this section you will learn how to run a relayer for Lux Warp Messaging. As discussed in the section on AWM, the relayer is responsible for checking for outgoing warp messages on the source L1, aggregate the signatures and deliver it with a transaction on the destination L1.

This chapter utilizes the reference relayer implementation created by Lux Network. In this case the relayer is a standalone application written in Go. There may be different implementations in the future that are adapted to special use cases. Anyone can build and run a relayer.

## What you will learn

In this section, you will learn how to:

- **Configure the Relayer:** Create and understand the relayer configuration file that defines which blockchains to monitor and how to interact with them
- **Set Up the Relayer Wallet:** Learn about the relayer's wallet requirements and how to fund it with testnet tokens
- **Run the Relayer:** Deploy and operate the ICM relayer using Docker
- **Monitor Message Delivery:** Track and verify cross-chain message delivery through relayer logs and blockchain transactions

# Configuration Breakdown (/academy/avalanche-l1/interchain-messaging/09-running-a-relayer/02-relayer-configuration)

---
title: Configuration Breakdown
description: Understand the Relayer Configuration  
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

A relayer is configured to relayer messages between certain source and destination L1s. Therefore, the configuration consists of three parts:
- **General Config:** Configuration independent of the source and destination L1s concerning the network as a whole
- **Source Blockchain Configs:** All parameters necessary for the relayer to pick up the messages 
- **Destination Blockchain Configs:** All parameters necessary to deliver the messages

Let's go through an example JSON understanding the different values you will configure with the Toolbox in the next section:

## General Config

The general config contains among others the following parameters:

```json
{
  "p-chain-api": {
    "base-url": "http://127.0.0.1:9650",
    "query-parameters": {},
    "http-headers": null
  },
  "info-api": {
    "base-url": "http://127.0.0.1:9650",
    "query-parameters": {},
    "http-headers": null
  	},  
   	// ...
}
```

- **info-api-url:** The URL of the [Info API](/docs/api-reference/info-api) node to which the relayer will connect to to receive information like the NetworkID.
- **p-chain-api-url:** The URL of the Lux [Platform-Chain API](/docs/api-reference/p-chain/api) node to which the relayer will connect to query the validator sets. 

## Source Blockchain Configs

Next is the configuration for our source blockchain. This is the configuration of the blockchain where messages will be initiated and picked up. The relayer will aggregate the signatures of the validators of that L1. 

```json
{
  // General Config ...

  "source-blockchains": [
	{
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "http://127.0.0.1:9650/ext/bc/epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku/rpc",
        "query-parameters": null,
        "http-headers": null
      },
      "ws-endpoint": {
        "base-url": "ws://127.0.0.1:9650/ext/bc/epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku/ws",
        "query-parameters": null,
        "http-headers": null
      },
      "message-contracts": {
        "0x0000000000000000000000000000000000000000": {
          "message-format": "off-chain-registry",
          "settings": {
            "teleporter-registry-address": "0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25"
          }
        },
        "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
          "message-format": "teleporter",
          "settings": {
            "reward-address": "0xbAE6Ff34d6Da45128C1ddFEDA008e55A328f5665"
          }
        }
      }
    }
  ]

  // Destination Blockchains
}
```

- **subnet-id:** The Blockchain ID of the L1 that the source blockchain is part of. In this example this is the Blockchain ID of the Primary Network.
- **blockchain-id:** The blockchain ID of the source. In this example this is the blockchain ID of Testnet's LUExchange-Chain.
- **vm:** A string specifying the virtual machine of the destination L1's blockchain. Currently, only the EVM is supported, but this field has been added in anticipation of communication between blockchains powered by different virtual machines in the future.
- **rpc-endpoint:** An API Config containing:
<div class="pl-6">
- **base-url:** RPC endpoint of the source L1's API node.
- **query-parameters:** Additional query parameters to include in the API requests
- **http-headers:** Additional HTTP headers to include in the API requests
</div>
- **wss-endpoint:** An API Config containing:
<div class="pl-6">
- **base-url**: The WebSocket endpoint of the source L1's API node
- **query-parameters:** Additional query parameters to include in the API requests
- **http-headers:** Additional HTTP headers to include in the API requests
</div>
- **message-contracts:** A map of contract addresses to the config options of the protocol (e.g. Teleporter) at that address. Each MessageProtocolConfig consists of a unique message-format name, and the raw JSON settings. "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf" is the address of the TeleporterMessenger on the Testnet LUExchange-Chain.
<div class="pl-6">
- **message-format:** should be set to Teleporter. Additional message formats next to Interchain Messaging may be developed in the future 
- **settings > reward-address:** The address that will be rewarded if an L1 is incentivizing relayers to send messages on it's behalf. This is the address of the wallet you will create for this relayer. 
</div>

## Destination Blockchains

Next is the configuration for our destination blockchain. This is the configuration of the blockchain where messages will be sent to. The relayer will aggregate the signatures of the validators of that L1. 
```json
{
  "destination-blockchains": [
    {
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "http://127.0.0.1:9650/ext/bc/epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku/rpc",
        "query-parameters": null,
        "http-headers": null
      },
      "kms-key-id": "",
      "kms-aws-region": "",
      "account-private-key": "6dc6ba26b9b17f82b7b44fc316857a35ff201613072d500231ce3f2ee235bc16"
    },
  ],
}
```

For each destination L1, the relayer has the following config parameter:

- **subnet-id:** The ID of the L1 that the destination blockchain is part of. 
- **blockchain-id:** The blockchain ID of the destination blockchain. This is the Blockchain ID of Testnet's Dispatch L1.
- **vm:** A string specifying the virtual machine of the destination L1's blockchain. Currently, only the EVM is supported, but this field has been added in anticipation of communication between blockchains powered by different virtual machines in the future.
- **rpc-endpoint:** The RPC endpoint of the destination L1's API node. Used in favor of api-node-host, api-node-port, and encrypt-connection when constructing the endpoint.
- **kms-key-id:** The ID of the KMS key to use for signing transactions on the destination blockchain. Only one of account-private-key or kms-key-id should be provided. If kms-key-id is provided, then kms-aws-region is required. Please note that the private key in KMS should be exclusive to the relayer. 
- **kms-aws-region:** The AWS region in which the KMS key is located. Required if kms-key-id is provided. 
- **account-private-key:** A private key for a wallet that holds gas tokens on the destination L1. This is required so the relayer can sign the transaction that delivers the warp message.

If you have been following all the course up to this point with the Lux-starter-kit and Lux-CLI will provide you with a relayer already funded to perform transactions between the local C-chain and your own chain

Some configuration fields have been omitted for the purpose of this exercise. If you are interested to read the extensive list of relayer configurations, you can visit the awm-relayer GitHub repository [here](https://github.com/luxfi/awm-relayer/tree/main?tab=readme-ov-file#configuration).

## Two-Way Messaging

The relayer can be configured to support two-way messaging between multiple Layer 1 blockchains. This means you can use a single relayer instance to handle communication in both directions between your chains. The key points to remember are:

<Callout type="warn" title="The relayer needs sufficient funds on both chains to deliver messages in both directions" />

To enable two-way communication:
- Add both chains to the `source-blockchains` array to listen for messages on both sides
- Add both chains to the `destination-blockchains` array to deliver messages to both sides
- Ensure the relayer account has enough funds on both chains for transaction fees

The ICM Relayer component in the Toolbox automatically handles this configuration for you, making it easy to set up two-way messaging between your chains.


# Configure & Run Relayer (/academy/avalanche-l1/interchain-messaging/09-running-a-relayer/03-configure-and-run-relayer)

---
title: Configure & Run Relayer
description: Configure and run an ICM relayer using Toolbox
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

The ICM Relayer is responsible for delivering messages between chains. Using the Toolbox interface, you can easily configure and manage your relayer instance.

## Relayer Setup

The Toolbox interface provides a simple way to configure and setup your relayer. Follow these steps to run your relayer:

1. Select both **Dispatch and LUExchange-Chain** as source and destination networks
2. Fund the relayer address with enough native tokens on each chain
3. Copy and run the configuration command
4. Start the relayer using the provided Docker command on you **interchain-messaging codespaces terminal**

<Callout type="warn" title="Make sure you are in testnet mode before proceeding & you have sufficient balance to fund the relayer" />

<ToolboxMdxWrapper walletMode="l1">
    <ICMRelayer />
</ToolboxMdxWrapper>

In order to check if the relayer is running you can run this command:

```bash
docker logs -f relayer
```

And the output should look like this:

```bash
{"level":"info","timestamp":"2024-07-11T01:38:40.093Z","logger":"awm-relayer","caller":"main/main.go:94","msg":"Initializing awm-relayer"}
{"level":"info","timestamp":"2024-07-11T01:38:40.093Z","logger":"awm-relayer","caller":"main/main.go:99","msg":"Set config options."}
{"level":"info","timestamp":"2024-07-11T01:38:40.093Z","logger":"awm-relayer","caller":"main/main.go:102","msg":"Initializing destination clients"}
{"level":"info","timestamp":"2024-07-11T01:38:40.094Z","logger":"awm-relayer","caller":"evm/destination_client.go:105","msg":"Initialized destination client","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku","evmChainID":"43112","nonce":0}
{"level":"info","timestamp":"2024-07-11T01:38:40.096Z","logger":"awm-relayer","caller":"evm/destination_client.go:105","msg":"Initialized destination client","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","evmChainID":"123","nonce":0}
{"level":"info","timestamp":"2024-07-11T01:38:40.096Z","logger":"awm-relayer","caller":"main/main.go:121","msg":"Initializing app request network"}
{"level":"info","timestamp":"2024-07-11T01:38:41.757Z","logger":"awm-relayer","caller":"main/main.go:440","msg":"starting metrics server...","port":9091}
{"level":"info","timestamp":"2024-07-11T01:38:41.757Z","logger":"awm-relayer","caller":"main/main.go:373","msg":"Creating application relayers","originBlockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"main/main.go:373","msg":"Creating application relayers","originBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0x96ba68805e937e7695ffb1c956dab0aff39ec5529fd037d8168eb6d5587866fe","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0xf8b2da5b262b41a2ee2d2b46e61e68c95ec7fb8f6b0abbe4101f75f8281b85aa","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"main/main.go:283","msg":"Created application relayers","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.759Z","logger":"awm-relayer","caller":"relayer/listener.go:127","msg":"Creating relayer","subnetID":"11111111111111111111111111111111LpoYY","subnetIDHex":"0000000000000000000000000000000000000000000000000000000000000000","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku","blockchainIDHex":"55e1fcfdde01f9f6d4c16fa2ed89ce65a8669120a86f321eef121891cab61241"}
{"level":"info","timestamp":"2024-07-11T01:38:41.760Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0xe73a74b50d44b1b216bf806bc7e230d5305e544d35d41c2313cda26766ccd8ec","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.760Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0x66f44659b15f9d819caf71978931df3d5d7925b5d800cc4ef8153f12151401f6","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.760Z","logger":"awm-relayer","caller":"main/main.go:283","msg":"Created application relayers","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.772Z","logger":"awm-relayer","caller":"relayer/listener.go:127","msg":"Creating relayer","subnetID":"26eqgD4Kt1MvTKXC9BDjEwBAfhcBcHCKj2EXjR2UuFpSWoAHhw","subnetIDHex":"9087d2f383171f73819baa49c3be63a5a6e2b492114dfc3556e42eedd182050a","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","blockchainIDHex":"52f2c4d51ef13a5781babe42c1b916e98fc88fc72919b20527782c939c8be71d"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"evm/subscriber.go:131","msg":"Successfully subscribed","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"evm/subscriber.go:131","msg":"Successfully subscribed","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"relayer/listener.go:166","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:335","msg":"Created listener","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:348","msg":"Listener initialized. Listening for messages to relay.","originBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"relayer/listener.go:166","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:335","msg":"Created listener","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:348","msg":"Listener initialized. Listening for messages to relay.","originBlockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:43:59.040Z","logger":"awm-relayer","caller":"relayer/listener.go:406","msg":"Unpacked warp message","sourceBlockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku","originSenderAddress":"0x5DB9A7629912EBF95876228C24A848de0bfB43A9","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","destinationAddress":"0x52C84043CD9c865236f11d9Fc9F56aa003c1f922","warpMessageID":"2ZV5u7WPVozo386A3d8T5B81vAKvcSDdNsggpmHFvihy5Yut1S"}
{"level":"info","timestamp":"2024-07-11T01:43:59.052Z","logger":"awm-relayer","caller":"relayer/application_relayer.go:320","msg":"Fetching aggregate signature from the source chain validators via AppRequest"}
{"level":"info","timestamp":"2024-07-11T01:43:59.060Z","logger":"awm-relayer","caller":"relayer/application_relayer.go:461","msg":"Created signed message.","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:43:59.060Z","logger":"awm-relayer","caller":"teleporter/message_handler.go:187","msg":"Sending message to destination chain","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","warpMessageID":"2ZV5u7WPVozo386A3d8T5B81vAKvcSDdNsggpmHFvihy5Yut1S","teleporterMessageID":"Hqr8jHV4NjTf4sbCoGqNJEuntm8QoWnDXdivFNLizAzFxRxm3"}
{"level":"info","timestamp":"2024-07-11T01:43:59.063Z","logger":"awm-relayer","caller":"evm/destination_client.go:192","msg":"Sent transaction","txID":"0x291bc3a3784dd79871cf4f95ba8f3fb3519e25c73848ee27bc5ebd7e3fe178d5","nonce":0}
{"level":"info","timestamp":"2024-07-11T01:43:59.266Z","logger":"awm-relayer","caller":"teleporter/message_handler.go:250","msg":"Delivered message to destination chain","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","warpMessageID":"2ZV5u7WPVozo386A3d8T5B81vAKvcSDdNsggpmHFvihy5Yut1S","teleporterMessageID":"Hqr8jHV4NjTf4sbCoGqNJEuntm8QoWnDXdivFNLizAzFxRxm3","txHash":"0x291bc3a3784dd79871cf4f95ba8f3fb3519e25c73848ee27bc5ebd7e3fe178d5"}
{"level":"info","timestamp":"2024-07-11T01:43:59.266Z","logger":"awm-relayer","caller":"relayer/application_relayer.go:246","msg":"Finished relaying message to destination chain","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
```

# Restricting a Relayer (/academy/avalanche-l1/interchain-messaging/10-restricting-the-relayer/01-restricting-the-relayer)

---
title: Restricting a Relayer
description: Learn about the basics of Lux.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

In this segment, we'll delve into the mechanisms of restricting relayers for transmitting messages across Lux L1s. While the security in AWM and Interchain Messaging doesn't rely at all on the Relayer, there might be some reasons why you would want to restrict the delivery of the message to certain Relayers. 

The more obvious one is when you run your own Relayer, and don't want to incentivize any other to ensure your message gets to the destination. On following sections you will learn how to run your own Relayer so you can restrict the messages to your own.

## What You Will Learn

In this section, you will go through the following topics:

- **Allowed Relayers:** Learn how to restrict the relayer for transmitting messages across Lux L1s
- **Dynamically update the allowed Relayers:** Understand how to update the allowed relayers dynamically

# Allowed Relayer (/academy/avalanche-l1/interchain-messaging/10-restricting-the-relayer/02-allowed-relayers)

---
title: Allowed Relayer
description: Learn about the basics of Lux.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

In this segment, we'll delve into the mechanisms of restricting relayers for transmitting messages across Lux L1s. While the security in AWM and Interchain Messaging doesn't rely at all on the Relayer, there might be some reasons why you would want to restrict the delivery of the message to certain Relayers. 

The more obvious one is when you run your own Relayer, and don't want to incentivize any other to ensure your message gets to the destination. On following sections you will learn how to run your own Relayer so you can restrict the messages to your own.

Let's look at the `TeleporterMessageInput` structure included when we call the `sendCrossChainMessage` one more time.

```solidity
struct TeleporterMessageInput {
    bytes32 destinationBlockchainID;
    address destinationAddress;
    TeleporterFeeInfo feeInfo;
    uint256 requiredGasLimit;
    address[] allowedRelayerAddresses;
    bytes message;
}

interface ITeleporterMessenger {
    function sendCrossChainMessage(TeleporterMessageInput calldata messageInput)
        external
        returns (bytes32);
}
```

As you can see the `TeleporterMessageInput` allows you to specify an array of addresses for the allowed relayers. Previously we have set that to an empty array, which means that any relayer can pick up the message.

```solidity
messenger.sendCrossChainMessage( 
    TeleporterMessageInput({
        // BlockchainID of Dispatch L1
        destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
        destinationAddress: destinationAddress, 
        feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: new address[](0), // [!code highlight]
        message: abi.encode(message)
    })
);
```

If you want to restrict the message to a certain relayer, you can simply add the address of the relayer to the array. A Relayer will be identified by the reward address it is associating each time it delivers a message.

```solidity
messenger.sendCrossChainMessage( 
    TeleporterMessageInput({
        // BlockchainID of Dispatch L1
        destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
        destinationAddress: destinationAddress, 
        feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: [0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc], // [!code highlight]
        message: abi.encode(message)
    })
);
```

# Introduction (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [0xstt]
icon: Book
---

As decentralized applications (dApps) expand across multiple blockchains, some Layer 1 (L1) networks lack direct support from essential services like **Chainlink VRF (Verifiable Random Functions)**. This presents a significant challenge for developers who rely on verifiable randomness for use cases such as gaming, lotteries, NFT minting, and other decentralized functions that require unbiased, unpredictable random numbers.

The challenge arises because not every L1 network has integrated with Chainlink, meaning developers on those chains are left without native access to VRF services. Without verifiable randomness, critical aspects of dApps, such as fairness and security, can be compromised.

### Why ICM is Necessary

To address this gap, **Interchain Messaging (ICM)** provides a solution by allowing L1 networks that don’t have direct Chainlink support to still access these services. Through ICM, any blockchain can request VRF outputs from a Chainlink-supported network (e.g., Testnet) and receive the results securely on their own L1. 

This cross-chain solution unlocks the ability to use Chainlink VRF on unsupported networks, bypassing the need for native integration and ensuring that dApp developers can continue building secure and fair decentralized applications.

In the following sections, we will explore how to use ICM to access Chainlink VRF services across different chains by deploying two key smart contracts: one on the Chainlink-supported network and another on the target L1.

# Understanding the Flow (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/02-understanding-the-flow)

---
title: Understanding the Flow
description: Learn how requests for random words flow across chains using ICM.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

This section explains how random words are requested and fulfilled using Chainlink VRF across two different blockchains through **Interchain Messaging (ICM)**. The entire process involves several key components: the decentralized application (DApp), `CrossChainVRFConsumer`, `CrossChainVRFWrapper`, and `TeleporterMessenger`.

Let’s walk through the flow step by step:

<Steps>
<Step>

### DApp Submits Request for Random Words

The DApp, running on an L1 without direct Chainlink support, initiates a request for verifiable randomness by interacting with the `CrossChainVRFConsumer` contract deployed on its chain.

</Step>
<Step>

### `CrossChainVRFConsumer` Sends Cross-Chain Message

Once the DApp submits the request, the `CrossChainVRFConsumer` prepares a message containing the necessary VRF request parameters (such as `keyHash`, `request confirmations`, `gas limit`, etc.). This message is sent across chains via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the Chainlink-supported network (e.g., Testnet).

</Step>
<Step>

### `TeleporterMessenger` Receives Message & Calls `CrossChainVRFWrapper`
1. On the Chainlink-supported network, the `TeleporterMessenger` receives the cross-chain message sent by the `CrossChainVRFConsumer`. It passes the message to the `CrossChainVRFWrapper`, which is authorized to handle VRF requests.
2. The `CrossChainVRFWrapper` contract, deployed on the supported network, sends the request to **Chainlink VRF** for random words, using the parameters received in the message (e.g., `subscription ID`, `callback gas limit`, etc.).

</Step>

<Step>

### Chainlink VRF Fulfills Random Words Request

1. The **Chainlink VRF** fulfills the request and returns the random words to the `CrossChainVRFWrapper` contract by invoking its callback function.
2. Once the random words are received, the `CrossChainVRFWrapper` encodes the fulfilled random words and sends them back as a cross-chain message to the `CrossChainVRFConsumer` on the original L1.

</Step>

<Step>

### `TeleporterMessenger` Returns Random Words to `CrossChainVRFConsumer`
   
The `TeleporterMessenger` on the original L1 receives the message containing the random words and passes it to the `CrossChainVRFConsumer`.

</Step>

<Step>

### `CrossChainVRFConsumer` Returns Random Words to the DApp

Finally, the `CrossChainVRFConsumer` processes the random words and sends them to the DApp that originally requested them, completing the flow.

</Step>

</Steps>



This end-to-end process demonstrates how decentralized applications on unsupported L1 networks can request verifiable randomness from Chainlink VRF, leveraging **ICM** to handle cross-chain communication.



# Orchestrating VRF Requests Over Multiple Chains (Wrapper) (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/03-orchestrating-vrf-requests)

---
title: Orchestrating VRF Requests Over Multiple Chains (Wrapper)
description: Learn how the CrossChainVRFWrapper contract on a Chainlink-supported L1 handles cross-chain requests for VRF.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFWrapper` contract plays a critical role in handling requests for randomness from an unsupported L1. It is deployed on a **Chainlink-supported network** (like Lux Testnet) and serves as the intermediary that interacts with Chainlink VRF to request random words.

Here’s how it functions as the provider for VRF services:

## Receives Cross-Chain Messages

<Steps>
<Step>

When the `CrossChainVRFConsumer` on the unsupported L1 initiates a request for randomness, it sends a cross-chain message via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the supported network.

</Step>
<Step>

The `CrossChainVRFWrapper` verifies that the request came from an authorized address. This is essential to ensure that only verified consumers can request randomness.

</Step>
<Step>

Upon receiving a valid request, the **VRFWrapper** calls **Chainlink VRF** and sends the request with the required parameters, such as the number of random words, request confirmations, and gas limits.

</Step>
<Step>

The `CrossChainVRFWrapper` keeps track of all pending requests using a mapping, associating each request ID with its destination (the L1 where the `CrossChainVRFConsumer` resides). This ensures that the random words are returned to the correct destination once fulfilled.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    // Verify that the origin sender address is authorized
    require(authorizedSubscriptions[originSenderAddress].isAuthorized, "Origin sender is not authorized");
    uint256 subscriptionId = authorizedSubscriptions[originSenderAddress].subscriptionId;
    // Verify that the subscription ID belongs to the correct owner
    (,,,, address[] memory consumers) = s_vrfCoordinator.getSubscription(subscriptionId);
    // Check wrapper contract is a consumer of the subscription
    bool isConsumer = false;
    for (uint256 i = 0; i < consumers.length; i++) {
        if (consumers[i] == address(this)) {
            isConsumer = true;
            break;
        }
    }
    require(isConsumer, "Contract is not a consumer of this subscription");
    // Decode message to get the VRF parameters
    CrossChainRequest memory vrfMessage = abi.decode(message, (CrossChainRequest));
    // Request random words
    VRFV2PlusClient.RandomWordsRequest memory req = VRFV2PlusClient.RandomWordsRequest({
        keyHash: vrfMessage.keyHash,
        subId: subscriptionId,
        requestConfirmations: vrfMessage.requestConfirmations,
        callbackGasLimit: vrfMessage.callbackGasLimit,
        numWords: vrfMessage.numWords,
        extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: vrfMessage.nativePayment}))
    });
    uint256 requestId = s_vrfCoordinator.requestRandomWords(req);
    pendingRequests[requestId] = CrossChainReceiver({
        destinationBlockchainId: originChainID,
        destinationAddress: originSenderAddress
    });
}   
```
</Accordion>
</Accordions>

## Handles Callback from Chainlink VRF

<Steps>
<Step>

When **Chainlink VRF** fulfills the randomness request, the `CrossChainVRFWrapper` receives the random words through a callback function. This ensures that the request has been successfully processed.

</Step>
<Step>

After receiving the random words, the `CrossChainVRFWrapper` encodes the result and sends it back as a cross-chain message to the `CrossChainVRFConsumer` on the unsupported L1. This is done using the `TeleporterMessenger`.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) internal override {
    require(pendingRequests[requestId].destinationAddress != address(0), "Invalid request ID");
    // Create CrossChainResponse struct
    CrossChainResponse memory crossChainResponse = CrossChainResponse({
        requestId: requestId,
        randomWords: randomWords
    });
    bytes memory encodedMessage = abi.encode(crossChainResponse);
    // Send cross chain message using ITeleporterMessenger interface
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: pendingRequests[requestId].destinationBlockchainId,
        destinationAddress: pendingRequests[requestId].destinationAddress,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
    delete pendingRequests[requestId];
}
```
</Accordion>
</Accordions>

In summary, the `CrossChainVRFWrapper` contract acts as the **bridge** between the unsupported L1 and Chainlink’s VRF services, ensuring that random words are requested, fulfilled, and delivered back across chains efficiently.


# Bringing Chainlink VRF to Unsupported L1s (Consumer) (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/04-bring-vrf-to-unsupported-l1)

---
title: Bringing Chainlink VRF to Unsupported L1s (Consumer)
description: Learn how to request VRF from an unsupported L1 using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFConsumer` contract enables DApps on an unsupported L1 to request random words from Chainlink VRF using a cross-chain communication mechanism. Since Chainlink does not natively support all blockchains, this setup allows developers to access Chainlink's VRF service even on networks that don’t have direct support.

<Steps>
<Step>

## Requesting Random Words

The `CrossChainVRFConsumer` contract sends a cross-chain message to the `CrossChainVRFWrapper` on a Chainlink-supported L1, requesting random words. This request is sent using `TeleporterMessenger`, which handles cross-chain communication.

<Accordions>
<Accordion title="Implementation">
```solidity
function requestRandomWords(
    bytes32 keyHash,
    uint16 requestConfirmations,
    uint32 callbackGasLimit,
    uint32 numWords,
    bool nativePayment,
    uint32 requiredGasLimit
) external {
    // Create CrossChainRequest struct
    CrossChainRequest memory crossChainRequest = CrossChainRequest({
        keyHash: keyHash,
        requestConfirmations: requestConfirmations,
        callbackGasLimit: callbackGasLimit,
        numWords: numWords,
        nativePayment: nativePayment
    });
    // Send Teleporter message
    bytes memory encodedMessage = abi.encode(crossChainRequest);
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: DATASOURCE_BLOCKCHAIN_ID, 
        destinationAddress: vrfRequesterContract,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: requiredGasLimit,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
}
```
</Accordion>
</Accordions>

</Step>

<Step>

## Processing the Request
Once the request is received by the `CrossChainVRFWrapper`, it interacts with the Chainlink VRF Coordinator to request the random words on behalf of the consumer on the unsupported L1.

</Step>

<Step>

## Receiving Random Words

Once Chainlink fulfills the request, the `CrossChainVRFWrapper` sends the random words back to the `CrossChainVRFConsumer` via a cross-chain message, enabling the DApp on the unsupported L1 to use them.

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(originChainID == DATASOURCE_BLOCKCHAIN_ID, "Invalid originChainID");
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    require(originSenderAddress == vrfRequesterContract, "Invalid sender");
    
    // Decode the message to get the request ID and random words
    CrossChainResponse memory response = abi.decode(message, (CrossChainResponse));
    
    // Fulfill the request by calling the internal function
    fulfillRandomWords(response.requestId, response.randomWords);
}

function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal {
    // Logic to handle the fulfillment of random words
    // Implement your custom logic here

    // Emit event for received random words
    emit RandomWordsReceived(requestId);
}
```
</Accordion>
</Accordions>

</Step>
</Steps>


# Deploy Wrapper (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/05-deploy-vrf-wrapper)

---
title: Deploy Wrapper
description: Learn how to deploy the CrossChainVRFWrapper contract to handle cross-chain VRF requests.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Once you have set up your Chainlink VRF subscription and have your LINK tokens ready, the next step is to deploy the **CrossChainVRFWrapper** contract. This contract will act as the bridge between your unsupported L1 and the Chainlink VRF network on a supported L1, enabling cross-chain requests for random words.

<Steps>
<Step>

## Prerequisites
Before deployment, make sure you have:
- A valid **Chainlink VRF Subscription ID** (see previous section for details).
- The `TeleporterMessenger` contract address on your supported L1 (e.g., Lux Testnet).
</Step>
<Step>

## Deploy the Contract
Using the `forge create` command, deploy the `CrossChainVRFWrapper` contract to the supported L1 (e.g., Lux Testnet).

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> src/CrossChainVRFWrapper.sol:CrossChainVRFWrapper
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the deployed `TeleporterMessenger` contract.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_WRAPPER=<address>
```

</Step>
<Step>

## Verify the Deployment
After deploying the contract, verify that the `CrossChainVRFWrapper` has been successfully deployed by checking its address on a block explorer.

</Step>
<Step>

## Configure Authorized Subscriptions
Once deployed, the `CrossChainVRFWrapper` contract needs to be configured with authorized subscriptions to process requests for random words.

- Call the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID.
- This ensures that only authorized addresses can request random words via the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" <CALLER_ADDRESS> <SUBSCRIPTION_ID>
```

Replace the following:

- `<CALLER_ADDRESS>`: The address that will be authorized to request random words.
- `<SUBSCRIPTION_ID>`: The ID of your Chainlink VRF subscription.
</Step>
</Steps>

# Deploy Consumer (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/06-deploy-vrf-consumer)

---
title: Deploy Consumer
description: Learn how to deploy the CrossChainVRFConsumer contract on any L1 that does not support Chainlink VRF.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Now that the `CrossChainVRFWrapper` is deployed on a Chainlink-supported L1, it’s time to deploy the `CrossChainVRFConsumer` contract on the L1 where Chainlink VRF is not supported. This contract will handle requests for random words and interact with the **TeleporterMessenger** to communicate with the supported L1.

<Steps>
<Step>
## Prerequisites
Make sure you have:
- The `TeleporterMessenger` contract address on the unsupported L1.
- The deployed `CrossChainVRFWrapper` on the supported L1. `($VRF_WRAPPER)`
</Step>
<Step>
## Deploy the Contract
Use the following command to deploy the `CrossChainVRFConsumer` contract on your unsupported L1.

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> $VRF_WRAPPER src/CrossChainVRFConsumer.sol:CrossChainVRFConsumer
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the `TeleporterMessenger` contract on your unsupported L1.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_CONSUMER=<address>
```
</Step>
<Step>
## Verify the Deployment
Once the `CrossChainVRFConsumer` contract is deployed, verify the contract’s address and confirm that it has been successfully deployed on your L1 using a block explorer.
</Step>
</Steps>

# Create Chainlink VRF Subscription (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/07-create-vrf-subscription)

---
title: Create Chainlink VRF Subscription
description: Learn how to create a Chainlink VRF subscription to enable cross-chain randomness requests.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Before you can request random words using Chainlink VRF, you need to set up a **Chainlink VRF subscription**. This subscription allows you to fund requests for randomness and manage the list of consumers that are authorized to use the VRF service.

<Steps>
<Step>

## Access Chainlink's VRF Subscription Manager

To create a subscription, go to the Chainlink VRF Subscription Manager on the network where you plan to request VRF (e.g., Lux Testnet). You can access the manager here: [VRF | Subscription Management for Testnet](https://vrf.chain.link/testnet).
![](/common-images/chainlink-vrf/visit-subscription-management.png)

</Step>
<Step>

## Create a New Subscription

Once on the subscription manager, create a new subscription. The subscription will have a unique ID, which you'll need to reference in your `CrossChainVRFWrapper` contract. This ID is used to track your random word requests and the balance associated with them.
![](/common-images/chainlink-vrf/create-subscription.png)

</Step>
<Step>

## Fund the Subscription

After creating the subscription, you need to fund it with LINK tokens. These tokens are used to pay for the randomness requests made through Chainlink VRF. Make sure your subscription has enough funds to cover your requests.
You can get testnet LINK tokens from the Testnet Faucet: [Chainlink Faucet for Testnet](https://faucets.chain.link/testnet)

![](/common-images/chainlink-vrf/faucet.png)

![](/common-images/chainlink-vrf/add-funds.png)

</Step>
<Step>

## Add Consumers

After funding your subscription, add the `CrossChainVRFWrapper` contract `($VRF_WRAPPER)` as a consumer. This step authorizes the contract to make randomness requests on behalf of your subscription. You can add other consumers, such as other contracts or addresses, depending on your use case.
![](/common-images/chainlink-vrf/add-consumer.png)

</Step>
<Step>

## Save Subscription ID

After completing these steps, save your subscription ID. You will need this ID when configuring the `CrossChainVRFWrapper` contract to request random words.

```bash
export VRF_SUBSCRIPTION_ID=<subscription_id>
```

</Step>
</Steps>

---


# Request Random Words (/academy/avalanche-l1/interchain-messaging/13-access-chainlink-vrf-services/08-request-random-words)

---
title: Request Random Words
description: Learn how to request random words using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will learn how to request random words from Chainlink VRF using both the `CrossChainVRFConsumer` contracts.

<Steps>
<Step>

## Authorize an Address to Request Random Words

After deploying the `CrossChainVRFWrapper` contract, the first step is to authorize an address to make requests for random words. This ensures that only specific addresses linked to a subscription can request VRF.

- Use the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID. This step allows the address to make random word requests through the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" $VRF_CONSUMER $VRF_SUBSCRIPTION_ID
```

</Step>
<Step>

## Request Random Words from `CrossChainVRFConsumer`

Once the address is authorized, the next step is to send a request for random words from the `CrossChainVRFConsumer` contract on the unsupported L1. This request is then sent to the `CrossChainVRFWrapper` via a cross-chain message.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_CONSUMER "requestRandomWords(bytes32 keyHash, uint16 requestConfirmations, uint32 callbackGasLimit, uint32 numWords, bool nativePayment, uint32 requiredGasLimit)" <KEY_HASH> <CONFIRMATIONS> <GAS_LIMIT> <NUM_WORDS> <NATIVE_PAYMENT> <REQUIRED_GAS_LIMIT>
```

Replace the placeholders with:

- `<KEY_HASH>`: The VRF key hash used for random word generation.
- `<CONFIRMATIONS>`: Number of confirmations required for the request.
- `<GAS_LIMIT>`: The gas limit for the VRF callback function.
- `<NUM_WORDS>`: The number of random words requested.
- `<NATIVE_PAYMENT>`: Indicates whether the payment will be made in the native token.
- `<REQUIRED_GAS_LIMIT>`: The gas limit required for the cross-chain message to be processed.

</Step>
</Steps>

# Incentivizing a Relayer (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/01-incentivizing-a-relayer)

---
title: Incentivizing a Relayer
description: Learn how to add Relayer Incentives.
updated: 2024-06-09
authors: [andyvargtz]
icon: Book
---

You already mastered how to send messages from one chain to another, but we have been working under the assumption that all messages will be picked by the Relayers. That is not always true, and external Relayers might want to have something in exchange for their services.

Relayer fees are an optional way to incentivize relayers to deliver a Interchain Messaging message to its destination chain. They are not strictly necessary, and may be omitted if a relayer is willing to relay messages with no fee, such as with a self-hosted relayer. If the relayer is not self hosted though, user will need to incentivize them, since they need to pay the transaction fees on the destination chain

## What you will learn

- What is the data flow for fees
- How to calculate an adecuate incentive amount
- How to implement those incentives

## Exercises

In this section you will apply the learned knowledge by calculating and adding fees to our basic send-receive contracts used in the [Interchain Messaging Basics chapter](/academy/interchain-messaging/04-icm-basics/01-icm-basics).

# Fee Data Flow (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/02-fee-data-flow)

---
title: Fee Data Flow
description: Learn the logic behind the fee incentivization.
updated: 2024-06-09
authors: [andyvargtz]
icon: BookOpen
---

The basic idea of incentivizing an external AWM Relayer to relay our message is to deposit an amount of an ERC-20 token into the Interchain Messaging contract as a reward for whichever relayer delivers our message.

Let's see how the fees are transferred from the user at the very beginning of sending a Cross Chain message, up to the point where the relayer is able to claim the fee.
![AWM Relayer with fees data flow](/common-images/teleporter/teleporter-fees-receipt.png)


We are using the following emoji guide to show the actors of each action:


**👩 User**

**📜 Cross-Chain dApp**

**👾 TeleporterMessenger**

**🛸 Relayer**

### Previous to Sending the Message:

- 👩 The message sender (user) requires to approve the Cross-Lux L1 dApp as a spender on the ERC20 contract to be used as fee.

### Sending the Message:

- 👩 User sends a message.
- 📜 Fee funds (previously approved) are transferred from the user's wallet to the Cross-Chain dApp.
- 📜 Cross-Chain dApp approves the Interchain Messaging Contract to spend the ERC20 fee tokens.
- 👾 Fee tokens are transferred into the Interchain Messaging Contract.
- 👾 Interchain Messaging assigns a unique ID to the Message and keeps track of the fee Info.
- 🛸 Relayer can now pick and deliver the Message.

### Message Delivered in the Destination Chain:

- 👾 Interchain Messaging in the Destination Chain generates a receipt with the `messageID` and Relayer address who delivered the message.
- Receipt is sent back to the Source Chain.
- 🛸 Relayers can send the receipts back to the Source Chain themselves or wait until a new (unrelated) message is sent now from the once Destination Chain to the former Source chain. Messages include up to 5 pending receipts in a message.

### Once Message is Received in the Source Chain:

- 👾 The Interchain Messaging marks the `messageID` as received and increases the Relayer redeemable reward.
- 🛸 The relayer can now claim its unlocked rewards.

As you can see, there are just a few actions you as a cross-chain dApp developer need to implement so dApp works smoothly with fees, everything else is being done by the Interchain Messaging contract and the Relayer.

If you run your own relayer, you don't have to attach any fees.

<Quiz quizId="315"/>

# Determining the Fee (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/03-determining-the-fee-amount)

---
title: Determining the Fee
description: Calculate a fair incentive amount.
updated: 2024-06-09
authors: [andyvargtz]
icon: BookOpen
---

## Economic Considerations for Relayers

### Determining Relayer Incentives

The first question to address is: How much should you pay a Relayer to ensure they are incentivized to deliver the message? The answer is straightforward but requires some analysis. The incentive should at least cover the expenses the Relayer will incur by delivering your message.

As mentioned in previous lessons, a message will be considered delivered in the destination Chain if the Relayer sends at least the `requiredGasLimit` stated in the message, regardless of whether the execution succeeds or fails. Thus, the associated cost in $USD (or another asset like LUX) that the Relayer will face to deliver your message is:  

*Cost = requiredGasLimit * gas_price_in_native_token * native_token_price*

While the income the Relayer will be paid for delivering your message is:  

*Income = Fee_Amount * ERC20_Price*

Excluding the Relayer's hosting costs, any Fee amount where *Costs < Income* will be profitable for the Relayer. Different types of messages or actions available in a cross-chain dApp may require different amounts of gas to deliver successfully. For instance, in a cross-chain ERC20 minter, creating the token contract is more expensive than minting new tokens, simply because creation requires deploying a new contract. Thus, it makes sense to reward the Relayer with a higher amount for delivering a creation message compared to a minting message (assuming both `requiredGasLimit` are set accordingly).

### Example Calculation

Let's calculate the minimum fee that could incentivize a Relayer to pick and deliver a message.

To simplify, consider the following assumptions:
- We are sending a message from LUExchange-Chain to Dispatch.
- ERC20 incentives will be paid in TLP.
- DIS is the fee token in Bulletin.
- Assume *DIS_price = TLP_price*.
- Relayer will only take your message if it can make at least 10% profit.
- The `requiredGasLimit` for sending our message is 10,000 gas units.
- Gas price in Dispatch = 50 nDIS (DIS * 10^-9).

### Calculating the Fee

The cost of relaying this message will be:  

*Cost = 10,000 * 50 * DIS_price*

The Relayer will take your message only if it can make a 10% profit:  

*Income = 1.1 * Cost*

Therefore:  

*TLP_price * Amount = 1.1 * 10,000 * 50 * DIS_price*

Knowing that *TLP_price = DIS_price*:  

*Amount = 1.1 * 10,000 * 50*

Then:  

*Amount = 550,000 nTLP*  
*Amount = 550,000,000,000,000 weiTLP*

All amounts in Solidity need to be declared in wei, so use a unit converter to convert from nTLP to wei (10^-18).

<Quiz quizId="316"/>

# Setting Incentives (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/04-setting-incentives)

---
title: Setting Incentives
description: Learn where incentives details need to be included
updated: 2024-06-09
authors: [andyvargtz]
icon: BookOpen
---

As we studied in previous lessons, the `sendCrossChainMessage` function takes `TeleporterMessageInput` struct as an input. The fields feeInfo in the `TeleporterMessageInput` will be a `TeleporterFeeInfo` struct formed by the ERC20 contract address in which the fee will be paid, as well as the amount of tokens to incentivize the relayer. This amount needs to be set in wei units. 

Let's take a look at it:

```solidity
// (c) 2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity 0.8.18;

struct TeleporterMessageInput {
    bytes32 destinationBlockchainID;
    address destinationAddress;
    TeleporterFeeInfo feeInfo; // [!code highlight]
    uint256 requiredGasLimit; 
    address[] allowedRelayerAddresses;
    bytes message;
}

struct TeleporterFeeInfo {
    address contractAddress; // [!code highlight]
    uint256 amount; // [!code highlight]
}

interface ITeleporterMessenger {
    function sendCrossChainMessage(TeleporterMessageInput calldata messageInput)
        external
    returns (bytes32);
}
```
As you can see, the `TeleporterMessageInput` now needs to include the ERC20 address that will pay the incentives and the amount, all this as part of the `TeleporterFeeInfo`




# Deploy Fee Token Contract (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/05-deploy-fee-token-contract)

---
title: Deploy Fee Token Contract
description: Deploy an ERC20 to work as the Fee Token for incentives.
updated: 2024-06-09
authors: [andyvargtz]
icon: Terminal
---

To add incentives for relayers, we need an ERC20 token on the source chain (Testnet LUExchange-Chain). We'll deploy a simple ERC20 token that will be used to pay relayers for delivering our cross-chain messages.

<ToolboxMdxWrapper chain="testnet-c">
  <DeployExampleERC20 />
</ToolboxMdxWrapper>

<Steps>
<Step>

### Save the Token Address

After deploying the token through the interface above, save the token address to use it in the next steps:

```bash
export FEE_TOKEN_ADDRESS=<your-deployed-token-address>
```

Replace `<your-deployed-token-address>` with the address shown in the interface after deployment.

</Step>
<Step>

### Verify Your Token Balance

You can check that you received the initial supply:

```bash
cast call --rpc-url testnet-c \
  $FEE_TOKEN_ADDRESS \
  "balanceOf(address)(uint256)" \
  $FUNDED_ADDRESS
```

The balance should show 1,000,000 * 10^18 tokens (1,000,000 tokens with 18 decimals).

</Step>
</Steps>

These tokens will be used in the next sections to incentivize relayers to deliver your cross-chain messages.


# Incentivize an AWM relayer (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/06-incentivize-an-awm-relayer)

---
title: Incentivize an AWM relayer
description: Add incentives to the basic send-receive contracts.
updated: 2024-06-09
authors: [andyvargtz]
icon: Terminal
---

## Add Incentives to our Sender Contract

Now that we have an ERC20 token deployed and some of those tokens in our account to incentivize our relayer, let's include the incentive in our Sender contract.

```solidity title="contracts/interchain-messaging/incentivize-relayer/senderWithFees.sol"
// (c) 2023, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import {IERC20} from "@openzeppelin/contracts@4/token/ERC20/IERC20.sol";

contract SenderWithFeesOnCChain {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);
    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress, string calldata message, address feeAddress) external {
        IERC20 feeContract = IERC20(feeAddress);
        uint256 feeAmount = 500000000000000;
        feeContract.transferFrom(msg.sender, address(this), feeAmount);
        feeContract.approve(address(messenger), feeAmount);

        messenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: feeAddress, amount: feeAmount}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(message)
            })
        );
    }
}
```

Notice, our contract implementing Fees now needs to include the functionality we described in the fee flow section:

- Import `IERC20` and create the fee contract interface instance 
- 📜The Cross-Lux L1 dApp transfers the ERC20 fee amount to the control of the Cross-Chain dApp contract.
- 📜Cross-Lux L1 dApp needs to implement the approval for the Interchain Messaging contract of these ERC20 tokens.
- Include the `TeleporterFeeInfo` struct in the message. 



# Interaction Flow With Fees (/academy/avalanche-l1/interchain-messaging/11-incentivizing-a-relayer/07-interaction-flow-with-fees)

---
title: Interaction Flow With Fees
description: Go trhough the complete deployment flow and send an incentivized message.
updated: 2024-06-09
authors: [andyvargtz]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Now we have all the Smart Contract 📜 set we can start sending incentivized cross-chain messages. Now let complete the flow 

- Deploy sender contract on **LUExchange-Chain**
- Deploy receiver contract on **Dispatch**
- Approve the sender contract to spend ERC20 funds from the message sender address
- Send the message

<Steps>
<Step>

### Deploy Sender Contract 

To deploy the sender contract run:

```bash
forge create --rpc-url testnet-c --private-key $PK contracts/interchain-messaging/incentivize-relayer/senderWithFees.sol:SenderWithFeesOnCChain --broadcast
```

```bash {6}
[⠊] Compiling...
[⠒] Compiling 2 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 92.98ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0xa4DfF80B4a1D748BF28BC4A271eD834689Ea3407
Transaction hash: 0xb0ff20527818fcc0836944a13ddb3b336b95047d434bb52f6c064ab407950166
```

</Step>
<Step>
### Save the Sender Contract Address

```bash
export SENDER_ADDRESS=0xa4DfF80B4a1D748BF28BC4A271eD834689Ea3407
```

</Step>
<Step>

### Deploy Receiver Contract

Now, deploy the receiver contract.

```bash
forge create --rpc-url testnet-dispatch --private-key $PK contracts/interchain-messaging/incentivize-relayer/receiverWithFees.sol:ReceiverOnDispatch --broadcast
```

```bash {6}
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 105.36ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0xe336d36FacA76840407e6836d26119E1EcE0A2b4
Transaction hash: 0x379f0a4b875effc9b80a33f039d9a49404514e7aabaef4490f57b56fb4818f65
```

</Step>
<Step>

### Save the Receiver Contract Address

```bash
export RECEIVER_ADDRESS=0xe336d36FacA76840407e6836d26119E1EcE0A2b4
```

</Step>
<Step>

### Approve ERC20 Token Expense

👩 The Message Sender (User) requires to approve the Cross-Lux L1 dApp as a spender on the ERC20 contract to be used as fee. We'll approve 0.0005 tokens (500000000000000 wei) from your total supply of 1,000,000 tokens which matches the fee amount set in the sender contract.

```bash
cast send --rpc-url testnet-c --private-key $PK $FEE_TOKEN_ADDRESS "approve(address,uint256)" $SENDER_ADDRESS 500000000000000
```

</Step>
<Step>

### Send an incentivized message

```bash
cast send --rpc-url testnet-c --private-key $PK $SENDER_ADDRESS "sendMessage(address, string, address)" $RECEIVER_ADDRESS "Hello" $FEE_TOKEN_ADDRESS
```

</Step>
<Step>

### Verify message was received on Lux L1 

```bash
cast call --rpc-url testnet-dispatch $RECEIVER_ADDRESS "lastMessage()(string)"
```
```bash
"Hello"
```

**Success!** The message was received on the destination chain while incentivizing the Relayer.

</Step>
</Steps>


# Introduction (/academy/avalanche-l1/l1-native-tokenomics/01-tokens-fundamentals/01-introduction)

---
title: Introduction
description: chapter outline and learning goals
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Book
---

## What You Will Learn

This foundational section covers the essential concepts of blockchain tokens:

- **Token Fundamentals**: How tokens represent ownership and value
- **Token Design**: Technical parameters that shape token behavior
- **Native Tokens**: Primary blockchain currencies and their roles
- **ERC-20 Tokens**: Standardized smart contract tokens for DeFi
- **Practical Skills**: Deploy and transfer ERC-20 tokens

## Learning Goals

By the end of this section, you will understand:
- What native and ERC-20 tokens are and how they work
- How to design tokens with appropriate technical parameters
- How to deploy and transfer ERC-20 tokens

The next section will cover the key differences between native and ERC-20 tokens, including wrapped tokens.

Let's get started! 

# Token Design (/academy/avalanche-l1/l1-native-tokenomics/01-tokens-fundamentals/02-token-design)

---
title: Token Design
description: Technical parameters that shape how a token behaves on-chain.
updated: 2024-09-03
authors: [0xstt]
icon: BookOpen
---

Designing a token can also have technical approach: choices you make in the contract (or at the protocol level for native tokens) determine precision, issuance, transfer rules, permissions, gas usage, and composability. Below are the core levers to consider when specifying a token

### Decimals (Precision)

Defines the smallest unit and affects UX, pricing, rounding, and integrations.

- 6 decimals → smallest unit is 0.000001
- 18 decimals → smallest unit is 0.000000000000000001 (common on EVM)

Implementation detail: ERC‑20 exposes `decimals()`; native tokens inherit precision from the chain/protocol.

---

### Total Supply and Issuance Model

Specify whether supply is fixed at deployment or elastic over time.

- Fixed supply: immutable cap set in constructor/genesis
- Elastic supply: emissions/vesting/mint/burn mechanisms adjust supply
- Programmatic schedules vs role‑gated actions

---

### Minting and Burning Functions

Control how supply can change post‑deployment.

- `mint(address,toAmount)`: who can call (owner, `MINTER_ROLE`)? caps?
- `burn(amount)` / `burnFrom(address,amount)`: opt‑in user burn vs admin burn
- Event emissions (`Transfer` from/to zero address) for indexers

---

### Transfer Mechanics

Define how balances move and what hooks apply.

- Plain ERC‑20 `transfer/transferFrom`
- Fee/tax on transfer (discouraged for DeFi composability)
- Blacklist/whitelist or trading windows (be careful: centralization + DEX issues)
- Pausable transfers (circuit breakers via `Pausable`)

### Allowance and Approvals

Permissions for third‑party spenders.

- Standard `approve/allowance/transferFrom`
- EIP‑2612 Permit (gasless approvals via signatures)
- Race‑condition safe patterns (set to 0 then new amount)

---

### Access Control and Roles

Who can mint, pause, upgrade, or change parameters.

- `Ownable` vs `AccessControl` (role‑based: `MINTER_ROLE`, `PAUSER_ROLE`)
- Timelocks and multisig admins for safer governance changes

---


Choosing these parameters up front ensures your token remains secure, composable, and easy to integrate while matching the precision, control, and lifecycle you intend.

# Native Tokens (/academy/avalanche-l1/l1-native-tokenomics/01-tokens-fundamentals/03-native-tokens)

---
title: Native Tokens
description: Learn about native tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: BookOpen
---

A **native token** in a blockchain running the Ethereum Virtual Machine (EVM) refers to the primary digital currency or cryptocurrency native to that blockchain. Native tokens act as the foundation for value transfer and network operation within their respective ecosystems.

- **Ethereum**: ETH
- **Lux LUExchange-Chain**: LUX
- **Dexalot**: ALOT
- many more...

---

### The Role of Native Tokens

Native tokens serve multiple key roles within EVM-based blockchain networks, such as:

- **Value Transfer**: Native tokens act as the primary currency for peer-to-peer transactions within the network, enabling value exchange between participants.
- **Gas Fees**: Native tokens are used as **gas** to pay for transaction fees, contract deployments, and other network operations. This ensures that resources are allocated efficiently within the network.
- **Security**: In Proof-of-Stake (PoS) networks, native tokens are often used for staking to secure the network and validate transactions.
- **Governance**: In some cases, native tokens grant holders governance rights, allowing them to participate in decision-making processes that shape the blockchain’s future.
- **Configurability**: On Lux L1s, networks may designate different assets for gas and staking, separating user fee UX from validator economics.

---

Native tokens are the backbone of blockchain ecosystems, serving multiple roles that maintain the network's stability, security, and functionality.

# Transfer Native Tokens (/academy/avalanche-l1/l1-native-tokenomics/01-tokens-fundamentals/04-transfer-native-token)

---
title: Transfer Native Tokens
description: Learn how to transfer native tokens using Core Wallet
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this exercise, you will learn how to transfer native tokens (LUX) between accounts using Core Wallet. We'll demonstrate this using the Testnet testnet.

<Steps>
<Step>

## Open Core Wallet

First, make sure you have Core Wallet installed. If you don't have Core Wallet installed already, click the Download Core Wallet button below.

<ToolboxMdxWrapper />

</Step>
<Step>

## Switch to Testnet Testnet

<ToolboxMdxWrapper enforceChainId={43113} />

</Step>
<Step>

## Get Test LUX

Before transferring tokens, ensure you have some test LUX:

**Option 1 (Recommended):** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet LUX automatically on the LUExchange-Chain.

**Option 2:** Use the external [Lux Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `lux-academy25` to claim LUX tokens on the LUExchange-Chain of the Testnet testnet.

</Step>
<Step>

## Transfer LUX

To transfer LUX to another address:

1. Click the "Send" button in Core Wallet
2. Enter the recipient's address
3. Enter the amount of LUX to send
4. Review the transaction details
5. Click "Send" to confirm

</Step>
<Step>

## Verify the Transfer

To verify the transfer was successful:

1. Check the transaction status in Core Wallet
2. View the transaction details on the [Testnet Explorer](https://testnet.snowtrace.io)
3. The recipient can check their balance in their Core Wallet

</Step>
</Steps>

<Callout>
Remember that you need to have enough LUX in your wallet to cover both the transfer amount and the gas fees. Always double-check the recipient address before sending to avoid any loss of funds.
</Callout>

Now that you know how to transfer native tokens, you can proceed to learn about transferring ERC-20 tokens in the next section.


# ERC-20 Tokens (/academy/avalanche-l1/l1-native-tokenomics/01-tokens-fundamentals/05-erc20)

---
title: ERC-20 Tokens
description: Learn about ERC-20 tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: BookOpen
---

While a blockchain has a single **native token**, the **ERC-20** token standard was developed to allow for the representation of a wide range of assets on EVM-compatible chains. 

**ERC** stands for **Ethereum Request for Comment**, and **20** is the identifier for the specific proposal that defines the standard.

ERC-20 tokens are **fungible**, meaning each token is identical to another and can be exchanged on a one-to-one basis. These tokens are created and managed through smart contracts that adhere to the ERC-20 standard, ensuring interoperability between different tokens and decentralized applications (DApps).

---

### ERC-20 Token Architecture

At the core of every ERC-20 token is a simple **mapping** of addresses to balances, representing the number of tokens an address holds.

```solidity
abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
    
  mapping(address account => uint256) private _balances;
  
  //...
}
```

Addresses holding ERC-20 tokens can belong to either **Externally Owned Accounts (EOAs)** or **smart contracts**. Both types of accounts can store and transfer ERC-20 tokens, making ERC-20 tokens versatile in decentralized finance (DeFi) and decentralized applications.

---

### Role of ERC-20 Tokens in Blockchain Ecosystems

ERC-20 tokens play an essential role in enabling the creation of decentralized applications with various functionalities:

- **Tokenized Assets**: ERC-20 tokens can represent anything from digital currencies to tokenized real-world assets.
- **DeFi Protocols**: Many DeFi protocols use ERC-20 tokens for lending, staking, and liquidity pools.
- **Token Sales**: ICOs (Initial Coin Offerings) and other fundraising models rely heavily on ERC-20 tokens.

---

### The ERC-20 Interface

All ERC-20 tokens follow a standard interface to ensure compatibility with decentralized applications (DApps). This allows tokens to be easily transferred, approved for spending, and managed by any DApp that follows the same rules.

```solidity
interface IERC20 {
    function name() external view returns (string memory);

    function symbol() external view returns (string memory);

    function decimals() external view returns (uint8);

    function totalSupply() external view returns (uint256);

    function balanceOf(address _owner) external view returns (uint256 balance);

    function transfer(address _to, uint256 _value) external returns (bool success);

    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);

    function approve(address _spender, uint256 _value) external returns (bool success);

    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```

You can review the full **ERC-20 standard** [here](https://eips.ethereum.org/EIPS/eip-20).

---

### Transferring ERC-20 Tokens

To transfer ERC-20 tokens between accounts, you use the `transfer()` function, where the sender specifies the recipient’s address and the amount to be transferred.

For more complex interactions, such as allowing a smart contract to transfer tokens on behalf of someone else, the ERC-20 standard includes the `approve()` and `transferFrom()` functions. 


<Accordions>
<Accordion title="transfer()">
Transfers tokens from the sender’s account to another account, decreasing the sender's balance and increasing the recipient’s.
</Accordion>
<Accordion title="approve()">
This function allows the owner of a token balance to approve another account (the **spender**) to withdraw up to a specified amount of tokens. The spender can withdraw from the owner's balance multiple times, as long as the total amount doesn’t exceed the approved limit.
</Accordion>
<Accordion title="allowance()">
The `allowance()` function returns the amount that a spender is still allowed to withdraw from an owner's balance.
</Accordion>
<Accordion title="transferFrom()">
This function facilitates the transfer of tokens from one account to another on behalf of the account owner. It is typically used in scenarios where smart contracts need to execute token transfers according to the contract's logic.
</Accordion>
</Accordions>

---

ERC-20 tokens revolutionized the blockchain space by enabling the tokenization of assets and simplifying the creation of decentralized applications. Their standardization ensures compatibility across platforms and DApps, making them an integral part of the broader crypto ecosystem.

# Deploy an ERC-20 (/academy/avalanche-l1/l1-native-tokenomics/01-tokens-fundamentals/06-deploy-erc20)

---
title: Deploy an ERC-20
description: Transfer an ERC-20 token between accounts
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Deploy ERC-20

Let's deploy a basic demo ERC20 token on the Testnet testnet using our toolbox.

<ToolboxMdxWrapper>
    <DeployExampleERC20 />
</ToolboxMdxWrapper>

</Step>
<Step>

### Add Token to Core Wallet

After deploying your ERC-20 token:

1. Open Core Wallet
2. Go to the Tokens tab
3. Click "Manage"
4. Click "+ Add Custom Token"
5. Enter the token contract address from the deployment
6. The token symbol and decimals should be automatically detected
7. Click "Add Token"

<Callout>
Make sure you're connected to the Testnet testnet when adding the token. The token will only be visible on the network where it was deployed.
</Callout>

</Step>
<Step>

### Transfer ERC-20 Token

To transfer your ERC-20 token:

1. In Core Wallet, select your token from the token list
2. Click "Send"
3. Enter the recipient's address
4. Enter the amount to transfer
5. Review the transaction details
6. Click "Send" to confirm

<Callout>
Always double-check the recipient address before sending. ERC-20 transfers cannot be reversed once confirmed.
</Callout>

</Step>
<Step>

### Verify Transfer

To verify the transfer was successful:

1. Check the transaction status in Core Wallet
2. View the transaction details on the [Testnet Explorer](https://testnet.snowtrace.io)
3. The recipient can add the token to their Core Wallet to see their balance

<Callout>
If the recipient doesn't see the token in their wallet, they'll need to add it using the token contract address, just like you did in step 2.
</Callout>

</Step>
</Steps>

Now that you know how to deploy and transfer ERC-20 tokens, you can proceed to learn about token bridging in the next section.

# Key Differences (/academy/avalanche-l1/l1-native-tokenomics/01b-native-vs-erc20/08-native-and-erc20-tokens)

---
title: Key Differences
description: Learn the key differences between native tokens and ERC20 tokens on Lux L1s
updated: 2025-01-15
authors: [nicolasarnedo]
icon: Book
---

Before moving forward, and now that we have seen both, it's crucial to understand the fundamental differences between native tokens and ERC20 tokens. Each has distinct characteristics that affect how they function within your blockchain ecosystem.

## Key Differences

| Feature | ERC20 | Native |
|---------|-------|--------|
| **Defined By** | Smart Contract Deployer | Protocol Level |
| **Balance Storage** | Mapping in contract storage<br/>`mapping(address => balance)` | EVM Account state<br/>`account.balance` |
| **Transfer Logic** | Handled by contract functions<br/>`transfer()`, `transferFrom()` | Handled by EVM opcodes<br/>`CALL`, `SELFDESTRUCT` |
| **Smart Contract Awareness** | Built-in hooks for DeFi compatibility<br/>Allows programmatic approvals<br/>(e.g., Uniswap, Aave) | Can't call functions<br/>`approve()`, `transferFrom()` |
| **Receiving in Functions** | No special modifier needed<br/>`function deposit(token, amount)` | Requires `payable` modifier<br/>`function deposit() payable` |

## The Protocol Limitation

One critical limitation of native tokens is that **protocols cannot "pull" native tokens from your wallet using `transferFrom()`**. This fundamental difference impacts how DeFi protocols interact with native tokens.

## Real-World Example: Aave Lending

Let's look at how supplying ETH (a native token) to Aave works:

1. **Wrap it into WETH** - Convert native ETH to ERC20 WETH
2. **Call `approve()`** - Give Aave permission to spend your WETH
3. **Aave calls `transferFrom()`** - Aave pulls the WETH from your wallet
4. **You receive aTokens** - Start earning interest and can borrow against your deposit

## Why ERC20 Standardization Matters

The main advantage of ERC20 tokens is **standardization**. Without it:
- You could build a `deposit()` payable function for native tokens
- But then you'd have two different logics for depositing tokens
- This creates complexity and potential security issues


# Wrapped Native Tokens (/academy/avalanche-l1/l1-native-tokenomics/01b-native-vs-erc20/09-wrapped-tokens)

---
title: Wrapped Native Tokens
description: Learn about wrapped tokens and their role in blockchain ecosystems.
updated: 2025-09-15
authors: [0xstt]
icon: BookOpen
---

Now that we understand the key differences between native tokens and ERC20s, we can explore **native token wrapping** - what it is and why it's necessary for blockchain ecosystems.

**Wrapped tokens** are blockchain assets that represent a native cryptocurrency (e.g., LUX, ALOT, ETH) in a tokenized form, typically conforming to the **ERC-20 token standard**. Wrapping a native token allows it to be used in decentralized applications (dApps) and protocols that require ERC-20 tokens.

---

### What Are Wrapped Tokens?

Wrapped tokens are created through a process where the native cryptocurrency is locked in a smart contract, and an equivalent amount of the wrapped token is minted. These wrapped tokens are backed 1:1 by the underlying native asset, ensuring that the value of the wrapped token mirrors that of the original native cryptocurrency.

This **ERC-20 compatibility** is crucial for enabling the native asset to interact with dApps, decentralized exchanges (DEXs), and smart contracts within the EVM ecosystem, where ERC-20 tokens are the standard. As we learned in the previous section, this solves the fundamental limitation where protocols cannot "pull" native tokens using `transferFrom()`.

---

### Why Are Wrapped Tokens Important?

Wrapped tokens play an essential role in **interoperability** within the EVM ecosystem, facilitating seamless use across decentralized applications and protocols. They directly address the limitations we discussed about native tokens:

- **DeFi Integration**: Wrapped tokens enable native assets to participate in DeFi protocols that require ERC-20 tokens. Remember our Aave example? Native ETH needs to be wrapped to WETH before it can be supplied to lending protocols.
- **Protocol Compatibility**: They solve the `transferFrom()` limitation by allowing protocols to "pull" tokens from user wallets, which is impossible with native tokens.
- **Liquidity**: Wrapped tokens increase liquidity in DeFi by enabling users to participate in protocols that require ERC-20 tokens, even when their original asset is a native token.
- **Cross-Chain Compatibility**: Wrapped tokens allow assets from one blockchain (e.g., Bitcoin) to be used on another chain, enhancing cross-chain functionality.

---

### Wrapped Token Contract Interface

A **wrapped token contract** is typically an implementation of the ERC-20 token standard, with added functions for minting and burning tokens to facilitate the wrapping and unwrapping process. Here's a basic contract interface for a wrapped token:

```solidity
interface IWrappedToken {
    function deposit() external payable;
    function withdraw(uint256 amount) external;
    
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
}
```

<Accordions>
<Accordion title="deposit()">
This function is used to wrap native tokens. When a user calls deposit(), they send the native cryptocurrency (e.g., LUX, ETH) to the contract, which then mints an equivalent amount of the wrapped token.
</Accordion>
<Accordion title="withdraw()">
This function is used to unwrap the tokens. It burns the specified amount of wrapped tokens and returns the equivalent amount of native cryptocurrency to the user.
</Accordion>
</Accordions>

# Deploy a Wrapped Token (/academy/avalanche-l1/l1-native-tokenomics/01b-native-vs-erc20/10-deploy-wrapped-tokens)

---
title: Deploy a Wrapped Token
description: Learn how to deploy and interact with wrapped tokens
updated: 2024-09-03
authors: [0xstt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, we will deploy and interact with a wrapped token using the Dev Console.

---

<Steps>
<Step>

#### 1. Deploy Wrapped Native Token with the Dev Console
Use the Dev Console to easily deploy a wrapped native token without any setup or command line tools.

The Dev Console provides a simple interface to deploy wrapped native tokens directly from your browser. This eliminates the need to:
- Set up a local development environment
- Install and configure Foundry
- Manage private keys manually
- Write deployment scripts

You can deploy a wrapped native token in just a few clicks using the integrated deployment tool below.

</Step>
<Step>

### Deploy Your Wrapped Native Token

Use the integrated Dev Console below to deploy your wrapped native token:

<ToolboxMdxWrapper>
  <DeployWrappedNative />
</ToolboxMdxWrapper>

</Step>

<Step>

### Note Your Wrapped Token Address

After deployment, the Dev Console will display your wrapped token address. You can copy this address for use in other tools and interactions. The address will be automatically saved in the Dev Console session for easy reference across different tools.

</Step>

<Step>

### Interacting with Your Wrapped Token

Once deployed, you can interact with your wrapped native token using various methods:

**Using the Dev Console:**
- The Dev Console provides additional tools for interacting with ERC-20 tokens
- Look for token interaction tools in the ICTT section
- These tools provide a user-friendly interface without requiring command-line knowledge

**Using Wallets:**
- Import the token address into MetaMask or other EVM-compatible wallets
- The wrapped token will appear as a standard ERC-20 token
- You can send, receive, and view balances directly in your wallet

**Key Functions:**
- **Deposit/Wrap**: Convert native tokens to wrapped tokens (increases your wrapped token balance)
- **Withdraw/Unwrap**: Convert wrapped tokens back to native tokens (decreases your wrapped token balance)

The wrapped token maintains a 1:1 ratio with the native token, making it perfect for DeFi integrations and cross-chain applications.

</Step>

</Steps>

<Quiz quizId="202"/>

# Introduction (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/01-introduction)

---
title: Introduction
description: Learn about custom native token of your Lux L1 blockchain.
updated: 2025-09-12
authors: [nicolasarnedo]
icon: Book
---

## What is Independent Tokenomics?

Lux Custom Blockchains offer multiple ways to implement independent tokenomics. This gives developers more control and can enable new business models that would not be economically feasible on single-chain systems.

The customizations you'll learn about include:

- **Native Token:** Every Lux L1 has its own native token used for paying transaction fees
- **Transaction Fees:** Configure how transaction fees should be calculated
- **Initial Native Token Allocation:** Specify how the initial token supply is distributed
- **Native Token Minting Rights:** Define if and who can mint more native tokens
- **Staking Token:** For public and permissionless validation, define your logic for how a node can become a validator

You'll get hands-on experience configuring the tokenomics of your own custom blockchain throughout this course.

Firstly, for financial institutions, having their blockchain with a custom native token can facilitate cheaper transactions compared to traditional banking systems. This flexibility can enable real-time payments, cross-border transactions, and micropayments, fostering financial inclusion and innovation.

For gaming platforms, having their blockchain with a custom native token can revolutionize in-game economies and user experiences. They can design their tokenomics to incentivize gameplay, reward loyal players, and monetize virtual assets.

# Custom Token vs ERC20 (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/02-custom-native-vs-erc20-native)

---
title: Custom Token vs ERC20
description: Understanding your options for native tokens on Lux L1s
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

Every Lux L1 blockchain has its own native token used for paying for transactions (gas). This isolates the fee to use the blockchain from any activity on other chains in the ecosystem.

For example, if there is high usage of the primary network, it does not affect the fees on another Lux L1.

Having their own blockchain with a custom native token in the Lux network can open up a wide range of new use cases for companies, ranging from financial institutions to gaming platforms. By having control over their gas token, these companies can revolutionize the blockchain landscape and enable innovative applications.

When designing your Lux L1, you have two options for what will be the native token of your chain. In this section we outline which one will create the right tokenomics for your use case.

## Option 1 - *Custom Native Token*

Creating a **custom native token** gives you complete control over your blockchain's gas token. This approach offers several advantages:

- **Custom Tokenomics**: Design token distribution, inflation, and utility to match your project's needs
- **Business Model Flexibility**: Avoid the high costs of sponsoring transaction fees on other chains. You can make the native token intentionally valueless to deliver gas-free experiences, eliminate fee sponsorship burdens, and create Web2-like UX that removes barriers for mainstream users
- **Fee Control**: Set predictable, isolated transaction costs independent of other chains' activity and token price volatility
- **Economic Design**: Create token utility, reward mechanisms, and incentive structures that align with your application's goals

## Option 2 - *Existing ERC20 as Native Token*

You can also tie your native token's value to an **existing ERC20 token** (like USDC). This approach offers:

- **Price Stability** (if you chose a stablecoin): It will ensure predictable gas costs for users; say 0.001 LUX is the gas cost, LUX might it be worth more in November than in January. During high congestion moments on your Stablecoin-based L1 gas price will still increase, just the underlying asset to pay it will always remain constant.
- **Familiar Asset**: Users already understand and trust the underlying asset

## L1 Native Tokenomics Decision Outline

This **L1 Native Tokenomics** course focuses on implementing and creating an L1 with a **custom native token**. You'll learn how to:

- Create custom token
- Assign Initial Allocation
- Use Wrapped Native Token pre-deployed contract
- Configure Native Minting Rights
- Configure Fee Configuration for Transactions

*Using existing ERC20 tokens* or **another chain's native token** as your L1's native token will be covered in the **Cross-Chain L1 Native** course*.



# Native and Staking Tokens (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/03-native-vs-staking)

---
title: Native and Staking Tokens
description: Understanding your options for native tokens on Lux L1s
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

It's important to understand that your **native token and staking token don't necessarily have to be the same**:

- **Native Token**: Used for paying transaction fees (gas)
- **Staking Token**: Used for validator rewards and network security

This separation allows for more flexible tokenomics design and can optimize different aspects of your blockchain's economy.

**Validator management and staking tokenomics** will be covered in:
- [Permissioned L1s](/academy/permissioned-l1s) course: Learn about validator manager deployment options
- [Permissionless L1s](/academy/permissionless-l1s) course: Learn about staking tokenomics and validator economics

# Token Symbol (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/04-token-symbol)

---
title: Token Symbol
description: Understanding token symbol conventions and their importance in blockchain ecosystems
updated: 2025-08-21
authors: [nicolasarnedo]
icon: BookOpen
---

When creating a custom native token for your Lux L1, choosing the right token symbol is more important than it might initially seem. A token symbol serves as the shorthand identifier for your token across wallets, exchanges, and applications.

## Symbol Conventions

Token symbols typically follow these conventions:
- **Length**: 3-5 characters (ETH, LUX, USDC, BTC)
- **Format**: All uppercase letters
- **Uniqueness**: Should be distinct from existing popular tokens
- **Relevance**: Often relates to the project name or purpose

## Native Token Symbol in Code

In Solidity and other EVM-based smart contracts, there's an important convention to understand. The native token is always referred to as **"ether"** in the code, regardless of what the actual token symbol is on your blockchain.

For example:
```solidity
// This always refers to the native token, whether it's ETH, LUX, or your custom token
msg.value // Amount of native token sent
address.balance // Native token balance
payable(recipient).transfer(1 ether) // Transfer 1 unit of native token
```

This convention exists because Solidity was originally designed for Ethereum, where the native token is Ether. The keyword "ether" became a unit denomination in the language itself.

## Custom L1 Considerations

When launching your Lux L1:
- Your chosen symbol (e.g., "GAME", "DEFI") is what users see in wallets and explorers
- But in smart contract code, you'll still use "ether" as the unit
- This separation between display symbol and code convention helps maintain compatibility

## Best Practices

1. **Research existing symbols** to avoid conflicts
2. **Keep it memorable** and easy to type
3. **Consider your brand** - the symbol becomes part of your identity
4. **Check trademark considerations** for your chosen symbol

Your token symbol is often the first thing users encounter, so choose wisely!

# Create Custom Token (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/05-create-custom-token)

---
title: Create Custom Token
description: Understanding token symbol conventions and their importance in blockchain ecosystems
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Terminal
---

In this course, we'll use the [Developer Console](/console) to create a new L1. While you may have already created an L1 in the Lux Fundamentals course, we'll now walk through the process again—this time explaining in detail each tokenomics configuration option available. The goal of this first step is simple: create your Subnet and set your blockchain's token name and token symbol.

## Create Subnet and Chose Token name

Use the tool below to create a Subnet and then add a blockchain to it. In the Genesis configuration, only set the token name and token symbol for now (you can ignore the other sections).

<Callout type="info">
**Token Name**: The token name is purely cosmetic and not recorded anywhere in the blockchain code (except for the wrapped native token contract). It's mainly used for display purposes in wallets and explorers.
</Callout>

<Callout type="warning" type="warn">
Don't hit **create chain** yet, we will configure other tokenomics (supply, allocation, fees, etc.) in later steps of this course.
</Callout>

<ToolboxMdxWrapper walletMode="c-chain">
  <CreateChain embedded={true} initiallyExpandedSections={['ChainParamsSection']} />
</ToolboxMdxWrapper>



# Native Token Allocation (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/06-native-token-allocation)

---
title: Native Token Allocation
description: Initial token allocation of a blockchain refers to the distribution of native tokens when a new blockchain network is launched.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

The creator of an Lux L1 can pre-allocate the native tokens during the chain genesis event. The initial token allocation of a blockchain refers to the distribution of tokens or digital assets when a new blockchain network is launched.

This allocation is a critical aspect of the network's design, as it determines how tokens are distributed among various stakeholders and participants.

There are several considerations that go into the initial token allocation:

- **Founders and Development Team:** Often, a portion of the initial token supply is allocated to the founders and development team as a reward for their efforts in creating the blockchain protocol. This allocation serves as an incentive for them to continue developing and maintaining the network.
- **Early Investors and Backers:** Another portion of the token supply may be allocated to early investors and backers who provided funding or support during the project's early stages. These individuals or entities take on early risk and are rewarded with tokens that may increase in value as the network grows.
- **Community:** A significant portion of tokens may be allocated to the community through mechanisms such as a token sale, airdrops, or other distribution methods. This ensures widespread ownership and participation in the network, fostering decentralization and security.
- **Reserve:** Some tokens may be allocated to a reserve or treasury to fund ongoing development, marketing, and ecosystem growth initiatives. This reserve can be managed by a decentralized autonomous organization (DAO) or a designated entity responsible for allocating funds in the best interest of the network.

Overall, the initial token allocation of a blockchain is a complex and crucial aspect of its design, shaping the network's distribution of ownership, governance, and incentives from the very beginning.

Transparent and equitable token allocation mechanisms are essential for fostering trust and confidence in the network among its stakeholders.

# Configure Native Token Allocation (/academy/avalanche-l1/l1-native-tokenomics/02-custom-tokens/07-configure-token-allocation)

---
title: Configure Native Token Allocation
description: Learn how to configure your blockchain native token allocation.
updated: 2024-06-28
authors: [usmaneth]
icon: Terminal
---

Alright, so let's set the initial token allocation. When prompted select **addresses and the amount of your token they will have from the genesis*.

<GenesisBuilder embedded={true} initiallyExpandedSections={['tokenomics']} />

# Introduction (/academy/avalanche-l1/l1-native-tokenomics/03-precompiles/01-introduction)

---
title: Introduction
description: Chapter overview and core blockchain concepts review
updated: 2025-01-15
authors: [nicolasarnedo]
icon: Book
---

In this section we are going to quickly address what Precompiles are, why we need them and how they are implemented. The reason we cover this in the L1 Native Tokenomics course is because in the next two sections we will be working with 2 precompiles that heavily influence the tokenomics of a chain, the [Native Minter](/l1-native-tokenomics/04-native-minter) and [Fee Config](/l1-native-tokenomics/05-fee-config) Precompiles.

Specifically we are going to look into **Stateful Precompiles**, but if you wish to learn more in detail about Precompiles and how you can use them to configure your L1 please check out the [Customizing the VM](/customizing-evm) course!

## Core Concepts Review (Optional)

Before we look more closely into precompiles, it is important we re-visit and fully understand some core concepts about how blockchains and virtual machines work.

### Deterministic State Transitions

Blockchains rely on a **deterministic machine (the EVM)** to calculate transitions from one state to the next. Every transaction modifies the blockchain state in a predictable, reproducible way—ensuring all nodes reach consensus on the new state.



### EVM as a Configurable Specification

Think of the EVM like a class in Object-Oriented Programming: it's a specification that defines behavior. Each blockchain—Ethereum, Lux LUExchange-Chain, or your custom L1—is an **instance** of this EVM class, with its own configuration.



**Through Lux, you can configure your EVM instance with precompiles that live at the execution level** (will dive deeper into this later), giving you control over core blockchain functionality like native token minting and transaction fee configuration.


# Stateful Precompiles (/academy/avalanche-l1/l1-native-tokenomics/03-precompiles/02-precompiles)

---
title: Stateful Precompiles
description: Understanding Stateful Precompiles and their role in blockchain optimization
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

First of all we will start by saying the notion of precompiles contracts, or "*Precompiles*" as we are calling them, is something inherited from the Ethereum community. The EVM, while very robust and efficient for handling thousands of simple transactions like token minting, swapping or so, has a series of limitations:

### Lack of Libraries

Solidity is a relatively new language, hence it doesn't have as many powerful and battle-tested libraries as other languages like *Go*, *Typescript* or *Rust*

### Expensive Computation

Solidity code is compiled into EVM opcodes—low-level instructions designed for simple operations like addition, storage reads, and basic logic. 

When performing complex mathematical operations (like elliptic curve cryptography or modular exponentiation), these simple opcodes must be chained together, requiring many steps and frequent use of expensive operations like `SSTORE` (storage writes) which cost 20,000 gas or more. This makes advanced cryptography impractically expensive in pure Solidity

## Basic Precompiles 

Given these limitations - many developer teams/communities have proposed creating programs written in more efficient languages (Go/Rust) for well-known or frequently used operations that may temporarily by-pass the limitations of the smart contract language of that blockchain. These "programs" are then wrapped in a interface (solidity/move) and deployed to a pre-defined address so they can be called from other smart contracts in the application layer.



Instances of these Precompiles exists across most major blockchain platforms:
- Ethereum has standard precompiles at fixed addresses
- Solana uses "Native Programs" written in Rust
- Aptos and Sui have "Native Functions" exposed through Move modules

For Lux, these precompiles are especially important because you are the **owner** of your L1. Rather than having to go through several community approvals (the case for single-chain environments like Ethereum and Solana) and executing a network upgrade to implement them, you can directly define them in the genesis block! (*or add them as well through a network upgrade*)

### Common Precompiles

Here are some of the most widely used precompiles across EVM-compatible blockchains:

**Cryptographic Operations:**
- `ecRecover` (0x01): Recover Ethereum address from ECDSA signature
- `SHA256` (0x02): SHA-256 hash function

## Stateful Precompiles

The basic precompiles we've discussed so far (like ecRecover and SHA256) are **stateless**—they perform computations and return results without modifying the blockchain state. However, Lux introduces a more powerful concept: **Stateful Precompiles**.

Stateful precompiles go a step further by **injecting state access** through the `PrecompileAccessibleState` interface. This gives them the ability to:
- Read and modify account balances
- Read and write to contract storage
- Access the full EVM state during execution

This state access makes stateful precompiles far more powerful than their stateless counterparts. Instead of just performing calculations, they can directly manipulate blockchain state at the protocol level—enabling use cases like native token minting, fee configuration, and transaction/contract deployer permissioning.

Through stateful precompiles, Lux provides a level of EVM customization that goes beyond what's possible with the original precompile interface, making it ideal for building highly customized L1 blockchains.


# Protocol Integration (/academy/avalanche-l1/l1-native-tokenomics/03-precompiles/03-precompile-architecture)

---
title: Protocol Integration
description: How precompiles integrate with the VM stack and optimize execution
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

Blockchains are organized into three distinct layers, each with specific responsibilities:



1. **Application Layer**: Where smart contracts and user applications run
2. **Execution Layer**: Where the EVM processes transactions and executes code
3. **Consensus Layer**: Where validators agree on the blockchain state

Precompiles live in the **Execution Layer**, directly integrated into the EVM itself:



## Why Aren't Precompiles in the Application Layer?

You might wonder: if precompiles can be called like smart contracts, why aren't they stored with other smart contracts in the application layer?

The answer comes down to **performance and access**:

**1. Direct State Access**  
Smart contracts in the application layer must go through the EVM interpreter to access blockchain state. Precompiles, living in the execution layer, have **direct access** to the EVM state—they can read and modify balances, storage, and consensus data without the overhead of bytecode interpretation.

**2. Native Code Execution**  
Application layer contracts are compiled to EVM bytecode and executed opcode-by-opcode. Precompiles are written in Go (Lux's client language) and execute as **native code**, making them orders of magnitude faster for complex operations.

**3. Protocol-Level Operations**  
Precompiles need to perform operations that regular smart contracts cannot or should not do—like minting native tokens, configuring transaction fees, or managing validator permissions. These are **protocol-level concerns** that require execution layer access.

**4. Security Boundaries**  
By keeping precompiles in the execution layer, we maintain a clear security boundary. User-deployed contracts can't interfere with protocol operations, and protocol operations benefit from the stability and security of the client software itself.

This architectural separation is what makes stateful precompiles so powerful: they bridge the gap between user applications and the blockchain protocol, enabling customizations that would be impossible in the application layer alone.

# Introduction (/academy/avalanche-l1/l1-native-tokenomics/04-native-minter/01-introduction)

---
title: Introduction
description: Understanding the Native Minter Precompile and token supply management
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Book
---

In the previous section, we learned about precompiles and how they enable protocol-level customization of your L1. Now we'll put that knowledge into practice with the **Native Minter Precompile**—one of the most powerful tools for managing your blockchain's tokenomics.

## What You'll Learn

This section covers:
- **Native Token Supply**: Understanding hard-capped vs. flexible token supplies
- **Native Minter Precompile**: How to enable and control native token minting
- **Minting Rights Management**: Configuring who can mint new tokens

## Why This Matters

The Native Minter Precompile determines whether your blockchain has a fixed token supply (like Bitcoin's 21M cap) or can mint additional tokens as needed. This decision has major implications:

- **Valueless Gas Tokens**: Enable gas-free user experiences by minting tokens as needed
- **Controlled Inflation**: Manage token supply for economic incentives
- **Protocol Flexibility**: Adapt your tokenomics as your ecosystem grows

By the end of this section, you'll understand how to configure native token minting rights for your L1's specific use case.

Let's dive in!


# Native Token Minting Rights (/academy/avalanche-l1/l1-native-tokenomics/04-native-minter/02-native-token-minting-rights)

---
title: Native Token Minting Rights
description: Learn how to manage the native token minting rights.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

Many chains have a hard-capped supply for their gas token. The Lux LUExchange-Chain uses LUX as their gas token and there will only ever be 720m LUX. This may not be optimal for enterprise use cases, especially if they want to **create an experience with a valueless gas token**.

Therefore, they have the option to mint more native tokens at any time. This can be done through the **Native Minter Precompile**. If a community running an Lux L1 wants to hard-cap the native token, that is perfectly doable as well. They just keep the native minter capabilities deactivated (which is the default).

import NativeMinter from "@/content/common/evm-precompiles/native-minter.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<NativeMinter components={defaultMdxComponents}/>

In the upcoming chapter, we will only use an admin address in order to keep the exercise simple.

<Quiz quizId="410"/>

# Activate Native Minter (/academy/avalanche-l1/l1-native-tokenomics/04-native-minter/03-activate-native-minter)

---
title: Activate Native Minter
description: Learn how to activate the native minter precompile.
updated: 2024-06-28
authors: [usmaneth]
icon: Terminal
---

When prompted if you want to allow minting of new natie tokens, select **Allow minting additional tokens**.

<Callout type="warning">
Remember, we're still configuring the genesis for our L1—**don't hit "Create Chain" yet!** We'll continue adding more tokenomics configurations in the following sections and finally create the chain in the Genesis Breakdown section where you'll see all your configurations come together.
</Callout>

<GenesisBuilder embedded={true} initiallyExpandedSections={['tokenomics']} />

# Introduction (/academy/avalanche-l1/l1-native-tokenomics/05-fee-config/01-introduction)

---
title: Introduction
description: Let's recap our knowledge on transaction fees in blockchains
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

import TransactionFees from '@/content/common/multi-chain-architecture/transaction-fees.mdx';

<TransactionFees />
<Quiz quizId="403"/>

# Transaction Fees (/academy/avalanche-l1/l1-native-tokenomics/05-fee-config/02-transaction-fees)

---
title: Transaction Fees
description: Learn about L1 blockchain gas fees.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

When creating an Lux L1 we can configure not only our custom native token, but also how the transaction fees (also known as gas fees) are determined. This allows Lux L1s to define the desired or maximal throughput of the blockchain differently.



To adjust the fee dynamics we have the following parameters:

**Gas Limit:** The total amount of gas that can be used in a single block. This impacts how much computation happens in one block. The value represents the maximum amount of gas a single transaction can use (which would result in a single-transaction block).

**Target Block Rate:** The network aims to produce a new block in targetBlockRate seconds. This value is in seconds. If the network starts producing faster than this, base fees are increased accordingly. Otherwise, if the network starts producing slower than this, base fees are decreased accordingly.

**Min. Base Fee:** The minimum base fee that can be used by a transaction and the cost to do native token transfers. No matter how simple a transaction is, it will cost at least the minimum base fee.

**Target Gas:** The targeted amount of gas (including block gas cost) to consume within a rolling 10s window.

**Base Fee Change Denominator:** The transaction base fee changes with demand of the block space. If the parent block used more gas than its target, the base fee should increase. Otherwise, if the parent block used less gas than its target, the base fee should decrease by the amount. There is a formula behind this that would go beyond the scope of this section, but setting this value to a larger value means that the base fee will change more gradually. Setting it to a smaller value will make the base fee change more rapidly.

**Min. Block Gas Cost:** Minimum gas cost a block should cover.

**Max. Block Gas cost:** Maximum gas cost a block should cover.

**Block Gas Cost Step:** This value determines the block gas change rate depending on the targetBlockRate. If the parent block is produced at the targetBlockRate, the block gas cost will stay the same. If the parent block is produced at a slower rate, the block gas cost will decrease.


# Activate Fee Config (/academy/avalanche-l1/l1-native-tokenomics/05-fee-config/03-activate-fee-config)

---
title: Activate Fee Config
description: Learn how to configure your blockchain gas fees.
updated: 2024-06-28
authors: [usmaneth]
icon: Terminal
---

Below you can set your custom fee configuration, select **Customize fee config**. Below toggle the **Reward Manager** and hit the *Add Wallet* button to include your connected wallet in the allowlist for this Precompile.

<Callout type="warning">
Remember, we're still configuring the genesis for our L1—**don't hit "Create Chain" yet!** We'll continue adding more configurations in the following sections and finally create the chain in the Genesis Breakdown section where you'll see all your configurations come together.
</Callout>

<GenesisBuilder embedded={true} initiallyExpandedSections={['feeConfiguration']} />

# Initial Allocation (/academy/avalanche-l1/l1-native-tokenomics/07-token-distribution/01-initial-allocation)

---
title: Initial Allocation
description: Considerations for the initial token allocation on an Lux L1
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

The creator of an Lux L1 can pre-allocate native tokens during the chain genesis event. This **initial token allocation** refers to the distribution of tokens or digital assets when a new blockchain network is launched, which is a crucial aspect of the network's design.

> **Note:** Initial token allocation determines how tokens are distributed among stakeholders and participants.

### Key Considerations for Initial Token Allocation

There are several factors to consider when allocating tokens:

#### Founders and Development Team

A portion of the initial token supply is often allocated to the founders and the development team as a reward for their efforts in creating the blockchain protocol. This serves as an incentive for continued development and network maintenance.

#### Early Investors and Backers

Another portion of the token supply may be allocated to early investors and backers who provided funding or support during the project's early stages. These entities take on early risk and are rewarded with tokens that may increase in value as the network grows.

#### Community

A significant portion of tokens may be allocated to the community through mechanisms such as token sales, airdrops, or other distribution methods. This ensures widespread ownership and participation in the network, fostering decentralization and security.

#### Reserve

Some tokens may be allocated to a reserve or treasury to fund ongoing development, marketing, and ecosystem growth initiatives. This reserve can be managed by a DAO or another entity tasked with allocating funds for the network's benefit.

> **Tip:** Transparent and equitable token allocation mechanisms are essential for fostering trust and confidence in the network among its stakeholders.

<Quiz quizId="212" />

# Vesting Schedules (/academy/avalanche-l1/l1-native-tokenomics/07-token-distribution/02-vesting-schedules)

---
title: Vesting Schedules
description: Learn about vesting schedules and how to implement them in Solidity.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

**Vesting schedules** are mechanisms used in blockchain projects to release tokens to team members, investors, or other stakeholders over a specified period. This approach helps align incentives, prevent immediate sell-offs, and promote long-term commitment to the project.

---

## Understanding Vesting Schedules

A vesting schedule dictates how and when tokens are released to a recipient. Common elements include:

- **Cliff Period**: An initial period during which no tokens are vested.
- **Vesting Period**: The total duration over which tokens are gradually released.
- **Release Interval**: The frequency at which tokens are released (e.g., monthly, quarterly).
- **Total Allocation**: The total number of tokens to be vested.

### Types of Vesting Schedules

1. **Linear Vesting**: Tokens are released uniformly over the vesting period.
2. **Graded Vesting**: Tokens vest in portions at different intervals.
3. **Cliff Vesting**: All or a significant portion of tokens vest after the cliff period.

---

## Implementing Vesting Schedules in Solidity

Smart contracts can automate vesting schedules, ensuring transparency and trustlessness. Below is an example of a simple Solidity contract implementing a linear vesting schedule.

### Example Solidity Contract

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

contract TokenVesting {
    address public beneficiary;
    uint256 public start;
    uint256 public duration;
    uint256 public cliff;
    uint256 public totalTokens;
    uint256 public released;

    IERC20 public token;

    constructor(
        address _token,
        address _beneficiary,
        uint256 _start,
        uint256 _cliffDuration,
        uint256 _duration,
        uint256 _totalTokens
    ) {
        require(_beneficiary != address(0), "Invalid beneficiary");
        require(_cliffDuration <= _duration, "Cliff longer than duration");
        require(_duration > 0, "Duration must be > 0");

        token = IERC20(_token);
        beneficiary = _beneficiary;
        start = _start;
        cliff = _start + _cliffDuration;
        duration = _duration;
        totalTokens = _totalTokens;
    }

    function release() public {
        require(block.timestamp >= cliff, "Cliff period not reached");
        uint256 unreleased = releasableAmount();
        require(unreleased > 0, "No tokens to release");

        released += unreleased;
        token.transfer(beneficiary, unreleased);
    }

    function releasableAmount() public view returns (uint256) {
        return vestedAmount() - released;
    }

    function vestedAmount() public view returns (uint256) {
        if (block.timestamp < cliff) {
            return 0;
        } else if (block.timestamp >= start + duration) {
            return totalTokens;
        } else {
            return (totalTokens * (block.timestamp - start)) / duration;
        }
    }
}

interface IERC20 {
    function transfer(address recipient, uint256 amount) external returns (bool);
}

# Bonding Curves (/academy/avalanche-l1/l1-native-tokenomics/07-token-distribution/03-bonding-curves)

---
title: Bonding Curves
description: Learn about bonding curves and their role in token economics.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

**Bonding curves** are mathematical formulas used in blockchain and token economics to define the relationship between a token's price and its supply. They provide a mechanism for automated price discovery and liquidity, enabling decentralized issuance and trading of tokens without relying on traditional market makers or exchanges.

---

## Understanding Bonding Curves

A bonding curve is a continuous token model where the price of a token is determined by a predefined mathematical function based on the total supply in circulation. As more tokens are purchased and the supply increases, the price per token rises according to the curve. Conversely, selling tokens decreases the supply and lowers the price.

### Key Concepts

- **Automated Market Maker (AMM)**: A system that provides liquidity and facilitates trading by automatically adjusting prices based on supply and demand.
- **Price Function**: A mathematical formula that defines how the token price changes with supply.
- **Liquidity Pool**: A reserve of tokens used to facilitate buying and selling without requiring counterparties.

---

## How Bonding Curves Work

### Price Functions

The bonding curve relies on a price function `P(S)`, where:

- `P` is the price per token.
- `S` is the current supply of tokens.

Common price functions include linear, exponential, and sigmoid curves.

#### Linear Bonding Curve

A simple linear function:

```
P(S) = a * S + b
```

- `a` and `b` are constants defining the slope and intercept.

#### Exponential Bonding Curve

An exponential function:

```
P(S) = e^(k * S)
```

- `e` is the base of the natural logarithm.
- `k` is a constant determining the rate of price increase.

### Buying and Selling Tokens

- **Buying Tokens**: To purchase tokens, a user pays an amount calculated by integrating the price function over the desired increase in supply.
- **Selling Tokens**: To sell tokens, a user receives an amount calculated by integrating the price function over the desired decrease in supply.

---

## Applications of Bonding Curves

### Token Launch Mechanisms

Bonding curves enable projects to launch tokens without initial liquidity or listing on exchanges.

- **Continuous Token Issuance**: Tokens can be minted on-demand as users buy them.
- **Fair Price Discovery**: Prices adjust automatically based on demand.

### Decentralized Finance (DeFi)

Used in AMMs and liquidity pools to facilitate decentralized trading.

- **Uniswap**: Utilizes bonding curves for token swaps.
- **Balancer**: Manages portfolios using bonding curves.

### Fundraising and DAOs

Facilitate fundraising by allowing investors to buy tokens that represent shares or voting rights.

- **Continuous Organizations**: Organizations that continuously raise funds through token sales governed by bonding curves.
- **DAO Membership**: Tokens purchased via bonding curves grant access and voting power.

---

## Implementing Bonding Curves in Smart Contracts

### Solidity Example

Below is a simplified example of implementing a linear bonding curve in Solidity.

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

contract BondingCurve {
    uint256 public totalSupply;
    uint256 public constant a = 1e18; // Slope
    uint256 public constant b = 1e18; // Intercept
    mapping(address => uint256) public balances;

    function buy() external payable {
        uint256 tokensToMint = calculateTokensToMint(msg.value);
        balances[msg.sender] += tokensToMint;
        totalSupply += tokensToMint;
    }

    function sell(uint256 tokenAmount) external {
        require(balances[msg.sender] >= tokenAmount, "Insufficient balance");
        uint256 ethToReturn = calculateEthToReturn(tokenAmount);
        balances[msg.sender] -= tokenAmount;
        totalSupply -= tokenAmount;
        payable(msg.sender).transfer(ethToReturn);
    }

    function calculatePrice(uint256 supply) public pure returns (uint256) {
        return a * supply + b;
    }

    function calculateTokensToMint(uint256 ethAmount) public view returns (uint256) {
        // Simplified calculation for demonstration purposes
        uint256 tokens = ethAmount / calculatePrice(totalSupply);
        return tokens;
    }

    function calculateEthToReturn(uint256 tokenAmount) public view returns (uint256) {
        // Simplified calculation for demonstration purposes
        uint256 ethAmount = tokenAmount * calculatePrice(totalSupply);
        return ethAmount;
    }
}
```

Explanation

- **`buy()`:** Users send ETH to buy tokens. The number of tokens minted is calculated based on the bonding curve.
- **`sell()`:** Users can sell their tokens back for ETH. The amount of ETH returned is calculated based on the current supply.
- **`calculatePrice()`:** Determines the price per token based on the total supply.

<Callout>This is a simplified example and not suitable for production. Proper handling of floating-point arithmetic and security considerations is necessary.</Callout>

### Considerations and Risks

**Price Volatility**

- **Speculation**: Prices can become volatile due to speculative trading.
- **Market Manipulation**: Large trades may influence prices significantly.

**Smart Contract Risks**

- **Security Vulnerabilities**: Bugs in the contract can lead to loss of funds.
- **Complexity**: Implementing accurate bonding curves requires careful mathematical and technical design.

**Liquidity Concerns**

- **Slippage**: Large trades may experience significant price slippage.
- **Liquidity Pools**: Adequate reserves are necessary to handle buy and sell orders.

## Conclusion

Bonding curves offer a powerful tool for automated price discovery and token issuance in decentralized networks like Lux. They enable projects to create self-sustaining economies with built-in liquidity and dynamic pricing. Understanding bonding curves is essential for developers and stakeholders involved in tokenomics and decentralized finance.

By carefully designing bonding curve parameters and smart contracts, projects can align incentives, promote fair participation, and foster sustainable growth within their ecosystems.
<Quiz quizId="213"/>

# Airdrops (/academy/avalanche-l1/l1-native-tokenomics/07-token-distribution/04-airdrop)

---
title: Airdrops
description: Learn about token airdrops and Core's airdrop service in the Lux ecosystem.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

**Token airdrops** are a popular method in the blockchain ecosystem for distributing tokens to users, promoting projects, and incentivizing community engagement. In the Lux network, airdrops can help bootstrap new projects, reward loyal participants, and increase the distribution of tokens to a wider audience.

---

## Understanding Airdrops

Airdrops involve sending tokens directly to users' wallets, typically for free or in exchange for simple tasks like participating in network activities, holding a specific token, or interacting with a smart contract. They serve multiple purposes:

- **Marketing and Promotion**: Raise awareness about a new project or token.
- **User Acquisition**: Attract new users to a platform or service.
- **Community Rewards**: Reward loyal users and early adopters.
- **Decentralization**: Distribute tokens widely to enhance network decentralization.

---

## Core Wallet's Airdrop Tool

[Core](https://core.app/), Lux's native ecosystem wallet and portfolio, has integrated a new promotions and airdrop tool developed by Lux Network. This tool leverages on-chain data sources for seamless token distribution, allowing any builder to strategically reward their loyal community members.

### Key Features

- **On-Chain Data Integration**: Utilizes indexed on-chain data to identify and reward true users based on their interactions with contracts.
- **User-Friendly Interface**: Provides a straightforward, free method to use on-chain data for airdrops and promotions.
- **Custom Queries**: Allows builders to locate community members who have interacted with their contracts using the query builder.
- **Manual Address Addition**: Enables manual addition or upload of addresses for token distribution.

### How It Works

Lux Network indexes on-chain data, enabling Core's airdrop tool to quickly analyze contract-level activity. Daily aggregation of LUExchange-Chain token balances is conducted at the close of each day (UTC time), collecting balances of native tokens, ERC20, and ERC721 tokens. Users can leverage this data to pinpoint addresses that meet specific criteria based on token activity.

At launch, the tool supports Lux LUExchange-Chain and a subset of ERC20 tokens, with more tokens to be added in the future.

#### Query Builder

- **Filter Options**: Filter based on holding duration, current holdings, minimum holding duration, or customized date ranges.
- **Multiple Queries**: Conduct multiple queries in a single search to refine the target audience.

#### Airdrop Distribution

Airdrops are distributed through contracts deployed on-chain. Core's airdrop tool leverages a deployed version of ThirdWeb's audited Airdrop contract and Lux Network’ internal security team. At launch, airdrops will be distributed evenly among all selected wallets.

---

## Benefits of Using Core's Airdrop Tool

- **Efficient Distribution**: Streamlines token distribution and community engagement with its intuitive interface.
- **Cost-Free**: Provides a free method for builders to conduct airdrops and promotions.
- **Strategic Rewards**: Allows for targeted airdrops based on specific on-chain activities.
- **Security**: Utilizes audited contracts and security measures to protect token distributions.

---

## Real-World Example: Core Memecoin Month

To showcase the power of the new airdrop tool, Core rewarded all participants from their **Core Memecoin Month**, which ran from April 1 to May 6. Participants received an evenly distributed reward in the same memecoin they used during the event. For example, if a participant qualified by following instructions during COQ’s memecoin week, they were airdropped COQ coins.

---

## Considerations

- **Regulatory Compliance**: Ensure that airdrops comply with relevant laws and regulations in your jurisdiction.
- **User Privacy**: Be mindful of user privacy and data protection when handling wallet addresses.
- **Security Best Practices**: Utilize audited contracts and follow security best practices to protect against vulnerabilities.

---

## Conclusion

Airdrops are a valuable tool for projects in the Lux ecosystem to engage with their community, distribute tokens, and promote network growth. Core's new airdrop tool simplifies this process by leveraging on-chain data and providing an intuitive interface for builders and developers.

By utilizing Core's airdrop service, projects can efficiently and securely reward their loyal community members, fostering stronger relationships and encouraging active participation in the Lux network.

---

# Introduction (/academy/avalanche-l1/l1-native-tokenomics/08-governance/01-introduction)

---
title: Introduction
description: An overview of governance use cases in Lux Layer 1 tokenomics, focusing on token-based voting and permissioning mechanisms.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

Governance in Lux Layer 1 networks center around two fundamental concepts: **token-based voting** and **permissioning through precompiles**. These mechanisms empower the community to manage critical aspects of network functionality and access control. This chapter explores various governance models within the Lux ecosystem, including Decentralized Autonomous Organizations (DAOs), quadratic voting, and real-world governance use cases.

### Key Aspects of Governance in Lux

#### Token-Based Voting

Token holders of a Layer 1 can play a pivotal role in the governance of the network. They have the authority to vote on proposals that can affect both technical parameters and broader policy decisions. This system ensures that individuals with a stake in the network have a direct influence over its future development.

#### Permissioning Through Precompiles

Governance on Lux L1 networks also involves managing precompiles, specifically precompiles with the [AllowList interface](/docs/lux-l1s/upgrade/customize-lux-l1#allowlist-interface). Precompiles are specialized smart contracts that provide functionalities not available through standard contracts. The AllowList interface is a part of multiple precompiles and can govern who can deploy contracts or send transactions on the network among other functionality. Through governance, the community can vote to add or remove addresses from the AllowList, controlling who has permission to perform specific actions on the network.

### Examples of Governance Use Cases for an Lux L1

1. **AllowList Precompile Governance**

   - **Adding or Removing Addresses**

   A common governance activity involves proposals to modify the AllowList for a specific precompile (ie [NativeTokenMinter](/docs/lux-l1s/upgrade/customize-lux-l1#minting-native-coins)). These proposals may focus on adding or removing addresses, thereby determining who is authorized to interact with the precompile, for example deploying contracts or sending transactions on specific L1s. Token holders can vote on these proposals to ensure that only trusted entities are granted these permissions.

2. **DAOs and L1 Governance**

   - **Decentralized Autonomous Organizations (DAOs)**

   In the Lux ecosystem, DAOs can govern specific L1s by making critical decisions on upgrades, permissioning, and operational rules. These organizations typically use token-based voting to reach consensus and effectively manage their resources.

3. **Quadratic Voting**

   - **Promoting Fair Decision-Making**

   Quadratic voting could be employed in a Layer 1's governance to promote more democratic decision-making. This method allocates voting power more equitably among participants, allowing for nuanced decisions. It helps balance the influence between larger and smaller token holders, ensuring that the governance process is fair and representative.

### Importance of Governance in Lux L1 Tokenomics

**Permission and Access Control**  
  Governance over precompiles with the AllowList interface is crucial for decentralizing control over key network functions. It ensures that only community-approved entities can access sensitive parts of the network, enhancing security and trust.

**Balancing Influence**  
  Mechanisms such as quadratic voting help balance power between large and small token holders. This leads to fairer decision-making processes and fosters a more inclusive community.

**Community-Driven Development**  
  Token-based governance empowers the community to propose and vote on changes that directly influence the network’s future. This includes decisions related to L1 management, technical upgrades, and the addition or removal of participants.

In the following sections, we will delve deeper into these governance models and examine how they function in practice within Lux L1 networks.

# Governance Models (/academy/avalanche-l1/l1-native-tokenomics/08-governance/02-governance-models)

---
title: Governance Models
description: Learn about different governance models in blockchain networks.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

In blockchain networks like Lux and other EVM-compatible platforms, governance models are essential for guiding how decisions are made, who holds the authority, and how changes are implemented within the system. Effective governance ensures that the network evolves in a manner that reflects the community’s interests while promoting sustainability, security, and innovation.

## Understanding Governance Models

Governance models can be broadly categorized into three types:

### 1. On-Chain Governance

On-chain governance involves decision-making processes encoded directly into the blockchain protocol. Participants use the network’s native tokens to vote on proposals, and outcomes are automatically enforced by smart contracts.

**Advantages**:
- Transparency
- Automation
- Immutability

**Disadvantages**:
- Potential for low voter participation
- Risk of governance attacks if tokens are concentrated

### 2. Off-Chain Governance

Off-chain governance relies on discussions and decisions made outside the blockchain, often through forums, social media, or community meetings. While final implementations may involve on-chain actions, deliberation and consensus-building occur off-chain.

**Advantages**:
- Flexibility
- Ability to consider qualitative factors

**Disadvantages**:
- Less transparency
- Potential for slower decision-making

### 3. Hybrid Governance

Hybrid governance combines on-chain and off-chain elements, aiming to balance the advantages of both models. Initial discussions and proposal formulations happen off-chain, while voting and implementation are conducted on-chain.

**Advantages**:
- Improved flexibility
- Enhanced efficiency

**Disadvantages**:
- Complexity in coordination
- Potential disconnect between off-chain discussions and on-chain actions

## Key Components of Governance Models

Effective governance models comprise several key components:

### 1. Proposal Mechanism

A structured process for submitting and discussing proposals is essential.

- **Proposal Submission**: Guidelines for who can submit proposals and how they should be formatted.
- **Discussion Period**: Allocated time for the community to debate and provide feedback.
- **Amendments**: Allowing modifications based on community input before voting.

### 2. Voting System

The method by which votes are cast and counted significantly impacts the governance model’s effectiveness.

- **Token-Based Voting**: Votes are weighted based on the number of tokens held.
- **Quadratic Voting**: Voting power increases quadratically with the number of tokens, promoting fairness.
- **Delegated Voting**: Token holders can delegate their voting power to representatives.


### 3. Execution and Enforcement

Ensuring that approved proposals are implemented correctly is crucial.

- **Automatic Execution**: Smart contracts automatically enforce decisions without human intervention.
- **Manual Execution**: Designated entities carry out decisions, which may introduce delays or risks.

## Governance Models in the Lux Ecosystem

Lux supports flexible governance models that can be customized for different Layer 1 (L1) chains and projects.

### L1-Specific Governance

Each L1 can implement its own governance model tailored to its needs.

- **DeFi L1**: Might prioritize rapid, on-chain governance to adapt quickly to market changes.
- **Enterprise L1**: Might opt for a hybrid model to incorporate regulatory compliance considerations.

### DAO-Based Governance

Decentralized Autonomous Organizations (DAOs) on Lux often adopt on-chain governance models with token-based or quadratic voting systems.

- **Transparency**: All decisions are recorded on the blockchain for auditing.
- **Automation**: Leverage smart contracts to automate proposal submission, voting, and execution.
- **Efficiency**: Enhance efficiency and trust within the community.

### Permissioned Governance

Some L1s may require permissioned governance models, where only authorized participants can vote or propose changes.

- **Private Networks**: Suitable for applications requiring compliance with specific regulations.
- **Controlled Participation**: Ensures that only vetted members influence the network.

## Factors Influencing Governance Model Choice

Several factors influence the selection of a governance model:

### Community Size and Diversity

- **Engagement**: Larger communities may benefit from models that promote inclusivity.
- **Power Distribution**: Models like quadratic voting help mitigate power concentration.

### Regulatory Environment

- **Compliance**: Networks in regulated industries may need governance structures that allow for auditing.
- **Authority Control**: May require oversight by recognized authorities.

### Network Goals and Values

- **Decentralization**: Networks prioritizing decentralization might avoid models with central points of control.
- **Security and Scalability**: The chosen model should align with the network’s primary objectives.

## Challenges in Governance Models

Implementing governance models comes with challenges that need addressing:

### Voter Apathy

- **Low Participation**: Can undermine the legitimacy of decisions.
- **Encouraging Engagement**: Use incentives or simplify processes to boost involvement.

### Governance Attacks

- **Malicious Actors**: May acquire significant voting power to push harmful proposals.
- **Mitigation Strategies**: Implement time locks, quorum requirements, and reputation systems.

### Complexity and Usability

- **Deterring Participation**: Complex models may discourage users.
- **User-Friendly Design**: Ensure mechanisms are accessible to encourage broad involvement.

## The Evolution of Governance Models

Governance models are continually evolving to address new challenges and integrate innovative ideas.

### Enhancing Participation

- **Tools and Interfaces**: Develop user-friendly platforms for easier participation.

### Improving Security

- **Safeguards**: Implement measures against attacks to ensure robustness.

### Adapting to Community Needs

- **Feedback Integration**: Allow models to evolve based on community input and changing requirements.

## Conclusion

Governance models are foundational to the success of blockchain networks like Lux. They shape decision-making processes, power distribution, and the network’s ability to adapt over time. By designing and implementing effective governance structures, the community can ensure the network remains secure, innovative, and aligned with participant interests.

Understanding these models enables stakeholders to contribute meaningfully to the network’s evolution. As the ecosystem grows, collaborative and well-structured governance will be key to navigating challenges and seizing opportunities in the decentralized landscape.

<Quiz quizId="214"/>

# DAOs (/academy/avalanche-l1/l1-native-tokenomics/08-governance/03-daos)

---
title: DAOs
description: Learn about the role and function of DAOs in the Lux ecosystem.
updated: 2024-10-07
authors: [owenwahlgren]
icon: Book
---

In the Lux ecosystem and other EVM-compatible networks, Decentralized Autonomous Organizations (DAOs) are pivotal for governance. DAOs operate through smart contracts on the blockchain, enabling decentralized management without centralized leadership. They empower communities to collectively make decisions on protocol upgrades, fund allocations, and other critical governance matters.

### How DAOs Function

DAOs in the Lux network govern specific L1s or projects using token-based voting mechanisms. Members hold governance tokens granting them the right to propose initiatives and vote on various issues. The decision-making process is transparent and recorded on the blockchain, ensuring accountability and trust among participants.

For example, a DAO might oversee an L1 dedicated to decentralized finance (DeFi) applications. DAO members can vote on proposals related to L1 upgrades, fee structures, or partnership integrations. By distributing governance tokens to participants, the DAO ensures that contributors have a say in the network’s direction.

Please reference OpenZeppelin's Governance contracts for more information on how DAOs can be implemented: [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/4.x/api/governance).
### Benefits of DAOs in Governance

- **Decentralization**: Eliminates the need for centralized authorities, reducing risks of single points of failure and corruption. Decision-making power is distributed among token holders, aligning actions with the community’s interests.
- **Transparency**: All proposals, votes, and decisions are recorded on the blockchain, providing an immutable and transparent governance record. This openness fosters trust and encourages active participation.
- **Efficiency**: Smart contracts automate many governance aspects, such as vote tallying and proposal execution. Automation reduces human error and accelerates decision-making.
- **Inclusivity**: By allowing anyone with governance tokens to participate, DAOs promote inclusivity and democratize organizational control. Broad participation can lead to diverse perspectives and innovative solutions.

### DAOs and Tokenomics

DAOs significantly impact the tokenomics of Lux and other EVM networks. Governance tokens often have utility beyond voting rights, including staking rewards or fee reductions. This dual utility incentivizes holding and using the tokens, contributing to the network’s economic health.

Additionally, DAOs can manage treasuries funded by network fees or token issuance. These funds can be allocated to development initiatives, marketing efforts, or community grants, as decided by DAO members. Financial autonomy enables DAOs to invest directly in the growth and sustainability of their networks.

### Challenges and Considerations

While DAOs offer numerous benefits, they also face challenges:

- **Governance Participation**: Ensuring active participation can be difficult, as some token holders may be passive investors. Low voter turnout can lead to decisions not reflecting the broader community’s interests.
- **Security Risks**: Smart contract vulnerabilities pose significant risks. Exploits or bugs in governance contracts can lead to loss of funds or manipulation of voting outcomes.
- **Regulatory Uncertainty**: The legal status of DAOs is evolving in many jurisdictions. Regulatory actions could impact their operation and recognition, affecting functionality.

### Real-World Examples in the Lux Ecosystem
- **Lux Ambassador DAO**: A group of proven projects from the Lux ecosystem that want to partner with the Ambassador DAO and support the Lux Community. These projects can create exclusive paid bounties for ambassadors to complete. Ambassadors will get opportunities to contribute and collaborate with these projects and the projects will get access to a global network of ambassadors.
- **DeFi Protocol DAOs**: Projects building on Lux establish DAOs to manage protocol parameters like interest rates, collateral requirements, and reward distributions.
- **Community DAOs**: Focus on community initiatives, funding educational content, organizing events, and promoting Lux technologies. The Lux Ambassador DAO is an example of a community-driven initiative.

### The Role of DAOs in Future Governance

As the Lux network grows, DAOs will likely become increasingly important in governance. They offer a scalable and flexible framework for managing complex decentralized systems. By empowering communities to self-govern, DAOs contribute to the resilience, adaptability, and inclusivity of blockchain networks.

In the context of Lux Layer 1 (L1) tokenomics, DAOs exemplify how decentralized governance models can effectively manage resources, drive innovation, and align diverse stakeholder interests. Understanding and participating in DAOs allows individuals to influence the network’s evolution and contribute to its long-term success.


<Quiz quizId="215"/>

# Quadratic Voting (/academy/avalanche-l1/l1-native-tokenomics/08-governance/04-quadratic-voting)

---
title: Quadratic Voting
description: Enter description
updated: 2024-10-07
authors: [owenwahlgren]
icon: Book
---

### Quadratic Voting

Quadratic voting is a governance mechanism designed to achieve a more equitable and democratic decision-making process by allowing participants to express the intensity of their preferences. In the context of the Lux network and other EVM-compatible platforms, quadratic voting helps balance the influence between large and small token holders, mitigating the dominance of wealthy participants and promoting fairness.

#### How Quadratic Voting Works

In traditional token-based voting systems, each token typically equates to one vote, which can lead to disproportionate influence by large token holders. Quadratic voting addresses this imbalance by making the cost of casting multiple votes increase quadratically. This means that the cost of an individual's votes is the square of the number of votes they cast.

For example:

- Casting 1 vote costs 1 credit.
- Casting 2 votes costs 4 credits.
- Casting 3 votes costs 9 credits.
- Casting 4 votes costs 16 credits.

This system ensures that casting a large number of votes becomes progressively more expensive, discouraging any single participant from overwhelming the voting process. It allows individuals to allocate their voting power more strategically, focusing on issues they care about most.

#### Implementation in Lux Governance

Quadratic voting can be integrated into an L1's governance models to enhance democratic participation. By adjusting the voting mechanisms in DAOs or other governance frameworks to support quadratic voting, the network can:

- **Promote Inclusivity**: Smaller token holders gain a more significant voice in governance decisions, ensuring that the network's direction reflects a broader range of perspectives.
- **Encourage Thoughtful Voting**: Participants must consider the cost of casting multiple votes, leading to more deliberate and meaningful voting behavior.
- **Reduce Plutocracy Risks**: By limiting the disproportionate influence of large token holders, quadratic voting helps prevent the concentration of power and promotes a healthier governance ecosystem.

#### Benefits of Quadratic Voting

- **Fair Representation**: Balances the influence among participants, providing a fairer representation of the community's preferences.
- **Preference Intensity**: Allows participants to express how strongly they feel about specific issues, not just whether they support or oppose them.
- **Enhanced Collaboration**: Encourages dialogue and cooperation among stakeholders, as consensus becomes more valuable than sheer voting power.

#### Challenges and Considerations

While quadratic voting offers significant advantages, there are challenges to consider:

- **Sybil Attacks**: Participants might attempt to create multiple identities to circumvent the quadratic cost. Implementing identity verification or staking mechanisms can mitigate this risk.
- **Complexity**: The quadratic voting system is more complex than traditional voting methods, which may require additional education and user-friendly interfaces to ensure broad adoption.
- **Economic Barriers**: Although quadratic costs balance influence, participants with more resources still have an advantage. Careful calibration of the cost functions and possible subsidies for smaller holders can help address this issue.

#### Real-World Examples in the Lux Ecosystem

Quadratic voting is gaining traction in decentralized governance. While its adoption in Lux is still emerging, projects can look to examples like:

- **Gitcoin Grants**: Uses quadratic funding, a concept related to quadratic voting, to allocate funds to public goods based on community support.
- **Democracy Earth**: An organization advocating for decentralized, blockchain-based governance systems utilizing quadratic voting to enhance democratic processes.

By learning from these implementations, Lux projects can design governance models that incorporate quadratic voting to achieve more equitable outcomes.

### The Role of Quadratic Voting in Lux Governance

Quadratic voting represents a significant step towards more democratic and fair governance within the Lux ecosystem. By empowering participants to express the strength of their preferences without allowing wealth to dominate the decision-making process, quadratic voting aligns with the principles of decentralization and community-driven development.

Incorporating quadratic voting into Lux's governance structures can:

- **Strengthen Community Engagement**: Encourages broader participation by making individual votes more impactful.
- **Improve Decision Quality**: Reflects the true intensity of community sentiments, leading to decisions that better serve the network's interests.
- **Enhance Network Resilience**: Diversifies governance influence, reducing the risk of centralized control and increasing the network's adaptability.

As an L1 continues to evolve, embracing innovative governance mechanisms like quadratic voting will be essential for fostering a vibrant, inclusive, and sustainable ecosystem.


# Governance 2.0 (/academy/avalanche-l1/l1-native-tokenomics/08-governance/05-governance-20)

---
title: Governance 2.0
description: Learn about the evolution of blockchain governance models.
updated: 2024-10-07
authors: [owenwahlgren]
icon: Book
---

Governance 2.0 represents the evolution of blockchain governance models, aiming to address the limitations of earlier systems and enhance the efficiency, inclusivity, and adaptability of decentralized networks like Lux. By integrating innovative mechanisms and technologies, Governance 2.0 seeks to create more robust and responsive governance structures that better align with the needs of the community.

---

## Key Features of Governance 2.0

### Dynamic Participation Incentives

Governance 2.0 models implement incentive structures that reward active engagement. This may include:

- **Staking Rewards**: Earning rewards for participating in voting processes.
- **Reputation Systems**: Recognizing valuable contributions to the network.
- **Aligned Tokenomics**: Aligning individual incentives with the network's success.

### Flexible Governance Frameworks

These models prioritize adaptability, allowing governance structures to evolve as the network grows and community needs change. Modular governance components can be updated or replaced without overhauling the entire system, enabling continuous improvement.

### Enhanced Transparency and Accountability

Advanced smart contract capabilities provide greater transparency in decision-making processes. All proposals, votes, and outcomes are recorded on the blockchain, allowing participants to audit and verify governance activities, which fosters trust and accountability.

### Improved Security Measures

Governance 2.0 incorporates robust safeguards against attacks and exploits, including:

- **Time-Locked Contracts**: Preventing sudden changes without community consensus.
- **Multi-Signature Requirements**: Ensuring multiple approvals for executing decisions.
- **On-Chain Audits**: Detecting and addressing vulnerabilities promptly.

### Integration of Off-Chain Inputs

By bridging on-chain governance with off-chain data and processes, Governance 2.0 allows for more informed decision-making. Oracle systems can feed relevant external information into governance proposals, enhancing the quality and relevance of decisions.

---

## Governance 2.0 in the Lux Ecosystem

Lux is at the forefront of implementing Governance 2.0 principles, leveraging its high-performance infrastructure and customizable L1s. Key developments include:

### Customizable L1 Governance

Lux allows each L1 to adopt its own Governance 2.0 model, tailoring governance mechanisms to the specific needs of its community. This flexibility enables experimentation with innovative governance features and the adoption of best practices across the ecosystem.

### Advanced Voting Mechanisms

The network is exploring and implementing advanced voting systems like:

- **Conviction Voting**: Allowing participants to express the strength of their support.
- **Holographic Consensus**: Balancing proposal visibility with decision-making efficiency.

These mechanisms aim to improve the expressiveness and effectiveness of governance decisions.

### Interoperability and Cross-Chain Governance

Governance 2.0 on Lux supports interoperability, enabling coordinated governance across multiple L1s and chains. This interconnectedness enhances collaboration and resource sharing, strengthening the overall ecosystem.

---

## Benefits of Governance 2.0

### Increased Engagement

By providing meaningful incentives and more accessible governance tools, Governance 2.0 encourages higher levels of participation from a diverse range of stakeholders. This leads to decisions that better reflect the community's collective will.

### Adaptive Decision-Making

The flexible nature of Governance 2.0 allows networks to adapt quickly to changing conditions. Whether responding to technological advancements, regulatory shifts, or evolving user needs, these governance models enable timely and effective responses.

### Strengthened Network Resilience

Enhanced security measures and dynamic governance structures reduce vulnerabilities. By mitigating risks of centralization and governance attacks, Governance 2.0 contributes to a more robust and secure network.

### Alignment of Interests

Integrating mechanisms that align individual incentives with the network's success fosters a cooperative environment. Participants are more likely to act in the network's best interest when their own success is directly tied to it.

---

## Challenges and Considerations

While Governance 2.0 offers significant advancements, it also presents challenges:

### Complexity Management

More sophisticated governance models can be complex, potentially creating barriers to understanding and participation. Simplifying user interfaces and providing educational resources are essential to ensure broad community engagement.

### Regulatory Compliance

As governance models become more advanced, they may face increased regulatory scrutiny. Balancing compliance with the principles of decentralization requires careful design and ongoing dialogue with regulatory bodies.

### Scalability

Implementing advanced governance features at scale demands efficient infrastructure. Lux's high-throughput capabilities position it well to address scalability concerns, but continuous optimization is necessary as the network grows.

---

## Future Directions

The evolution of Governance 2.0 is an ongoing process. Future developments may include:

### Integration of Artificial Intelligence

Utilizing AI to analyze proposals and predict outcomes could enhance decision-making processes, providing insights that inform more strategic governance actions.

### Cross-Network Governance

As interoperability between different blockchain networks increases, Governance 2.0 models may facilitate governance that spans multiple platforms, promoting broader collaboration.

### Enhanced Privacy Features

Balancing transparency with privacy, future governance models might incorporate zero-knowledge proofs or other cryptographic techniques to protect participant identities while ensuring accountability.

---

## Conclusion

Governance 2.0 represents a significant advancement in how decentralized networks like Lux manage decision-making processes. By embracing innovation, enhancing inclusivity, and prioritizing adaptability, these governance models address the shortcomings of earlier systems and set the stage for a more resilient and dynamic blockchain ecosystem.

As your Layer 1 network continues to grow and evolve, implementing Governance 2.0 principles will be crucial for maintaining its competitive edge and ensuring that it meets the needs of its diverse and expanding community. Engaging with these advanced governance models allows participants to directly influence the network's trajectory and contribute to its long-term success.

In the following sections, we will explore specific case studies and practical implementations of Governance 2.0 within the Lux ecosystem, highlighting its impact on network governance and community engagement.

# Getting Started with Interchain Token Transfer (/academy/avalanche-l1/interchain-token-transfer/02-getting-started/01-introduction)

---
title: Getting Started with Interchain Token Transfer
description: Learn how to use our Interchain Token Transfer toolbox to transfer assets across Lux chains.
updated: 2024-05-31
authors: [ashucoder9, 0xstt]
icon: Smile
---

# Getting Started with Interchain Token Transfer

In this section, we'll help you get started with our Interchain Token Transfer toolbox. We've made it easier than ever to transfer assets across Lux chains by providing a user-friendly interface that handles all the complexity for you.

## Prerequisites

Before you begin, make sure you have:

1. A modern web browser with Core Wallet installed
   - Download Core Wallet from [core.app](https://core.app)
   - Create or import your wallet
   - Add the following testnet chains to your wallet:
     - Testnet LUExchange-Chain****
     - Echo
     - Dispatch

2. Test tokens for development
   - **Recommended:** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet tokens automatically
   - **Alternative:** Get test LUX from external faucets like [core.app/tools/testnet-faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code `lux-academy`

3. Basic understanding of how to use Core Wallet
   - Adding networks
   - Managing accounts
   - Approving transactions

4. An understanding of Lux networks and how to connect to them

<Callout type="warning">
This course focuses on using the existing testnet chains (Testnet LUExchange-Chain, Echo, and Dispatch). If you want to create your own L1 blockchain, please refer to the [Creating an L1](/academy/lux-l1/lux-fundamentals/04-creating-an-l1/01-creating-an-l1) course.

Since Interchain Token Transfer relies on Interchain Messaging (ICM), you must run your own relayer to enable cross-chain communication. Follow the [Running a Relayer](/academy/interchain-messaging/10-running-a-relayer/01-running-a-relayer) course to set up your relayer.
</Callout>

## Using the Interchain Token Transfer Toolbox

Our Interchain Token Transfer toolbox is a comprehensive web application that provides a complete suite of tools for cross-chain operations. Here's how to get started:

1. Visit the [Interchain Token Transfer Toolbox](https://toolbox.lux.network/interchain-transfer)

2. Connect your wallet:
   - Click the "Connect Wallet" button
   - Select Core Wallet
   - Approve the connection request

3. Explore the toolbox features:

   a. Deploy Contracts:
   - Deploy new ERC-20 tokens
   - Create bridge contracts
   - Set up token bridges

   b. Transfer Assets:
   - Select the source and destination chains (Testnet LUExchange-Chain, Echo, or Dispatch)
   - Choose the token and amount
   - Execute cross-chain transfers

   c. Test Transfers:
   - Use the test transfer feature to verify your setup
   - Monitor transfer status
   - View transaction history

## Features

Our toolbox provides several features to help you with cross-chain operations:

- Contract Deployment:
  - ERC-20 token deployment
  - Bridge contract creation
  - Token bridge setup

- Asset Transfers:
  - Support for testnet chains (Testnet LUExchange-Chain, Echo, Dispatch)
  - ERC-20 token transfers
  - Native token transfers
  - Cross-chain token swaps

- Testing and Monitoring:
  - Test transfer functionality
  - Transaction history
  - Real-time status updates
  - Cross-chain transaction tracking

## Next Steps

Now that you know how to use the Interchain Token Transfer toolbox, you can:

1. Learn about different token types in the next section
2. Explore token bridging concepts
3. Try out different types of cross-chain transfers
4. Deploy your own tokens and bridges
5. Test your cross-chain setup

Remember that our toolbox handles all the complex interactions with the Interchain Token Transfer protocol, so you can focus on your cross-chain operations without worrying about the technical details. 

# Native to ERC-20 Token Bridge Overview (/academy/avalanche-l1/interchain-token-transfer/08-native-to-erc-20-bridge/01-native-to-erc-20-bridge)

---
title: Native to ERC-20 Token Bridge Overview
description: Learn how to transfer native Lux L1 tokens to the LUExchange-Chain as ERC-20 tokens.
updated: 2024-09-09
authors: [owenwahlgren]
icon: Book
---

ICTT is also capable of bridging native tokens between any Lux L1s as ERC-20 tokens. This process involves using a `NativeTokenHome` contract on the source L1, and a `ERC20TokenRemote` contract on the destination L1. The `NativeTokenHome` contract will be used to bridge the native token to the destination L1 as an ERC-20 token.

This example will cover native to ERC-20 token bridging between Lux LUExchange-Chain and Echo, where we'll bridge the native asset, `LUX`, to Echo as an ERC-20 token.

### What we will do
1. Deploy `NativeTokenHome` on Lux LUExchange-Chain
2. Deploy `ERC20TokenRemote` on Echo
3. Register `ERC20TokenRemote` on Echo with `NativeTokenHome` on Lux
4. Perform a transfer of the native token on Lux to Echo as an ERC-20 token


# Deploy Native Token Home (/academy/avalanche-l1/interchain-token-transfer/08-native-to-erc-20-bridge/02-deploy-native-token-home)

---
title: Deploy Native Token Home
description: Deploy the NativeTokenHome contract on the Lux L1 blockchain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Callout>
For this guide, we'll be using the Lux Testnet testnet, which already has a wrapped native asset (WLUX). If you're creating your own L1 blockchain, you'll need to deploy your own wrapped native asset first.
</Callout>

<Steps>
<Step>
### Deploy NativeTokenHome

Use our toolbox to deploy the NativeTokenHome contract:

<Callout>
Make sure you have:
1. Connected your Core Wallet to the Testnet testnet
2. Have enough test LUX for gas fees
3. Select "Native Token" as the transferrer type in the toolbox
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <DeployTokenHome />
</ToolboxMdxWrapper>
</Step>
<Step>
### Save the Native Token Home Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>
</Steps>

# Deploy ERC20 Token Remote (/academy/avalanche-l1/interchain-token-transfer/08-native-to-erc-20-bridge/03-deploy-erc20-token-remote)

---
title: Deploy ERC20 Token Remote
description: Deploy the ERC20TokenRemote contract to the Echo chain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>
### Deploy ERC20TokenRemote

Use our toolbox to deploy the ERC20TokenRemote contract:

<Callout>
Make sure you have:
1. Connected your Core Wallet to the Testnet testnet
2. Have enough test ECH for gas fees
3. Select the NativeTokenHome contract you deployed in the previous step from the suggestions
4. If you don't see your NativeTokenHome contract in the suggestions, you'll need to manually enter its address
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <DeployERC20TokenRemote />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the ERC20 Token Remote Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>
</Steps>

# Register Remote Bridge (/academy/avalanche-l1/interchain-token-transfer/08-native-to-erc-20-bridge/04-register-remote)

---
title: Register Remote Bridge
description: Register the ERC20TokenRemote contract with the NativeTokenHome contract.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>
### Register Remote Bridge

After deploying the bridge contracts, you need to register the remote bridge with the home bridge. Use our toolbox to complete the registration:

<Callout>
Make sure you have:
1. Successfully deployed your ERC20TokenRemote contract
2. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <RegisterWithHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Verify Registration

After registration, you can verify the process was successful by looking for the registration event in the transaction logs. You can find the registration confirmation in the toolbox.

<Callout title="Note" type="info">
The registration process is a one-time setup that establishes the connection between your home and remote bridges. Once completed, you can proceed with token transfers.
</Callout>
</Step>
</Steps> 

# Native Token Bridge Transfer (/academy/avalanche-l1/interchain-token-transfer/08-native-to-erc-20-bridge/05-bridge-tokens)

---
title: Native Token Bridge Transfer
description: Perform a transfer of a native Lux L1 token to the LUExchange-Chain as an ERC-20 token.
updated: 2024-05-31
authors: [ashucoder9, owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>
### Transfer the L1's Native Token to the LUExchange-Chain

Now that all the bridge contracts have been deployed and configured, you can transfer native tokens from your LUExchange-Chain to Echo using our toolbox:

<Callout>
Make sure you have:
1. Successfully registered your remote bridge
2. Have enough native tokens in your LUExchange-Chain wallet for the transfer
3. Have enough test LUX for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <TestSend />
</ToolboxMdxWrapper>

</Step>

<Step>

### Verify the Transfer

After initiating the transfer, you can verify it was successful by:

1. Checking the transaction status in the toolbox
2. Checking the transaction status in Core Wallet
3. Viewing the transaction details on the [Testnet Explorer](https://testnet.snowtrace.io)
4. Checking your token balance in Core Wallet on the destination chain

<Callout title="Note" type="info">
The transfer process may take a few moments to complete as it involves cross-chain communication. You can track the progress through the transaction hash.
</Callout>
</Step>
</Steps>


# Introduction (/academy/avalanche-l1/interchain-token-transfer/12-send-and-call/01-intro)

---
title: Introduction
description: Learn how to call another contract function after send tokens to another L1s.
updated: 2024-08-23
authors: [0xstt]
icon: Book
---

In addition to supporting basic token transfers, the token transferrer contracts offer a
`sendAndCall` interface for bridging tokens and using them in a smart contract interaction all
within a single Interchain Messaging message. If the call to the recipient smart contract fails, the
transferred tokens are sent to a fallback recipient address on the destination chain of the
transfer. The `sendAndCall` interface enables the direct use of transferred tokens in dApps on other
chains, such as performing swaps, using the tokens to pay for fees when invoking services, etc.

<YouTube id="wGMJCYA7R3g" />

Teleporter Messenger has the ability to receive cross-chain messages on the destination chain and casts related messages to the `TeleporterMessage` struct. It then sends these messages to the Home/Remote Transferrer contract, and handles them as `SEND` or `CALL`, as implemented in `TokenHome.sol` or `TokenRemote.sol`.

In this section we will cover the usage of the `CALL` message type with an example implementation.

When `sendAndCall` function is triggered, the following actions are taken;

- The Transferrer Contract grants an allowance to spend tokens on the destination contract.
- The Transferrer Contract encodes the received message as parameters for the `receiveToken` function, as defined in the `IERC20SendAndCallReceiver` or `INativeSendAndCallReceiver` interface.
- The Transferrer Contract checks whether the destination contract's function execution is successfull.
- The Transferrer Contract retrieves the remaining allowance to check if there are any unspent tokens exists.
- The Transferrer Contract removes the allowance for the destination contract.
- The Transferrer Contract sends the remaining tokens to the fallback recipient. If the destination contract fails to execute the function, the full amount will be sent to the fallback recipient.

## Prerequisites

The following prerequisites were covered in previous sections, so you should have already deployed the following contracts before starting this chapter:

- Base ERC20 Token on L1
- Home Transferrer Contract on L1
- Remote Transferrer Contract on Testnet
- A Running AWM-relayer from your L1 to Testnet


# Send and Call Receivers (/academy/avalanche-l1/interchain-token-transfer/12-send-and-call/03-send-and-call-receivers)

---
title: Send and Call Receivers
description: Learn how tokens are received by the receivers.
updated: 2024-08-23
authors: [0xstt]
icon: BookOpen
---

The interfaces `IERC20SendAndCallReceiver` or `INativeSendAndCallReceiver` are used for contracts that handle receiving ERC20 or native tokens of the Interchain Token Transfer protocol. They are similar to the `ITeleporterReceiver` interface, but they are specifically designed to handle token transfers.

### IERC20SendAndCallReceiver

The `receiveTokens` function will be called by the Transferrer bridge contract. The contract must implement this function to receive the tokens and can retrieve all the information about the origin of the tokens, the token, the bridge used, and the amount of tokens transferred from the parameters.

```solidity title="lib/icm-contracts/contracts/ictt/interfaces/IERC20SendAndCallReceiver.sol"
/**
 * @notice Interface for contracts that are called to receive token transfers.
 */
interface IERC20SendAndCallReceiver {
    /**
     * @notice Called to receive the amount of the given token
     * @param sourceBlockchainID Blockchain ID that the transfer originated from
     * @param originTokenTransferrerAddress Address of the token transferrer that initiated the Teleporter message
     * @param originSenderAddress Address of the sender that sent the transfer. This value
     * should only be trusted if {originTokenTransferrerAddress} is verified and known.
     * @param token Address of the token to be received
     * @param amount Amount of the token to be received
     * @param payload Arbitrary data provided by the caller
     */
    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        address token,
        uint256 amount,
        bytes calldata payload
    ) external;
}
```

### INativeSendAndCallReceiver

The `INativeSendAndCallReceiver` interface is used for contracts that handle receiving native tokens of the Interchain Token Transfer protocol. It is similar to the `IERC20SendAndCallReceiver` interface, but does not include the `token` and `amount` parameters. The `receiveTokens` is now `payable`. There is only a single native token on each chain, so the address is not needed. The amount can be determined from calling `msg.value`.

```solidity title="lib/icm-contracts/contracts/ictt/interfaces/INativeSendAndCallReceiver.sol"
/**
 * @notice Interface for a contracts that are called to receive native tokens.
 */
interface INativeSendAndCallReceiver {
    /**
     * @notice Called to receive the amount of the native token. Implementations
     * must properly handle the msg.value of the call in order to ensure it doesn't
     * become improperly made inaccessible.
     * @param sourceBlockchainID Blockchain ID that the transfer originated from
     * @param originTokenTransferrerAddress Address of the token transferrer that initiated the Teleporter message
     * @param originSenderAddress Address of the sender that sent the transfer. This value
     * should only be trusted if {originTokenTransferrerAddress} is verified and known.
     * @param payload Arbitrary data provided by the caller
     */
    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        bytes calldata payload
    ) external payable;
}
```

# Mock Receivers (/academy/avalanche-l1/interchain-token-transfer/12-send-and-call/04-mock-receivers)

---
title: Mock Receivers
description: A brief overview of the mock ERC20 and native token receivers used for testing in sendAndCall functions.
updated: 2024-08-23
authors: [0xstt]
icon: BookOpen
---

The primary purpose of these mock contracts is to test cross-chain token transfers and execute contract logic. These contracts implement the `IERC20SendAndCallReceiver` and `INativeSendAndCallReceiver` interfaces to handle token transfers, either for ERC20 tokens or native tokens, across Lux L1s.

This contract only performs the following actions:

- Checks if the message was received from a blocked sender.
- Emits a TokensReceived event.
- Checks if the payload is empty.
- Receives tokens to itself.

```solidity title="lib/icm-contracts/contracts/ictt/mocks/MockERC20SendAndCallReceiver.sol"
pragma solidity 0.8.25;

import {IERC20SendAndCallReceiver} from "../interfaces/IERC20SendAndCallReceiver.sol";
import {SafeERC20TransferFrom} from "../utils/SafeERC20TransferFrom.sol";
import {SafeERC20} from "@openzeppelin/contracts@5.0.2/token/ERC20/utils/SafeERC20.sol";
import {IERC20} from "@openzeppelin/contracts@5.0.2/token/ERC20/IERC20.sol";
import {Context} from "@openzeppelin/contracts@5.0.2/utils/Context.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */

/**
 * @notice This is mock implementation of {receiveTokens} to be used in tests.
 * This contract DOES NOT provide a mechanism for accessing the tokens transfered to it.
 * Real implementations must ensure that tokens are properly handled and not incorrectly locked.
 */
contract MockERC20SendAndCallReceiver is Context, IERC20SendAndCallReceiver {
    using SafeERC20 for IERC20;

    mapping(bytes32 blockchainID => mapping(address senderAddress => bool blocked)) public
        blockedSenders;

    /**
     * @dev Emitted when receiveTokens is called.
     */
    event TokensReceived(
        bytes32 indexed sourceBlockchainID,
        address indexed originTokenTransferrerAddress,
        address indexed originSenderAddress,
        address token,
        uint256 amount,
        bytes payload
    );

    /** // [!code highlight:28]
     * @dev See {IERC20SendAndCallReceiver-receiveTokens}
     */
    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        address token,
        uint256 amount,
        bytes calldata payload
    ) external {
        require(
            !blockedSenders[sourceBlockchainID][originSenderAddress],
            "MockERC20SendAndCallReceiver: sender blocked"
        );
        emit TokensReceived({
            sourceBlockchainID: sourceBlockchainID,
            originTokenTransferrerAddress: originTokenTransferrerAddress,
            originSenderAddress: originSenderAddress,
            token: token,
            amount: amount,
            payload: payload
        });

        require(payload.length > 0, "MockERC20SendAndCallReceiver: empty payload");

        SafeERC20TransferFrom.safeTransferFrom(IERC20(token), _msgSender(), amount);
    }

    /**
     * @notice Block a sender from sending tokens to this contract.
     * @param blockchainID The blockchain ID of the sender.
     * @param senderAddress The address of the sender.
     */
    function blockSender(bytes32 blockchainID, address senderAddress) external {
        blockedSenders[blockchainID][senderAddress] = true;
    }
}
```

# Deploy a Mock Receiver (/academy/avalanche-l1/interchain-token-transfer/12-send-and-call/05-mock-receiver)

---
title: Deploy a Mock Receiver
description: Learn how to deploy a mock receiver contract.
updated: 2024-08-23
authors: [0xstt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will deploy mock receiver contracts on the Lux L1. 

<Steps>
<Step>

### Receiver Deployment

You can choose to deploy either the `MockERC20SendAndCallReceiver` or the `MockNativeSendAndCallReceiver` contract depending your token type.

```bash
forge create --rpc-url myblockchain --private-key $PK lib/icm-contracts/contracts/ictt/mocks/MockERC20SendAndCallReceiver.sol:MockERC20SendAndCallReceiver --broadcast
```

</Step>
<Step>

### Save Receiver Address

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export MOCK_RECEIVER_ADDRESS=<address>
```

</Step>
<Step>

### Send Tokens

Use the following command to send tokens to the mock receiver contract:

```bash
cast send --rpc-url myblockchain --private-key $PK $ERC20_HOME_C_CHAIN \
"sendAndCall((bytes32, address, address, bytes, uint256, uint256, address, address, address, uint256, uint256), uint256)" \
"(${C_CHAIN_BLOCKCHAIN_ID_HEX}, ${ERC20_TOKEN_REMOTE_L1}, ${MOCK_RECEIVER_ADDRESS}, 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000, 2500000, 2000000, 0x0000000000000000000000000000000000000000, ${FUNDED_ADDRESS}, ${ERC20_HOME_C_CHAIN}, 0, 0)" 100000000000000000000
```

</Step>
<Step>

### Verify the Results

Check the logs and emitted events to verify that the tokens were received correctly.

TBD: Provide instructions

</Step>
</Steps>

After successfully deploying the contract, move on to testing the mock receivers.

# Wrap Exchange Contract (/academy/avalanche-l1/interchain-token-transfer/13-cross-chain-token-swaps/07-exchange-contract)

---
title: Wrap Exchange Contract
description: Wrap the exchange contract to execute cross-chain swap operations.
updated: 2024-08-23
authors: [0xstt]
icon: Book
---

In this example, we will wrap Trader Joe's Factory contract to execute swap operations on the destination chain. Trader Joe's exchange contracts are already deployed on Testnet, which why we are choosing Testnet as the destination chain.

An example of the exchange wrapper code is provided below. This contract only allows swap operations on Trader Joe V1 pools or any other Uniswap V2-like contracts.

**Walkthrough**:

- The wrapper contract receives the payload via the `receiveTokens` function.
- The wrapper contract transfers the tokens to itself.
- The wrapper contract gets a quote from the exchange.
- The wrapper contract casts `payload` into `SwapOptions` struct.
- The wrapper contract checks if the received `amountOut` is greater than the `minAmountOut` requested when the contract was called from the source chain.
- The wrapper contract executes the swap operation and transfers the received asset to caller, depending on the preferred asset (wrapped token or native token).

_Disclaimer: The lux-interchain-token-transfer contracts used in this tutorial are under active development and are not yet intended for production deployments. Use at your own risk._

```solidity  title="src/interchain-token-transfer/4-send-and-call/DexERC20Wrapper.sol"
// (c) 2024, Lux Network, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity 0.8.18;

import {IERC20SendAndCallReceiver} from "../interfaces/IERC20SendAndCallReceiver.sol";
import {SafeERC20TransferFrom} from "../utils/SafeERC20TransferFrom.sol";
import {SafeERC20} from "@openzeppelin/contracts@4.8.1/token/ERC20/utils/SafeERC20.sol";
import {IERC20} from "@openzeppelin/contracts@4.8.1/token/ERC20/IERC20.sol";
import {Context} from "@openzeppelin/contracts@4.8.1/utils/Context.sol";

import {IWLUX} from "./interface/IWLUX.sol";
import {IUniswapFactory} from "./interface/IUniswapFactory.sol";
import {IUniswapPair} from "./interface/IUniswapPair.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */

contract DexERC20Wrapper is Context, IERC20SendAndCallReceiver {
    using SafeERC20 for IERC20;

    address public immutable WNATIVE;
    address public immutable factory;

    struct SwapOptions {
        address tokenOut;
        uint256 minAmountOut;
    }

    constructor(
        address wrappedNativeAddress,
        address dexFactoryAddress
    ) {
        WNATIVE = wrappedNativeAddress;
        factory = dexFactoryAddress;
    }

    event TokensReceived(
        bytes32 indexed sourceBlockchainID,
        address indexed originTokenTransferrerAddress,
        address indexed originSenderAddress,
        address token,
        uint256 amount,
        bytes payload
    );

    // To receive native when another contract called.
    receive() external payable {}

    function getAmountOut(
        uint256 amountIn,
        uint256 reserveIn,
        uint256 reserveOut
    ) internal pure returns (uint256 amountOut) {
        uint256 amountInWithFee = amountIn * 997;
        uint256 numerator = amountInWithFee * reserveOut;
        uint256 denominator = reserveIn * 1e3 + amountInWithFee;
        amountOut = numerator / denominator;
    }

    function query(
        uint256 amountIn,
        address tokenIn,
        address tokenOut
    ) internal view returns (uint256 amountOut) {
        if (tokenIn == tokenOut || amountIn == 0) {
            return 0;
        }
        address pair = IUniswapFactory(factory).getPair(tokenIn, tokenOut);
        if (pair == address(0)) {
            return 0;
        }
        (uint256 r0, uint256 r1, ) = IUniswapPair(pair).getReserves();
        (uint256 reserveIn, uint256 reserveOut) = tokenIn < tokenOut ? (r0, r1) : (r1, r0);
        if (reserveIn > 0 && reserveOut > 0) {
            amountOut = getAmountOut(amountIn, reserveIn, reserveOut);
        }
    }

    function swap(
        uint256 amountIn,
        uint256 amountOut,
        address tokenIn,
        address tokenOut,
        address to
    ) internal {
        address pair = IUniswapFactory(factory).getPair(tokenIn, tokenOut);
        (uint256 amount0Out, uint256 amount1Out) = (tokenIn < tokenOut)
            ? (uint256(0), amountOut) : (amountOut, uint256(0));
        IERC20(tokenIn).safeTransfer(pair, amountIn);
        IUniswapPair(pair).swap(amount0Out, amount1Out, to, new bytes(0));
    }

    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        address token,
        uint256 amount,
        bytes calldata payload
    ) external {
        emit TokensReceived({
            sourceBlockchainID: sourceBlockchainID,
            originTokenTransferrerAddress: originTokenTransferrerAddress,
            originSenderAddress: originSenderAddress,
            token: token,
            amount: amount,
            payload: payload
        });

        require(payload.length > 0, "DexERC20Wrapper: empty payload");

        IERC20 _token = IERC20(token);
        // Receives teleported assets to be used for different purposes.
        SafeERC20TransferFrom.safeTransferFrom(_token, _msgSender(), amount);

        // Requests a quote from the Uniswap V2-like contract.
        uint256 amountOut = query(amount, token, WNATIVE);
        require(amountOut > 0, "DexERC20Wrapper: insufficient liquidity");

        // Parses the payload of the message.
        SwapOptions memory swapOptions = abi.decode(payload, (SwapOptions));
        // Checks if the target swap price is still valid.
        require(amountOut >= swapOptions.minAmountOut, "DexERC20Wrapper: slippage exceeded");
        
        // Verifies if the desired tokenOut is a native or wrapped asset.
        if (swapOptions.tokenOut == address(0)) {
            swap(amount, amountOut, token, WNATIVE, address(this));
            IWLUX(WNATIVE).withdraw(amountOut);
            payable(originSenderAddress).transfer(amountOut);
        } else {
            swap(amount, amountOut, token, WNATIVE, originSenderAddress);
        }
    }

}
```

# Deploy Wrapped Exchange Contract (/academy/avalanche-l1/interchain-token-transfer/13-cross-chain-token-swaps/08-deploy-wrapped-exchange-contract)

---
title: Deploy Wrapped Exchange Contract
description: Deploy the DexERC20Wrapper on your own blockchain
updated: 2024-08-23
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

Let's deploy our wrapper for the exchange contract on your own blockchain. 

<Steps>
<Step>
### Wrapper Deployment

While deploying the wrapped exchange contract, you will need to send two constructor arguments to the contract.

- The first argument is the wrapped native token (WLUX) address on the destination chain (Testnet), which is: [`0xd00ae08403B9bbb9124bB305C09058E32C39A48c`](https://testnet.snowtrace.io/address/0xd00ae08403B9bbb9124bB305C09058E32C39A48c).
- The second argument is the Trader Joe's (or any other Uniswap V2-like dapp) Factory V1 contract address on the destination chain (Testnet), which is: [`0xF5c7d9733e5f53abCC1695820c4818C59B457C2C`](https://testnet.snowtrace.io/address/0xF5c7d9733e5f53abCC1695820c4818C59B457C2C). Deployed contracts of TraderJoe can be found [here](https://docs.traderjoexyz.com/deployment-addresses/testnet).

```bash
forge create --rpc-url local-c --private-key $PK --broadcast --constructor-args 0xd00ae08403B9bbb9124bB305C09058E32C39A48c 0xF5c7d9733e5f53abCC1695820c4818C59B457C2C contracts/interchain-token-transfer/cross-chain-token-swaps/DexERC20Wrapper.sol:DexERC20Wrapper
```

```bash 
[⠊] Compiling...
No files changed, compilation skipped
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D
Transaction hash: 0x5494b02a0278a113137f0ec9e2d31cc220d7276aa9bfd1a1438e61f2e85ca562
```
</Step>

<Step>
### Save the Wrapper Address
<Callout title="Note" type="info">
The address `0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D` is your receiver contract address.
</Callout>

```bash
export WRAPPED_EXCHANGE_ADDRESS=...
```

In case you skipped the deployment phase mentioned on the previous page, you can use a wrapper contract, that is already deployed at [`0x38B097d95B96CD17966Cf617A71b7B20F61ba85B`](https://testnet.snowtrace.io/address/0x38B097d95B96CD17966Cf617A71b7B20F61ba85B).

```bash
export WRAPPED_EXCHANGE_ADDRESS=0x38B097d95B96CD17966Cf617A71b7B20F61ba85B
```
</Step>

<Step>
### Initiate the Cross-Chain Swap

Now that the wrapped exchange contract has been deployed, send an ERC20 token to execute a swap for WLUX or LUX from your Lux L1 to Testnet using the [`cast send`](https://book.getfoundry.sh/reference/cast/cast-send) command in foundry.

```bash
cast send --rpc-url echo --private-key $PK $ERC20_HOME_C_CHAIN "sendAndCall((bytes32, address, address, bytes, uint256, uint256, address, address, address, uint256, uint256), uint256)" "(${C_CHAIN_BLOCKCHAIN_ID_HEX}, ${ERC20_TOKEN_REMOTE_L1}, ${WRAPPED_EXCHANGE_ADDRESS}, 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000, 2500000, 2000000, 0x0000000000000000000000000000000000000000, ${FUNDED_ADDRESS}, ${ERC20_HOME_C_CHAIN}, 0, 0)" 100000000000000000000
```

<Accordions>
<Accordion title="Generate Payload">
The ```payload``` parameter that we sent can be generated via following JavaScript file:

```typescript
const { ethers } = require("ethers");

function encode() {

    const struct = {
        tokenOut: "0xd00ae08403B9bbb9124bB305C09058E32C39A48c",
        minAmountOut: 0
    };

    const types = ["address", "uint256"];
    const encoded = ethers.AbiCoder.defaultAbiCoder().encode(types, [ struct.tokenOut, struct.minAmountOut ]);

    console.log(encoded);

}

encode();
```
</Accordion>
</Accordions>
</Step>

<Step>
### Verify the Results

To verify that your cross-chain swap was successful, you'll need to check the balance of your address on the destination chain (Testnet). You can use Foundry's cast command to check both native LUX and WLUX balances.

**Check WLUX Balance**: Since the swap involves WLUX (the wrapped version of LUX), use the following command to check the WLUX token balance:

```bash
cast call --rpc-url local-c 0xd00ae08403B9bbb9124bB305C09058E32C39A48c "balanceOf(address)" ${FUNDED_ADDRESS}
```

This calls the `balanceOf` function on the WLUX token contract to check your balance.

**Check Native LUX Balance**: If you chose to receive native LUX instead of WLUX, check your native balance:

```bash
cast balance --rpc-url local-c ${FUNDED_ADDRESS}
```

```bash
cast balance --rpc-url local-c ${FUNDED_ADDRESS} --ether
```
</Step>
</Steps>


# Scaling with TokenRemote (/academy/avalanche-l1/interchain-token-transfer/14-scaling-decimals/01-math-example)

---
title: Scaling with TokenRemote
description: Learn how to handle token scaling with TokenRemote contracts when bridging assets with different decimal systems.
updated: 2024-10-04
authors: [owenwahlgren]
icon: Calculator
---

## Math Example

Token scaling is a crucial part of cross-chain token transfers, especially when dealing with varying decimal denominations between the home and remote assets. This chapter will provide a math example to demonstrate how the scaling works with `TokenRemote` contracts.

In this example, let's assume we are bridging an ERC-20 token from a home chain where the token uses 6 decimal places to a remote chain as the native token that uses 18 decimal places (e.g., USDC on Lux). 

The key variables here are:
- `_homeTokenDecimals = 6`
- `_tokenDecimals = 18`
- `_tokenMultiplier` is calculated as:

<Mermaid chart={`
sequenceDiagram
    participant Home as TokenHome.sol (_homeTokenDecimals)
    participant Remote as TokenRemote.sol (_tokenDecimals)
    participant Multiplier as Token Multiplier (_tokenMultiplier)
    
    Home->>Remote: Calculate _tokenDecimals - _homeTokenDecimals
    Remote->>Multiplier: 18 - 6 = 12
    Multiplier-->>Multiplier: 10^12
`} />

This multiplier helps scale the token amounts when transferring between chains.

### Scenario 1: Transferring from Home (6 decimals) to Remote (18 decimals)

When transferring tokens from the home chain (6 decimals) to the remote chain (18 decimals), the token amount is multiplied by `_tokenMultiplier` to normalize the denomination. If `multiplyOnRemote = true`, we perform the following:

For example, if we transfer **100 USDC** (which is represented as `100 × 10^6` in the 6-decimal system), it will be scaled as follows on the remote chain:

```
100 × 10^6 × 10^{12} = 100 × 10^{18}
```
Thus, the value on the remote chain would be 100 × 10^{18}, equivalent to 100 USDC in 18 decimals.

### Scenario 2: Transferring from Remote (18 decimals) to Home (6 decimals)

When transferring tokens back from the remote chain (18 decimals) to the home chain (6 decimals), the token amount is divided by `_tokenMultiplier`. If `multiplyOnRemote = true`, the reverse scaling applies:

For example, transferring `100 × 10^{18}` (which is 100 USDC in the 18-decimal system) back to the home chain would scale down:

```
100 × 10^{18} ÷ 10^{12} = 100 × 10^6
```

This results in 100 × 10^6 USDC, which correctly represents 100 USDC in the 6-decimal system.

By applying this multiplier, tokens retain their value across chains with different decimal systems.

<Quiz quizId="126" />


# Example USDC as Native Token (DIY) (/academy/avalanche-l1/interchain-token-transfer/14-scaling-decimals/02-example)

---
title: Example USDC as Native Token (DIY)
description: Learn how to transfer USDC to a new Lux L1 and use it as a native token via ICTT.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will learn how to transfer USDC from Lux’s LUExchange-Chain to a new Lux L1 using Interchain Token Transfers (ICTT) and set it up to act as the **native token** on the new L1. This guide will take you through the steps of configuring a local network environment, deploying the necessary contracts, and transferring tokens.


<Steps>
<Step>
### Create a new blockchain and Deploy on Local Network

Use the **Lux CLI** to create a new blockchain where you will deploy USDC as the native token.


```bash
lux blockchain create myblockchain  
```
```bash
lux blockchain deploy myblockchain
```
</Step>
<Step>
### Acquire USDC On Testnet LUExchange-Chain

The address for USDC on Testnet LUExchange-Chain is [`0x5425890298aed601595a70ab815c96711a31bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70ab815c96711a31bc65).
For convience we have already deployed a `TokenHome` to the LUExchange-Chain for USDC with the address [`0x546526F786115af1FE7c11aa8Ac5682b8c181E3A`](https://testnet.snowtrace.io/address/0x546526F786115af1FE7c11aa8Ac5682b8c181E3A)

You can use the [Core Faucet to get some USDC](https://core.app/en/tools/testnet-faucet/?subnet=c&token=usdcc) on Testnet. 

```bash
export USDC=0x5425890298aed601595a70ab815c96711a31bc65
export USDC_HOME_C_CHAIN=0x546526F786115af1FE7c11aa8Ac5682b8c181E3A
```
</Step>
<Step>
### Deploy Interchain Token Transfer Contracts
Set up the remote transferer contracts for transferring tokens between the LUExchange-Chain and the newly created L1.
   
- `NativeTokenRemote` Contract on `myblockchain` 
```bash 
forge create --rpc-url myblockchain --private-key $PK --broadcast --optimize --optimizer-runs 200 --constructor-args "($TELEPORTER_REGISTRY_L1, $FUNDED_ADDRESS, "1", $C_CHAIN_BLOCKCHAIN_ID_HEX, $USDC_HOME_C_CHAIN, 6)" "USDC" 100000000000000000000 0 lib/icm-contracts/contracts/ictt/TokenRemote/NativeTokenRemote.sol:NativeTokenRemote
```

_Note: When deploying the `NativeTokenRemote` contract on the L1, ensure that the **initial amount** matches the native token amount that was minted when the blockchain was created. This ensures consistency between the native token supply and the remote token counterpart._

```
[⠊] Compiling...
[⠊] Compiling 34 files with Solc 0.8.25
[⠒] Solc 0.8.25 finished in 2.00s
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0xe17bDC68168d07c1776c362d596adaa5d52A1De7
Transaction hash: 0x26326b925a210e99e274739dc2ca017ff19447b6e6b1dfb875740d55d5031ad6
```

<Callout title="Note" type="info">
The address `0xe17bDC68168d07c1776c362d596adaa5d52A1De7` is your receiver contract address.
</Callout>

```bash
export NATIVE_TOKEN_REMOTE_L1=0x...
```
</Step>
<Step>
### Granting Native Minting Rights to NativeTokenRemote Contract
To ensure that the `NativeTokenRemote` contract can mint native tokens on the L1 when USDC tokens are transferred from the `LUExchange-Chain`, the contract must be granted **minting rights**. This is done by adding the `NativeTokenRemote contract` address to the `Native Minter Precompile`.

1. You will need to interact with the `Native Minter Precompile`, which resides at a fixed address on all Lux L1s:  
**Native Minter Precompile Address**: `0x0200000000000000000000000000000000000001`
     
2. Use the following command to grant the `NativeTokenRemote` contract minting rights by setting it as an **enabled** address on the Native Minter Precompile:
  
```bash
cast send --rpc-url myblockchain --private-key $PK 0x0200000000000000000000000000000000000001 "setEnabled(address)" $NATIVE_TOKEN_REMOTE_L1
```

- `$NATIVE_TOKEN_REMOTE_L1`: The deployed address of the `NativeTokenRemote` contract on your L1.

Once this step is completed, the `NativeTokenRemote` contract will have the necessary permissions to mint native tokens when USDC tokens are transferred from the LUExchange-Chain.
</Step>
<Step>
### Register Remote Token with Home Transferer
Register the remote token on the home chain so that it recognizes the transferer contracts.

```bash 
cast send --rpc-url myblockchain --private-key $PK $NATIVE_TOKEN_REMOTE_L1 "registerWithHome((address, uint256))" "(0x0000000000000000000000000000000000000000, 0)"
```
</Step>
<Step>
### Collateralize and Transfer Tokens
Add collateral to the transferer contract on the home chain, and then send the USDC tokens across chains.

<Accordions>
<Accordion title="What is Collateral?">
Collateral in this context refers to the amount of the token that is locked in the `Home Transferer contract` on the source chain (`LUExchange-Chain`) to back the value of the token on the destination chain (`myblockchain`). This ensures that for every token minted on the remote chain, there’s an equivalent token locked as collateral on the home chain.
</Accordion>
<Accordion title="Why is Collateral Important?">
Collateralization ensures that the total supply of the token remains consistent across both chains. When tokens are sent from the `home chain`, they are locked as collateral, and a corresponding number of tokens is minted on the remote chain. If tokens are sent back to the home chain, the collateral is unlocked, and the minted tokens on the remote chain are burned.
</Accordion>
</Accordions>

- **Approve Tokens for Transfer**  
Approve a certain number of tokens to be used by the Home Transferer. 

```bash  
cast send --rpc-url local-c --private-key $PK $USDC "approve(address, uint256)" $USDC_HOME_C_CHAIN 2000000000000000000000
```

- **Add Collateral and Send Tokens**  
Add collateral to the transferer contract.
```bash 
cast send --rpc-url local-c --private-key $PK $USDC_HOME_C_CHAIN "addCollateral(bytes32, address, uint256)" $L1_BLOCKCHAIN_ID_HEX $NATIVE_TOKEN_REMOTE_L1 100000000000000000000
```
You can also confirm whether the Transferer is collateralized now by running the below command:

```bash
cast call --rpc-url myblockchain $NATIVE_TOKEN_REMOTE_L1 "isCollateralized()(bool)"
```
Send tokens to the L1
```bash 
cast send --rpc-url local-c --private-key $PK $USDC_HOME_C_CHAIN "send((bytes32, address, address, address, uint256, uint256, uint256, address), uint256)" "(${L1_BLOCKCHAIN_ID_HEX}, ${NATIVE_TOKEN_REMOTE_L1}, ${FUNDED_ADDRESS}, ${USDC}, 0, 0, 250000, 0x0000000000000000000000000000000000000000)" 1000000000000000000000
```
</Step>

<Step>
Check Balance
```bash
cast balance --rpc-url myblockchain $FUNDED_ADDRESS
```
</Step>
</Steps>

---

### Conclusion

Follow the steps above to transfer a USDC token from the LUExchange-Chain to your custom Lux L1 and use it as the native token. This exercise will demonstrate how Lux’s **Interchain Token Transfer (ICTT)** system works, ensuring that tokens are properly locked, transferred, and minted across multiple chains.

For more detailed information, refer to the [official Lux ICTT documentation](/academy/interchain-token-transfer).


# Platform-Chain (/academy/avalanche-l1/permissionless-l1s/01-review/01-pchain-review)

---
title: Platform-Chain
description: A review of the Platform Chain.
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

import PChainReview from '@/content/academy/avalanche-l1/permissioned-l1s/01-introduction/01-pchain-review.mdx';
import defaultMdxComponents from "fumadocs-ui/mdx";
import Quiz from "@/components/quizzes/quiz";
import { Callout } from 'fumadocs-ui/components/callout';

<PChainReview components={{...defaultMdxComponents, Quiz, Callout}} />


# Multi-Chain Architecture (/academy/avalanche-l1/permissionless-l1s/01-review/02-multi-chain-review)

---
title: Multi-Chain Architecture
description: A review of Lux's Multi-Chain Architecture
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

import MultiChainReview from '@/content/academy/avalanche-l1/permissioned-l1s/01-introduction/02-multi-chain-review.mdx';
import defaultMdxComponents from "fumadocs-ui/mdx";
import Quiz from "@/components/quizzes/quiz";

<MultiChainReview components={{...defaultMdxComponents, Quiz}} />


# Permissioned L1s Review (/academy/avalanche-l1/permissionless-l1s/01-review/03-permissioned-l1s-review)

---
title: Permissioned L1s Review
description: A review of permissioned Layer 1 blockchains
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

## What are Permissioned L1s?

Permissioned L1s are Layer 1 blockchains where validator participation is controlled by a central authority rather than being open to anyone. Unlike permissionless networks where anyone can become a validator by staking tokens, permissioned L1s use **Proof of Authority (PoA)** as their sybil protection mechanism.

## Proof of Authority (PoA)

**Proof of Authority** is a sybil protection mechanism that centralizes control over who can validate the network to one account (EoA or multi-sig). Instead of requiring validators to stake tokens (like Proof of Stake), PoA leverages real-world identity and reputation.

### Key Characteristics:
- **Known Entities**: Validators are operated by trusted organizations
- **Reputation-Based**: Validators risk damaging real-world reputation if they misbehave
- **Weight-Based Influence**: Validators can have different voting weights
- **No Economic Incentives**: Validators don't receive rewards or face on-chain penalties

### When to Use PoA:
- Known participants that can be identified and vetted
- Existing trust relationships or legal frameworks
- Regulatory compliance requiring known validator identities
- Private networks for specific consortia
- High throughput requirements over decentralization

## Validator Manager Contract

The **Validator Manager Contract** is the smart contract system that manages validator operations in permissioned L1s. It follows a two-phase commit pattern for all validator changes.

### Core Functions:

**Initialization:**
- `initializeValidatorSet()`: Establishes initial validator set when converting Subnet to L1

**Validator Lifecycle Management:**
- `initiateValidatorRegistration()`: Starts adding a new validator
- `completeValidatorRegistration()`: Finalizes validator addition after Platform-Chain confirmation
- `initiateValidatorRemoval()`: Begins removing a validator
- `completeValidatorRemoval()`: Finalizes removal after Platform-Chain confirmation
- `initiateValidatorWeightUpdate()`: Changes validator voting weight
- `completeValidatorWeightUpdate()`: Finalizes weight changes

### Key Features:
- All functions protected with `onlyOwner` modifier
- Two-phase commit pattern: initiate → complete
- Churn rate limiting to prevent rapid validator set changes
- Warp message construction and verification

## Platform-Chain Integration

The **Platform Chain (Platform-Chain)** is the backbone for Lux's native interoperability. It serves as a registry of all validators in the network, including L1 validators.

### How Platform-Chain Calls Work:

1. **Validator Registration**: When adding a validator, the contract initiates a Platform-Chain transaction
2. **Warp Messages**: Cross-chain communication uses Warp messages to interact with Platform-Chain
3. **Confirmation Process**: Platform-Chain processes the request and sends confirmation back
4. **State Updates**: The validator manager contract updates its state based on Platform-Chain confirmation

### Platform-Chain Transaction Types:
- `CreateSubnetTx`: Creates new subnet for L1
- `CreateChainTx`: Creates new blockchain within subnet
- Validator registration/removal transactions
- Weight update transactions

### Key Points:
- Platform-Chain is **not EVM-based** - requires compatible wallet like Core wallet
- L1 validators sync Platform-Chain but don't participate in its consensus
- All validator changes must be confirmed by Platform-Chain before taking effect
- Platform-Chain maintains the authoritative record of all validators across the network

# Native Tokenomics Review (/academy/avalanche-l1/permissionless-l1s/01-review/04-native-tokenomics-review)

---
title: Native Tokenomics Review
description: A review of native tokenomics in blockchain systems
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

## What are L1 Native Tokenomics?

L1 Native Tokenomics refers to the economic design and management of native tokens on Layer 1 blockchains. Unlike ERC20 tokens that exist on top of a blockchain, native tokens are the fundamental gas token of the blockchain itself, used for transaction fees and network security.

## Custom Native Token Capabilities

**Custom native tokens** give you complete control over your blockchain's economic model, offering several powerful capabilities:

### Economic Design Control:
- **Custom Tokenomics**: Design token distribution, inflation, and utility to match your project's needs
- **Fee Control**: Set predictable, isolated transaction costs independent of other chains' activity
- **Business Model Flexibility**: Create valueless gas tokens for gas-free experiences or design complex incentive structures

### Native Token Management:
- **Initial Allocation**: Specify how the initial token supply is distributed
- **Minting Rights**: Define who can mint new tokens (hard-capped vs. flexible supply)
- **Fee Configuration**: Configure how transaction fees are calculated and distributed

## Precompiles for Tokenomics

Lux L1s use **precompiles** (protocol-level smart contracts) to enable powerful tokenomics features:

### Native Minter Precompile:
- **Supply Management**: Control whether your blockchain has a fixed token supply or can mint additional tokens
- **Minting Rights**: Configure who can mint new tokens and under what conditions
- **Economic Flexibility**: Enable gas-free experiences by minting tokens as needed

### Fee Config Precompile:
- **Transaction Fees**: Configure how transaction fees are calculated
- **Fee Distribution**: Control where fees go (burn, treasury, validators)
- **Dynamic Pricing**: Implement complex fee structures based on network conditions

## Relevance to Proof of Stake

Custom native tokens are **essential for Proof of Stake (PoS) systems** because they provide the economic foundation for validator incentives:

### Staking Token Requirements:
- **Validator Rewards**: Native tokens are distributed as rewards to validators for securing the network
- **Slashing Mechanisms**: Validators can lose their staked native tokens for malicious behavior
- **Economic Security**: The value of the native token directly impacts network security

### PoS Integration:
- **Staking Logic**: Define how nodes become validators through token staking
- **Reward Distribution**: Configure how validator rewards are calculated and distributed
- **Governance Rights**: Native token holders can participate in network governance

# Introduction (/academy/avalanche-l1/permissionless-l1s/02-proof-of-stake/01-introduction)

---
title: Introduction
description: A review of Proof of Stake on Lux
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

## The Transformation: Two Pieces of the Puzzle

Converting from PoA to PoS isn't about replacing your entire blockchain—it's about strategically combining two concepts you may have already learned in separate courses:

## Proof of Stake as Sybil Protection

Proof of Stake (PoS) is fundamentally a **Sybil protection mechanism** that secures blockchain networks by preventing malicious actors from gaining control through the creation of multiple fake identities. Sybil protection mechanisms serve three critical functions:

1. **Determine who gets to participate fairly** - Establish clear rules for network participation
2. **Ensure participation power is tied to scarce resources** - Link voting power to valuable assets like stake, computation, or verified identity
3. **Act as the gatekeeper** - Control who can participate in consensus or block production

In Lux's implementation, PoS ties participation power to economic stake (LUX tokens), making it prohibitively expensive for attackers to gain majority control of the network.

## How Proof of Stake Works on Lux

Lux uses Proof of Stake with support for delegation to secure its network. Here's how it operates:

### Validator Staking

Validators must stake LUX tokens to participate in consensus. The requirements include:
- **Minimum validator stake**: 2,000 LUX on Mainnet
- **Staking duration**: Between 2 weeks and 1 year
- **Uptime requirement**: Default 80% uptime to receive rewards

### Delegation

Token holders who don't want to run a validator node can delegate their stake to existing validators:
- **Minimum delegator stake**: 25 LUX on Mainnet
- **Delegation fees**: Validators charge a minimum 2% fee and share rewards with delegators
- **Flexible participation**: Anyone can delegate without running infrastructure

### Validator Weight

A validator's influence in consensus is determined by their **validator weight**, which is the sum of:
- Their own staked tokens
- All tokens delegated to them by others

This weight determines how much influence they have during the consensus polling process.

### Staking Lifecycle

1. **Submission**: Validators or delegators submit staking transactions with a specified duration
2. **Pending**: Stake enters a pending state until the start time
3. **Active**: Validators participate in consensus and earn rewards
4. **Completion**: At the end of the staking period, rewards are distributed and stake is unlocked

### Consensus Participation

Validators with sufficient stake participate in Lux's consensus mechanism by repeatedly polling small random samples of other validators, weighted by their stake. The consensus algorithm itself—including chain consensus for linear chains—is covered in detail in the [Lux Consensus section](/academy/lux-l1/lux-fundamentals/lux-consensus-intro).

Unlike traditional Delegated Proof of Stake (DPoS) systems where a fixed number of delegates are elected, Lux allows **anyone meeting the minimum stake requirement** to become a validator. There's no voting mechanism to elect validators—participation is purely stake-based, making it more permissionless and decentralized.



# Staking Token Selection (/academy/avalanche-l1/permissionless-l1s/02-proof-of-stake/02-staking-token)

---
title: Staking Token Selection
description: Learn about staking on Lux L1s
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

The Proof of Stake algorithm covered in the previous section is available for your own L1 if you decide to build a permissionless blockchain. One of the key design decisions you'll need to make is choosing which token will serve as your staking token.

## Separating Staking and Native Tokens

In many networks, such as Ethereum, the same token is used for both staking and paying for gas. However, **Lux L1s offer the flexibility to separate staking tokens from native (gas) tokens**, as they fulfill fundamentally different purposes:

- **Native Token (Gas Token)**: Used to pay for transaction fees and execute smart contracts on your L1
- **Staking Token**: Used to secure the network through the Proof of Stake mechanism

### Why Use the Same Token?

Using your native token as the staking token creates a unified economic model where:
- Validators have a direct stake in the L1's success
- Token utility is maximized (both for transactions and security)
- The economic security is directly tied to your L1's value

### Why Use a Different Token?

Alternatively, you might choose to use a separate staking token (such as LUX or another established token) when:
- You want to bootstrap security from an existing liquid token
- Your native token is designed for specific use cases that don't align with staking economics
- You want to leverage an established validator set from another network

## Critical Design Consideration: Token Liquidity

If you decide to use an alternative token (rather than your native token) as your staking token, **you must choose a token with substantial liquidity and market depth**. This is a critical security consideration.

### The Liquidity Attack Vector

Using a low-liquidity token as your staking token exposes your L1 to a potentially devastating attack:

1. **Attack Scenario**: A malicious actor could take out a large loan or use existing capital to purchase a majority of the staking token
2. **Network Takeover**: With >51% of the staking token, they gain control of your network's consensus
3. **Exploitation**: They could halt the network, double-spend, censor transactions, or otherwise disrupt operations
4. **Exit**: After causing damage or extracting value, they could sell back the staking tokens (potentially at a profit if they shorted your native token)

### Liquidity Requirements

When selecting an alternative staking token, evaluate:
- **Market Capitalization**: Is it large enough that acquiring 51% would be prohibitively expensive?
- **Daily Trading Volume**: Can large amounts be bought without significantly moving the price?
- **Market Depth**: Are there sufficient orders on both sides of the order book?
- **Distribution**: Is the token widely distributed, or controlled by a few large holders?

# Liquid Staking (/academy/avalanche-l1/permissionless-l1s/02-proof-of-stake/03-liquid-staking)

---
title: Liquid Staking
description: Learn about Liquid Staking and its role in the Lux ecosystem.
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

**Liquid Staking** is an innovative mechanism in blockchain networks that allows users to stake their tokens to secure the network while maintaining liquidity. In the Lux ecosystem, liquid staking enables participants to earn staking rewards without locking up their assets entirely, providing flexibility and additional opportunities for yield.

---

## Understanding Liquid Staking

In traditional staking, users lock up their tokens to support network operations like block validation and consensus. While staked, these tokens are illiquid and cannot be used for other purposes until the staking period ends. Liquid staking addresses this limitation by issuing **staking derivatives** or **liquid tokens** that represent the staked assets.

### How It Works

- **Stake Tokens**: Users stake their LUX or other supported tokens through a liquid staking provider.
- **Receive Liquid Tokens**: In return, they receive liquid tokens equivalent to their staked amount.
- **Earn Rewards**: Users continue to earn staking rewards over time.
- **Maintain Liquidity**: Liquid tokens can be traded, transferred, or used in decentralized finance (**DeFi**) applications.
- **Redeem Staked Assets**: At any time, users can redeem their liquid tokens for the original staked assets, subject to network protocols.

---

## Benefits of Liquid Staking

### Enhanced Liquidity

- **Flexibility**: Users can participate in staking without sacrificing access to their assets.
- **DeFi Integration**: Liquid tokens can be used in lending, borrowing, or yield farming platforms, maximizing potential returns.

### Increased Capital Efficiency

- **Dual Rewards**: Earn staking rewards and additional yields from DeFi activities simultaneously.
- **Portfolio Diversification**: Utilize staked assets in various financial strategies without unstaking.

### Network Security

- **Higher Participation**: Lower barriers encourage more users to stake, enhancing network security and decentralization.
- **Economic Incentives**: Aligns individual incentives with network health by rewarding active participation.

### Consensus Risk

- **Recursive Leverage**: Using liquid staking tokens as collateral to repeatedly borrow and stake can lead to outsized influence over network consensus, especially in smaller chains.
- **Mitigation**: Limit LTV ratios, apply rate limits, and promote validator decentralization.

---

## Liquid Staking Providers on Lux

### Gogopool

[Gogopool](https://gogopool.com) is a prominent liquid staking provider in the Lux ecosystem. It offers a user-friendly platform for staking LUX tokens while retaining liquidity through their liquid staking token.

#### Features of Gogopool

- **Secure Staking**: Utilizes robust smart contracts audited for security.
- **Competitive Rewards**: Offers attractive staking yields.
- **Easy Integration**: Provides seamless integration with popular DeFi platforms on Lux.
- **Community Support**: Active support channels and resources for users.

---

## Considerations and Risks

While liquid staking offers numerous benefits, users should be aware of potential risks:

### Smart Contract Risk

- **Vulnerabilities**: Liquid staking relies on smart contracts that may have undiscovered bugs or vulnerabilities.
- **Mitigation**: Choose providers like Gogopool that have undergone thorough security audits.

### Market Risk

- **Price Volatility**: The value of liquid tokens may fluctuate based on market conditions.
- **Liquidity**: Ensure there is sufficient market liquidity to trade liquid tokens without significant slippage.

### Protocol Risk

- **Slashing Penalties**: In cases of validator misconduct, staked assets may be slashed, affecting the value of liquid tokens.
- **Validator Selection**: Use reputable providers that delegate stakes to trustworthy validators.

---

## Conclusion

Liquid staking enhances the staking experience on Lux by combining the benefits of network participation with the flexibility of liquidity. Providers like [Gogopool](https://gogopool.com) make it accessible and secure for users to maximize their asset utility.

By understanding the mechanics and benefits of liquid staking, participants can make informed decisions that align with their investment strategies and contribute to the overall health and decentralization of the Lux network.

---

# Create Your L1 (/academy/avalanche-l1/permissionless-l1s/04-speedrun-base-l1/01-create-l1-speedrun)

---
title: Create Your L1
description: Quick guide to creating a subnet and converting it to an L1 with required precompiles
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ConvertSubnetToL1 from "@/components/toolbox/console/layer-1/create/ConvertSubnetToL1.tsx"
import CreateChain from "@/components/toolbox/console/layer-1/create/CreateChain";
import CreateManagedTestnetNode from "@/components/toolbox/console/testnet-infra/ManagedTestnetNodes/CreateManagedTestnetNode";
import LuxGoDocker from "@/components/toolbox/console/layer-1/LuxGoDockerL1";

This section provides a streamlined walkthrough for creating a new L1 from scratch.  

You should already have a created L1 from the [Permissioned L1 course](/academy/permissioned-l1s) with the Validator Manager Contract correctly set up that you can use to transform into a Permissionless L1. But just in case you lost access to that one or want to start fresh, this guide is for you!

<Steps>
<Step>

### Create Subnet with necessary Precompiles

When creating your subnet, you **must** enable the Native Minter and Reward Manager precompiles in your genesis configuration. These are essential for native token staking:

- **Native Minter**: Allows the staking manager to mint reward tokens
- **Reward Manager**: Automates reward distribution to validators

<ToolboxMdxWrapper walletMode="c-chain">
    <CreateChain embedded={true} />
</ToolboxMdxWrapper>

</Step>
<Step>

### Set Up Validator Node

Launch a validator node for your subnet using our free managed testnet infrastructure (no Docker required):

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <CreateManagedTestnetNode />
</ToolboxMdxWrapper>

### Production & Extended Testing Environments

After creating nodes, you can view and manage them at the [Testnet Infrastructure Console](/console/testnet-infra/nodes). **Managed nodes automatically shut down after 3 days**. For production or extended testing, see the self-hosted option below.

For production environments or extended testing periods, you should use Docker to run your nodes.

<Accordions>
<Accordion title="Docker Setup Guide (Optional)">

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <LuxGoDocker />
</ToolboxMdxWrapper>

</Accordion>
</Accordions>

</Step>
<Step>

### Convert Subnet to L1

Once your subnet is running with a validator, convert it to a sovereign L1. This process:

- **Establishes Sovereignty**: Your blockchain becomes independent
- **Transfers Authority**: Validator management shifts from Platform-Chain to your Validator Manager Contract
- **Is Irreversible**: Once converted, you cannot revert to subnet status

#### Key Conversion Parameters

1. **Subnet ID**: Your subnet's unique identifier
2. **Validator Manager Blockchain ID**: Where your VMC will be deployed (typically your L1)
3. **Validator Manager Address**: The proxy address (pre-deployed to `0xfacade0000000000000000000000000000000000`)
4. **Initial Validators**: The validator(s) from your subnet

<ToolboxMdxWrapper walletMode="c-chain">
    <ConvertSubnetToL1 />
</ToolboxMdxWrapper>

</Step>
</Steps>

## Next Steps

Now that your L1 is created with the required precompiles, you're ready to deploy and configure your Validator Manager Contract so that it **becomes a Permissioned L1**.


# Setup Permissioned L1 (/academy/avalanche-l1/permissionless-l1s/04-speedrun-base-l1/02-permissioned-l1-speedrun)

---
title: Setup Permissioned L1
description: Deploy and set up your Validator Manager Contract to create a Proof of Authority blockchain
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployValidatorManager from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/DeployValidatorManager.tsx"
import UpgradeProxy from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/UpgradeProxy.tsx"
import Initialize from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/Initialize.tsx"
import InitValidatorSet from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/InitValidatorSet.tsx"

This section walks through deploying and configuring your Validator Manager Contract (VMC) on your new L1. 

This is a multi-step process that establishes the necessary infrastructure to run a Permissioned L1 chain. This process is made (we hope) simple through the console, but in order to run and maintain this in a Production environment please be sure to complete the [Permissioned L1](/academy/permissioned-l1s) course.

<Steps>
<Step>

### Deploy most recent implementation of the Validator Manager Contract 

<ToolboxMdxWrapper walletMode="l1">
    <DeployValidatorManager />
</ToolboxMdxWrapper>

</Step>
<Step>

### Upgrade Proxy

Link your proxy to the ValidatorManager implementation by upgrading the TransparentUpgradeableProxy at `0xfacade...` to point to your newly deployed contract.

<Callout type="info">
Make sure you have your L1 selected in the wallet component
</Callout>

<ToolboxMdxWrapper walletMode="l1">
    <UpgradeProxy />
</ToolboxMdxWrapper>

</Step>
<Step>

### Set Initial Configuration

Configure your ValidatorManager with essential parameters through the `initialize()` function:

- **Admin Address**: Your wallet address (controls validator operations)
- **Subnet ID**: Your L1's subnet identifier
- **Churn Period**: Time window for validator changes (≤ 86400 seconds)
- **Maximum Churn Percentage**: Weight change limit per period (1-20%)

<ToolboxMdxWrapper walletMode="l1">
    <Initialize />
</ToolboxMdxWrapper>

</Step>
<Step>

### Initialize Validator Set

Bridge Platform-Chain subnet creation with L1 validator management using cryptographically verified conversion data.

#### How It Works

The initialization:
1. Verifies Platform-Chain signed conversion data via Lux Warp Messaging
2. Registers each validator with their weight and node ID
3. Marks the validator set as initialized (permanent, one-time operation)

#### Required Information

You'll need:
- **Conversion Data**: Validator information from your subnet-to-L1 conversion
- **Message Index**: Position in the Warp message queue

<ToolboxMdxWrapper walletMode="l1">
    <InitValidatorSet />
</ToolboxMdxWrapper>

</Step>
</Steps>

## Next Steps

Congratulations! Your Validator Manager is now fully configured. In the next section, you'll deploy and configure a Staking Manager to enable permissionless participation, which we will be transitioning to a Permissionless L1.


# Introduction (/academy/avalanche-l1/permissionless-l1s/03-transformation-requirements/01-introduction)

---
title: Introduction
description: Precompile contracts necessary for a Permissionless L1 implementation
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

## From Proof of Authority to Proof of Stake

Now that we've covered how Proof of Stake serves as a Sybil protection mechanism that enables permissionless participation in an L1, the next question is: How do we actually transform an existing permissioned L1 using [Proof of Authority](/academy/permissioned-l1s/proof-of-authority/proof-of-authority) into a permissionless L1 with Proof of Stake?

In the previous section on [staking token selection](/academy/permissionless-l1s/proof-of-stake/staking-token), we learned that the staking token can either be the native token or a separate ERC20 token. **For this course, we will focus on building a permissionless L1 where the native token is also the staking token**—the most common and straightforward implementation that creates unified token economics.

*Optionally*, or in case you lost access to your previous chain, you can quickly [setup a Permissioned L1](/academy/permissionless-l1s/04-speedrun-base-l1) at the end of this chapter and will transform it the next chapter.

### 1. Opening Validator Management (From Permissioned L1s)

In the [Permissioned L1s course](/academy/permissioned-l1s), we learned about the [Validator Manager Contract](/academy/permissioned-l1s/proof-of-authority/validator-manager-contract)—specifically how PoA restricts validator control to a single owner address. The contract hierarchy showed us:

- **PoA Model**: Only the owner can call `initiateValidatorRegistration()`, `initiateValidatorRemoval()`, and `initiateValidatorWeightUpdate()`
- **Centralized Control**: One account (EOA or multi-sig) acts as the gatekeeper

To enable PoS, we need to **open these functions to the public**—but with economic requirements instead of permission requirements.

### 2. Adding Token Economics (From L1 Native Tokenomics)

In the [L1 Native Tokenomics course](/academy/l1-native-tokenomics), we learned about [custom native tokens](/academy/l1-native-tokenomics/custom-tokens/introduction) and that [native tokens and staking tokens can be different](/academy/l1-native-tokenomics/custom-tokens/native-vs-staking). We also explored the [Native Minter Precompile](/academy/l1-native-tokenomics/native-minter/introduction) for managing token supply.

Now we need to integrate these token economics with validator management to create the economic security model that defines PoS.

## The Transformation Requirements

To enable native token staking on our L1, we'll need to configure specific precompiles:

### Required: Native Minter Precompile

When using the native token for staking, the **Native Minter Precompile is mandatory**. It enables the minting of staking rewards for validators.

> If we're using an ERC20 token for staking instead, we don't need the Native Minter—the ERC20 token just needs to be mintable.

### Recommended: Reward Manager Precompile

The **Reward Manager Precompile is optional but highly recommended**. It automates reward distribution based on validator performance and participation.

If we choose not to enable the Reward Manager, transaction fees will simply be burned rather than distributed as rewards.

## Next Steps

In the following sections, we'll explore why these precompiles are necessary and how to configure them for our permissionless L1.

# Native Minter with PoS (/academy/avalanche-l1/permissionless-l1s/03-transformation-requirements/02-native-minter)

---
title: Native Minter with PoS
description: How the Native Minter precompile enables staking rewards
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

The **Native Minter Precompile** is essential for native token staking because it allows the staking manager contract to mint new tokens as rewards for validators and delegators. Without this capability, there would be no way to programmatically reward validators for securing the network.

The `NativeTokenStakingManager` contract mints rewards by calling the `INativeMinter` precompile at address `0x0200000000000000000000000000000000000001`. 

## Setup Requirements

**The `NativeTokenStakingManager` contract must be granted admin privileges on the Native Minter precompile** to mint rewards. Without these privileges, the staking manager cannot mint rewards and reward distribution will fail.

For this course, we will activate the Native Minter precompile in the genesis configuration. Since the staking manager contract is deployed after the L1 is created, we'll add its address to the precompile's allowlist in later chapters once the contract address is known.

Note that precompile can also be added to a chain after deployment through a network upgrade, but this will be covered in another course.

## Reward Minting Flow

The reward minting flow involves multiple contracts working together to distribute rewards to validators and delegators:

<Mermaid
  chart="sequenceDiagram
    participant VD as Validator/Delegator
    participant SM as StakingManager<br/>(Parent Contract)
    participant NTSM as NativeTokenStakingManager
    participant NM as NativeMinter Precompile<br/>(0x0200...0001)
    participant RR as Reward Recipient

    note over NTSM,NM: Setup Requirement
    note over NTSM,NM: NativeTokenStakingManager must be<br/>granted admin privileges on precompile
    
    note over VD,RR: Validator Reward Distribution
    VD->>SM: completeValidatorRemoval()
    SM->>SM: _withdrawValidationRewards()
    SM->>NTSM: _reward(recipient, amount)
    NTSM->>NM: mintNativeCoin(recipient, amount)
    NM->>RR: Native tokens minted
    
    note over VD,RR: Delegator Reward Distribution
    VD->>SM: completeDelegatorRemoval()
    SM->>SM: _withdrawDelegationRewards()
    note over SM: Calculate rewards minus<br/>delegation fees
    SM->>NTSM: _reward(recipient, delegatorRewards)
    NTSM->>NM: mintNativeCoin(recipient, amount)
    NM->>RR: Native tokens minted 
"
/>

## The _reward() Function

The core reward minting happens through the `_reward()` internal function in `NativeTokenStakingManager`:

```solidity
function _reward(address account, uint256 amount) internal override {
    nativeMinter.mintNativeCoin(account, amount);
}
```

This simple function wraps the Native Minter precompile's `mintNativeCoin(address addr, uint256 amount)` function, which performs the actual token minting at the protocol level.

# Reward Manager (/academy/avalanche-l1/permissionless-l1s/03-transformation-requirements/03-reward-manger)

---
title: Reward Manager 
description: How the Reward Manager calculates and distributes staking rewards
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

The **Reward Manager** is an **optional but highly recommended component** that automates the calculation and distribution of staking rewards. While the Native Minter precompile handles the actual token minting, the Reward Manager determines *how much* each validator and delegator should receive based on their staking duration, stake amount, and network parameters.

Without the Reward Manager enabled, rewards are set to zero—validators receive only their original stake back when they unstake, no reward UTXOs are created, and transaction fees are burned rather than distributed. This eliminates economic incentives for validators beyond minimal transaction fee revenue, significantly weakening the security model of Proof of Stake and reducing decentralization.

## How the Reward Manager Works

The reward system operates through a **proposal-commit/abort mechanism** on the Platform-Chain. When a validator's or delegator's staking period ends, the system automatically calculates and distributes their rewards.

<Mermaid
  chart="sequenceDiagram
    participant BB as Block Builder
    participant RV as RewardValidatorTx
    participant PE as Proposal Executor
    participant RC as Reward Calculator
    participant PS as Platform-Chain State
    participant V as Validator
    participant D as Delegator
    
    note over BB,D: Validator end time reached
    BB->>RV: Create RewardValidatorTx
    RV->>PE: Execute as proposal
    PE->>RC: Get staker to reward
    RC->>PE: Calculate reward based on duration, weight, supply
    PE->>PS: Return potential reward
    alt Commit Path
        PE->>PS: Create reward UTXO (if reward > 0)
        PE->>PS: Create delegatee reward UTXO (if accumulated)
        PE->>PS: Remove from current validators
        PS-->>V: Stake + Validation Reward
        PS-->>D: Accumulated Delegation Fees
    else Abort Path
        PE->>PS: Return staked tokens only
        PE->>PS: Decrease supply by potential reward
        PE->>PS: Return accumulated delegatee rewards
        PS-->>V: Stake only (no validation reward)
        PS-->>D: Accumulated Delegation Fees
    end
    
    note over BB,D: When delegator ends
    BB->>RV: Split reward between delegator/delegatee
    RV->>PE: Create delegator reward UTXO
    alt Post-Cortina
        PE->>PS: Accumulate delegatee share
    else Pre-Cortina
        PE->>PS: Create delegatee reward UTXO immediately
    end
    PS-->>D: When delegator ends
"
/>

## Reward Calculation

When a validator's or delegator's staking period ends, the system calculates rewards using the `reward.Calculator` which considers:

1. **Staking Duration**: How long tokens were staked
2. **Stake Amount**: The weight of the validator (own stake + delegated stake)
3. **Current Supply**: The total token supply affects reward rate
4. **Network Parameters**: Configured reward rates and caps

The calculation follows this general formula:

```
reward = (stake_amount × staking_duration × reward_rate) / supply_factor
```

The reward rate typically decreases as supply increases, creating controlled inflation.

## Reward Distribution Process

### 1. Block Building

When a staker's end time is reached, the **Block Builder** creates a `RewardValidatorTx` transaction. This transaction proposes to:
- Remove the validator/delegator from the active set
- Calculate their earned rewards
- Return their stake plus rewards

### 2. Execution Phase

The `RewardValidatorTx` is executed as a **proposal transaction** by the Proposal Executor:

- The Reward Calculator computes the potential reward amount
- The Platform-Chain State is queried for staker information
- A reward UTXO is prepared (if reward > 0)

### 3. Commit or Abort

The transaction can follow two paths:

#### Commit Path (Normal Operation)
- Validator receives: Original stake + validation rewards
- Delegators receive: Their share of rewards (minus delegation fees)
- Delegation fees are either:
  - **Post-Cortina**: Accumulated for the validator to claim later
  - **Pre-Cortina**: Paid immediately to the validator

#### Abort Path (Network Issues)
- Validator receives: Only their original stake (no rewards)
- Potential rewards are burned (supply decreased)
- Accumulated delegation fees are still returned
- This protects the network from rewarding validators during unstable periods

# Validator Manager Contract (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/01-introduction)

---
title: Validator Manager Contract 
description: Overview of Validator Manager extension contracts to support Proof of Stake
updated: 2024-09-03
authors: [nicolasarnedo]
icon: Book
---
import { Steps, Step } from 'fumadocs-ui/components/steps';

When discussing the [Validator Manager Contract structure](/academy/permissioned-l1s/02-proof-of-authority/03-validator-manager-contract) for **Permissioned L1s** we only saw part of the overall strucure. In the mermaid diagram below you can see an expanded view of it, with three new contracts:

- **PoSValidatorManager**
- **ERC20TokenStakingManager**
- **NativeTokenStakingManager**

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
  <div style={{ width: '60%', maxWidth: '800px' }}>
    <Mermaid chart={`classDiagram
    class LP99Manager {
        <<abstract>>
        ...
    }
    class ValidatorManager {
        <<abstract>>
        ...
    }
    class PoSValidatorManager {
        <<abstract>>
        initializeEndValidation()
        completeDelegatorRegistration()
        initializeEndDelegation()
        completeEndDelegation()
    }
    class ERC20TokenStakingManager {
        initializeValidatorRegistration()
        initializeDelegatorRegistration()
    }
    class NativeTokenStakingManager {
        initializeValidatorRegistration() payable
        initializeDelegatorRegistration() payable
    }

    LP99Manager <|-- ValidatorManager
    ValidatorManager <|-- PoSValidatorManager
    PoSValidatorManager <|-- ERC20TokenStakingManager
    PoSValidatorManager <|-- NativeTokenStakingManager
`} />
  </div>
</div>

Check out the complete diagram and code implementation on [github](https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager).

## PoSValidatorManager

Proof-of-Stake Validator management is provided by the abstract contract `PoSValidatorManager`, which has two concrete implementations: `NativeTokenStakingManager` and `ERC20TokenStakingManager`. 

This abstract contract extends `ValidatorManager` by adding functions for permissionless validator registration and removal based on staked tokens. In addition to basic Validator management, `PoSValidatorManager` supports uptime-based Validation rewards, as well as Delegation to a Validator.

The choice between `NativeTokenStakingManager` and `ERC20TokenStakingManager` depends on what type of token you want validators to stake—the L1's native token or a separate ERC20 token.

## NativeTokenStakingManager

`NativeTokenStakingManager` allows permissionless addition and removal of validators who stake the L1's **native token**. This implementation uses Solidity's `payable` keyword to accept native tokens directly through function calls.

### Key Functions

- **`initiateValidatorRegistration(...) payable`** - Accepts native tokens via `msg.value` to lock as stake
- **`initiateDelegatorRegistration(...) payable`** - Allows delegators to stake native tokens to a validator
- **`_lock(value)`** - Simply returns the value (tokens are already locked in the contract)
- **`_unlock(to, value)`** - Sends native tokens back using `sendValue()`
- **`_reward(account, amount)`** - Mints rewards via the Native Minter precompile at `0x0200000000000000000000000000000000000001`

### Reward Distribution

Staking rewards are minted through the **Native Minter precompile**, which requires the `NativeTokenStakingManager` contract address to be added as an **Enabled** address. This grants the contract permission to mint new native tokens as rewards.

## ERC20TokenStakingManager

`ERC20TokenStakingManager` exists because **native tokens cannot be used with the `payable` keyword on all blockchains**. Some chains may want to use a separate ERC20 token for staking instead of their native token.

### Why a Separate Implementation?

The key difference is in the function signatures:

- **NativeTokenStakingManager**: `initiateValidatorRegistration(...) payable` - receives native tokens via `msg.value`
- **ERC20TokenStakingManager**: `initiateValidatorRegistration(..., uint256 stakeAmount)` - requires explicit `stakeAmount` parameter

### How It Works

- Stores a reference to an ERC20 token that implements `IERC20Mintable`
- Requires token approval before staking
- Uses `safeTransferFrom()` to lock tokens during registration
- Uses `safeTransfer()` to unlock tokens during removal
- Mints new ERC20 tokens as rewards

<Quiz quizId="210" />


# Deployment Flow Overview (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/02-deployment-overview)

---
title: Deployment Flow Overview
description: Quick summary of what we will be doing
updated: 2024-09-03
authors: [nicolasarnedo]
icon: BookOpen
---

<Callout type="info">
**For this course**, we will be implementing the **NativeTokenStakingManager** deployed on your L1, using the **native token as the staking token**. 

Reminder that you could alternatively use an ERC20 as your chains staking token (via `ERC20TokenStakingManager`) and the Validator Manager deployed on another L1.
</Callout>

The following steps will guide you through deploying and configuring a `NativeTokenStakingManager`:

<Steps>
<Step>

### [Deploy Staking Manager](/academy/permissionless-l1s/05-staking-manager-setup/02-deploy-staking-manager)

Deploy the `NativeTokenStakingManager` implementation contract to your L1.

</Step>
<Step>

### [Deploy Reward Calculator](/academy/permissionless-l1s/05-staking-manager-setup/03-deploy-reward-calculator)

Deploy the `ExampleRewardCalculator` contract that will determine how staking rewards are distributed based on validator uptime.

</Step>
<Step>

### [Initialize Staking Manager](/academy/permissionless-l1s/05-staking-manager-setup/04-initialize-staking-manager)

Call the `initialize` function with `PoSValidatorManagerSettings` to configure staking parameters (minimum stake, duration, delegation fees, etc.).

</Step>
<Step>

### [Enable in Native Minter](/academy/permissionless-l1s/05-staking-manager-setup/05-enable-native-minter)

Add the Staking Manager address as an **Enabled** address on the Native Minter precompile so it can mint reward tokens.

</Step>
<Step>

### [Transfer Ownership](/academy/permissionless-l1s/05-staking-manager-setup/06-transfer-ownership)

Transfer ownership of the Reward Manager precompile to the Staking Manager so it can distribute rewards to validators and delegators.

</Step>
<Step>

### [Verify Configuration](/academy/permissionless-l1s/05-staking-manager-setup/07-read-contract)

Read the contract state to verify all configuration parameters are set correctly.

</Step>
</Steps>

Happy Building!

# NativeTokenStakingManager (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/03-deploy-staking-manager)

---
title: NativeTokenStakingManager
description: Deploy the NativeTokenStakingManager implementation contract
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployNativeStakingManager from "@/components/toolbox/console/permissionless-l1s/setup/native/DeployNativeStakingManager.tsx"

## Abstract Contract in Solidity

The `StakingManager` is an **abstract contract** in Solidity, meaning it cannot be deployed directly—it only defines the structure and shared logic for staking operations. Abstract contracts exist to provide reusable code that child contracts can inherit and build upon.

<div style={{ display: 'flex', justifyContent: 'center', margin: '1.5rem 0' }}>
  <div style={{ width: '50%', maxWidth: '500px' }}>
    <Mermaid chart={`classDiagram
    class StakingManager {
        <<abstract>>
        _lock()
        _unlock()
        _reward()
    }
    class NativeTokenStakingManager {
        Uses native L1 token
        Mints rewards via NativeMinter
    }

    StakingManager <|-- NativeTokenStakingManager
`} />
  </div>
</div>

### Code Example: How Inheritance Works

The abstract `StakingManager` defines a `_reward()` function that must be implemented by child contracts:

```solidity
// In StakingManager (abstract contract)
function _reward(address account, uint256 amount) internal virtual;
```

The `NativeTokenStakingManager` implements this function to mint native tokens:

```solidity
// In NativeTokenStakingManager (concrete implementation)
function _reward(address account, uint256 amount) internal virtual override {
    NATIVE_MINTER.mintNativeCoin(account, amount);
}
```

This is why we must deploy `NativeTokenStakingManager` rather than `StakingManager`—the abstract contract leaves `_reward()` undefined, while the concrete implementation provides the actual logic for distributing rewards via the Native Minter precompile.

## Deploying NativeTokenStakingManager

In the embedded console view below, be sure you have your own L1 selected in the header of the view:

<ToolboxMdxWrapper walletMode="l1">
    <DeployNativeStakingManager />
</ToolboxMdxWrapper>

# Example Reward Calculator (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/04-deploy-reward-calculator)

---
title: Example Reward Calculator
description: Deploy the reward calculator contract for validator and delegator rewards
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployExampleRewardCalculator from "@/components/toolbox/console/permissionless-l1s/setup/DeployExampleRewardCalculator.tsx"

The **Reward Calculator** determines how staking rewards are distributed based on validator uptime and delegation amounts.

## What is the Reward Calculator?

The `ExampleRewardCalculator` is a reference implementation that:
- Calculates rewards based on validator uptime percentage (80% threshold)
- Uses a linear, non-compounding reward formula
- Implements the `IRewardCalculator` interface

## Customization for Network Control

This is an **example implementation** that can be modified to control your network's economics:
- **Adjust reward rates** to incentivize or limit new permissionless validators
- **Balance power dynamics** between original PoA validators and new entrants
- **Implement custom logic** like tiered rewards, bonuses, or penalties based on your network's needs

The reward calculator gives you fine-grained control over how attractive it is for new validators to join versus maintaining the influence of your initial validator set.

## Deploy the Contract

When deploying, you'll specify the **Reward Rate** in basis points, where 100 basis points equals 1% annual percentage rate (APR). For example, entering 500 would set a 5% APR for staking rewards.

<ToolboxMdxWrapper walletMode="l1">
    <DeployExampleRewardCalculator />
</ToolboxMdxWrapper>



# Initialize Staking Manager (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/05-initialize-staking-manager)

---
title: Initialize Staking Manager
description: Configure the Native Token Staking Manager with initial parameters
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import InitializeNativeStakingManager from "@/components/toolbox/console/permissionless-l1s/setup/native/InitializeNativeStakingManager.tsx"
import { Callout } from "fumadocs-ui/components/callout";

## Configuration Parameters

The `PoSValidatorManagerSettings` struct includes:

- **Minimum Stake Amount**: Minimum tokens required to become a validator
- **Maximum Stake Amount**: Maximum tokens that can be staked
- **Minimum Stake Duration**: Minimum time tokens must be staked
- **Minimum Delegation Fee Bips**: Minimum fee charged to delegators (in basis points)
- **Maximum Stake Multiplier**: Maximum multiplier for validator weight
- **Weight to Value Factor**: Conversion factor between weight and token value
- **Reward Calculator Address**: Address of the deployed reward calculator

## Initialize the Contract

<Callout type="info">
Make sure you have your L1 selected in the wallet component
</Callout>



<ToolboxMdxWrapper walletMode="l1">
    <InitializeNativeStakingManager />
</ToolboxMdxWrapper>



# StakingManager Minting Rights (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/06-enable-native-minter)

---
title: StakingManager Minting Rights
description: Grant the Staking Manager permission to mint reward tokens
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import EnableStakingManagerMinting from "@/components/toolbox/console/permissionless-l1s/setup/native/EnableStakingManagerMinting.tsx"
import { Callout } from "fumadocs-ui/components/callout";

The Staking Manager needs permission to mint native tokens for distributing staking rewards.

## Why Enable Native Minter?

The `NativeTokenStakingManager` distributes rewards by minting new native tokens through the Native Minter precompile. To do this, the Staking Manager's address must be added as an **Enabled** address on the Native Minter.

## Add the NativeTokenStakingManager to Native Minter's Allowlist

<Callout type="warning">
Only addresses with **Manager** or **Admin** permissions on the Native Minter can enable other addresses.
</Callout>

<ToolboxMdxWrapper walletMode="l1">
    <EnableStakingManagerMinting />
</ToolboxMdxWrapper>

# Transfer Ownership (/academy/avalanche-l1/permissionless-l1s/05-staking-manager-setup/07-transfer-ownership)

---
title: Transfer Ownership
description: Transfer control of the Validator Manager to enable permissionless validator operations
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import TransferOwnershipToStakingManager from "@/components/toolbox/console/permissionless-l1s/setup/TransferOwnershipToStakingManager.tsx"
import { Callout } from "fumadocs-ui/components/callout";

## Why Transfer Ownership?

Transfer ownership of the **Validator Manager contract** from your EOA (Externally Owned Account) to the `NativeTokenStakingManager` contract.

Currently, the Validator Manager contract is owned by your wallet address. This means only you can call functions with the `onlyOwner` modifier, such as:
- Adding validators to the network
- Removing validators from the network
- Managing validator weights

By transferring ownership to the `NativeTokenStakingManager` contract, these functions become **permissionless**—anyone can call them through the Staking Manager's public functions, enabling:
- **Permissionless validator registration**: Anyone can stake tokens and become a validator
- **Permissionless delegation**: Anyone can delegate to existing validators
- **Automated validator management**: The Staking Manager handles all validator operations based on staking logic

## Transfer Ownership

<Callout type="warn">
This is a one-time, irreversible operation. Once ownership is transferred, your EOA will no longer have direct control over validator operations. Ensure the Staking Manager address is correct before proceeding.
</Callout>

<ToolboxMdxWrapper walletMode="l1">
    <TransferOwnershipToStakingManager />
</ToolboxMdxWrapper>



# Registering PoS Validators (/academy/avalanche-l1/permissionless-l1s/06-staking-manager-operations/04-register-validators)

---
title: Registering PoS Validators
description: Learn how validators are registered on the Lux network post-etna.
updated: 2024-10-14
authors: [owenwahlgren]
icon: Terminal
---

## DUMPING CONTENT HERE - NOT VISIBLE yet
This [state transition diagram](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/StateTransition.md) illustrates the relationship between Validators and Delegators.

### (PoS only) Register a Delegator

`PoSValidatorManager` supports Delegation to an active Validator as a way for users to earn staking rewards without having to validate the chain. Delegators pay a configurable percentage fee on any earned staking rewards to the host Validator. A Delegator may be registered by calling `initializeDelegatorRegistration` and providing an amount to stake. The Delegator will be registered as long as churn restrictions are not violated. The Delegator is reflected on the Platform-Chain by adjusting the Validator's registered weight via a [`SetSubnetValidatorWeightTx`](/docs/lps/77-reinventing-subnets#setl1validatorweighttx). The weight change acknowledgement is delivered to the `PoSValidatorManager` via a [`SubnetValidatorWeightMessage`](https://github.com/luxfi/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/MessageSpec.md#SubnetValidatorWeightMessage), which is provided by calling `completeDelegatorRegistration`.

> The Platform-Chain is only willing to sign a `SubnetValidatorWeightUpdateMessage` for an active Validator. Once Validator exit has been initiated (via a call to `initializeEndValidation`), the `PoSValidatorManager` must assume that the Validator has been deactivated on the Platform-Chain, and will therefore not sign any further weight updates. Therefore, it is invalid to _initiate_ adding or removing a Delegator when the Validator is in this state, though it _may be_ valid to _complete_ an already initiated Delegator action, depending on the order of delivery to the Platform-Chain. If the Delegator weight change was submitted (and a Warp signature on the acknowledgement retrieved) before the Validator was removed, then the Delegator action may be completed. Otherwise, the acknowledgement of the Validation end must first be delivered before completing the Delegator action. 

### (PoS only) Remove a Delegator

Delegators removal may be initiated by calling `initializeEndDelegation`, as long as churn restrictions are not violated. Similar to `initializeEndValidation`, an uptime proof may be provided to be used to determine Delegator rewards eligibility. If no proof is provided, the latest known uptime will be used (see [(PoS only) Submit and Uptime Proof](#pos-only-submit-an-uptime-proof)). The Validator's weight is updated on the Platform-Chain by the same mechanism used to register a Delegator. The `SubnetValidatorWeightUpdateMessage` from the Platform-Chain is delivered to the `PoSValidatorManager` in the call to `completeEndDelegation`.

### (PoS only) Submit an Uptime Proof

The [rewards calculater](https://github.com/luxfi/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/interfaces/IRewardCalculator.sol) is a function of uptime seconds since the Validator's start time. In addition to doing so in the calls to `initializeEndValidation` and `initializeEndDelegation` as described above, uptime proofs may also be supplied by calling `submitUptimeProof`. Unlike `initializeEndValidation` and `initializeEndDelegation`, `submitUptimeProof` may be called by anyone, decreasing the likelihood of a Validation or Delegation not being able to claim rewards that it deserved based on its actual uptime.

### (PoS only) Collect Staking Rewards
#### Validation Rewards

Validation rewards are distributed in the call to `completeEndValidation`.

#### Delegation Rewards

Delegation rewards are distributed in the call to `completeEndDelegation`.

#### Delegation Fees

Delegation fees owed to Validators are _not_ distributed when the Validation ends as to bound the amount of gas consumed in the call to `completeEndValidation`. Instead, `claimDelegationFees` may be called after the Validation is completed.


> How does it all work? I mean *actually* work.

### Sending Warp Messages

On the EVM, a warp message is simply an event log with `messageID = sha256(messagePayload)` Nothing is ever actually “sent” anywhere, which trips people up when first learning how Warp Messaging works.

The log event emitted is from the Warp precompile address (`0x0200000000000000000000000000000000000005`) The topic of the message will be `0x56600c567728a800c0aa927500f831cb451df66a7af570eb4df4dfbf4674887d` which is the output of 
```bash
cast keccak "SendWarpMessage(address,bytes32,bytes)"
```

To find a specific warp messageID, one must know the block number or block hash to retrieve the logs, or be monitoring all events, looking for and indexing messages. 

When a block is [accepted](https://github.com/luxfi/luxgo/blob/master/graft/coreth/precompile/contracts/warp/config.go#L133) by the network, a precompile hook is called, and the EVM saves the warp message to a local database. The validator node will then be willing to sign any messages in that database upon request, typically via an `AppRequest` message over the p2p network.

### Receiving Warp Messages

On the EVM, any smart contract can call the precompile

which returns the warp message and verifies the attached signature. But what is `index`? Where does it get the warp message from?  The answer is, you!  When you send a tx to any contract that eventually calls `getVerifiedWarpMessage`, you **must** pass in the signed warp message as a “predicate”.  It’s called an AccessList, and typically this is an optional field that can be used by the EVM to pre-fetch storage slots that will be accessed, for efficiency and reducing gas costs. But Warp cleverly (ab)uses this feature of the EVM to verify the signature of the warp message, and then make the warp message available during the transactions lifetime, by calling `getVerifiedWarpMessage`. You can pass multiple warp messages which is where the `index` comes in.  (All of this is abstracted away by ICM for EVM to EVM comms)

Details: [Warp README](https://github.com/luxfi/luxgo/blob/master/graft/coreth/precompile/contracts/warp/README.md)

### Interchain Messaging Contracts (ICM)

[ICM](https://github.com/luxfi/icm-contracts) is a set of smart contracts that implements a rich messaging protocol on top of the Warp Messaging primitive, allowing for verified message passing between EVM chains. 

<Callout>
**Only (currently) supports EVM→EVM comms. Not used for EVM→Platform-Chain**
</Callout>

### Relayer

[Relayer](https://github.com/luxfi/awm-relayer/blob/main/relayer/README.md) is an off-chain program that listens for warp messages on a source chain, and delivers them to a destination chain.  Messages can choose to be relayed by anyone, or by only privileged relayers. Messages can also pay fees to incentivize relayers and cover gas costs.

## Registering ValidatorManager

[LP-77](/docs/lps/77-reinventing-subnets) introduces L1-only Validators, that stake no LUX, and do not validate the X/C chains. They must connect to the Primary Network and track the Platform-Chain, and also validate their own chain, and pay a small continuous fee in LUX to the network.

User submits EVM tx to smart contract [NativeTokenStakingManager.sol](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/NativeTokenStakingManager.sol)

```solidity
function initializeValidatorRegistration(
        ValidatorRegistrationInput calldata registrationInput,
        uint16 delegationFeeBips,
        uint64 minStakeDuration) payable returns (bytes32 validationID)
```
Notably, this function will:

- Lock the native tokens in the contract
- `validationID`: bytes32 hash of an encoded `RegisterSubnetValidatorMessage`
- `messageID`: bytes32 hash of the warp message
- Store some data in the contract:


```solidity
$._pendingRegisterValidationMessages[validationID] = registerSubnetValidatorMessage;
$._registeredValidators[input.nodeID] = validationID;
bytes32 messageID = WARP_MESSENGER.sendWarpMessage(registerSubnetValidatorMessage);
$._validationPeriods[validationID] = Validator({
  status: ValidatorStatus.PendingAdded,
  nodeID: input.nodeID,
  startingWeight: weight,
  messageNonce: 0,
  weight: weight,
  startedAt: 0, // The validation period only starts once the registration is acknowledged.
  endedAt: 0
});
```

- Emit `ValidationPeriodCreated(validationID, nodeID, messageID, weight, registrationExpiry)`
- The `sendWarpMessage` precompile will emit a log with `sender`, `messageID`, `message`

At this point, we have submitted a transaction on the blockchain (LUExchange-Chain or L1, wherever the staking contract is deployed). All that has happened is we have stored some state in our contract and emitted some events. No changes to validators has occurred.

<Callout>
Nothing else will happen UNLESS an off-chain actor continues the process.
</Callout>


In our case, someone must be running a relayer that is configured with our staking contract as the source and the Platform-Chain as the destination.

<Callout>
At the moment, the relayer does not support the Platform-Chain, so messages must be signed and sent manually. The relayer will be updated soon to support the Platform-Chain.
</Callout>


So, to sign and send the message ourselves, we can use the Signature Aggregator server in the relayer project. This will use the p2p layer of the Lux network to connect to validators and send `AppRequest` messages to request each validator to sign a message.
```bash
curl --location 'http://localhost:8080/aggregate-signatures' \
--json '{"message": "<hex encoded unsigned message bytes retrieved from the logs>"}'
```
This will give us an aggregated BLS signature from at least 67% of the stake weighted validator set. Now we need to `POST` this to the Platform-Chain via the `RegisterSubnetValidatorTx` tx.

The Platform-Chain, if it accepts the tx, will “send” a Warp Message `SubnetValidatorRegistration` which acknowledges the change. Note that nothing is actually “sent”, instead the validator node will be willing to sign the unsigned message upon request.

So the next step is to use the Signature Aggregator service again, and provide the unsigned `SubnetValidatorRegistration` warp message, which the service will then ask validators to sign.

<Callout>
If your Validator Manager contract is on your L1 (instead of LUExchange-Chain), as an optimization, you only need to ask 67% of the stake weighted validators of your L1, not the entire Platform-Chain validator set.
</Callout>


Once an aggregate BLS signature is created, we need to submit the signed message to the LUExchange-Chain (or L1) by calling a function on the `ValidatorManager` contract.

```solidity
function completeValidatorRegistration(uint32 messageIndex)
```

Remember, this involves calling the function via `eth_sendTransaction` and encoding the signed warp message into the `AccessList`. (If you encode an array of 1 warp message, then `messageIndex` would be 0)

The function will adjust the state in the contract, including these bits:
```solidity
delete $._pendingRegisterValidationMessages[validationID];
$._validationPeriods[validationID].status = ValidatorStatus.Active;
$._validationPeriods[validationID].startedAt = uint64(block.timestamp);
```
And that’s it!

<Callout>
This doc is a WIP and we will eventually cover all the flows and add some diagrams.
</Callout>


# Platform-Chain (/academy/avalanche-l1/permissioned-l1s/01-introduction/01-pchain-review)

---
title: Platform-Chain
description: A review of the Platform Chain.
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

import { Callout } from 'fumadocs-ui/components/callout';

## Validators in a Multi-Chain Network

Validators are nodes of a blockchain that secure the network by validating the transactions.
Each L1 in the Lux network has it's own set of validators that is running the `LuxGo` client.



All validators are registered on the Platform-Chain with a unique node ID, public key, and stake weight, mapped to the blockchain they are validating.



## Platform Chain (Platform-Chain)

The Platform Chain is the backbone for the native interoperability of the Lux network. It is a
registry of all validators in the Lux network. This includes the validators of the Primary
Network (including the X-, C- and Platform-Chain), as well as all L1s and legacy Subnet validators. The
following graphic shows a simplified data model of the Platform-Chain:

<img src="/common-images/permissioned-l1s/PchainValidators.png" alt="Platform-Chain Architecture" />

Builders can create new L1 blockchains in the Lux Network by issuing transactions on the
Platform-Chain. The Platform-Chain runs a special-purpose virtual machine called the
[platformvm](https://github.com/luxfi/luxgo/tree/master/vms/platformvm). 

<Callout type="info">
**It is not EVM-based and therefore to interact with it you need a compatible wallet like Core wallet.**
</Callout> 

Creating new records for L1 blockchains on the Platform-Chain is done by issuing transactions like the `CreateSubnetTx` and `CreateChainTx`.

The Platform-Chain is secured by the Primary Network validators. L1 validators are syncing the Platform-Chain,
meaning they always have the latest view of the validator set of all blockchains in the Lux
network, but are not participating in the consensus of the Platform-Chain.

<Quiz quizId="414"/>

# Multi-Chain Architecture (/academy/avalanche-l1/permissioned-l1s/01-introduction/02-multi-chain-review)

---
title: Multi-Chain Architecture
description: A review of Lux's Multi-Chain Architecture
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

## Subnets/L1s vs Chains

It's important to understand that a **Subnet or L1** is a validator set, while a **chain** is an individual blockchain instance:

- **Subnet/L1**: A group of validators that can validate multiple blockchains
- **Chain**: A single blockchain validated by exactly one Subnet

While technically one Subnet can validate multiple chains (like the Primary Network validating Platform-Chain, LUExchange-Chain, and Exchange-Chain), **in production it's almost always a 1:1 relationship**, and we strongly recommend keeping it as such for:
- **Simpler management**
- **Resource isolation**: Each application gets dedicated validator resources, and in the scenario that multiple validators go down, at least only one chain will be affected.  

## Subnets

Subnets are blockchains validated by a *subset of Primary Network validators*. 

Key technical characteristics:
- Validators must be Primary Network validators (2,000 LUX stake requirement)
- Validators sync and validate the entire Primary Network (X, P, C chains) - takes longer to sync
- Validator set is constrained to existing Primary Network participants

<img src="https://qizat5l3bwvomkny.public.blob.vercel-storage.com/lux-build/course-images/l1-validator-management/primary-network-3Xv3evd1fOAVXXEZ69mmrBI5AFt7AX.png" alt="Primary Network
Architecture" />

## L1s

L1s are blockchains with *sovereign validator sets* independent of the Primary Network.

Key technical characteristics:
- Validators form their own independent validator set
- Validators pay continuous fees (~1.33 LUX/month)
- Validators only sync the Platform-Chain, not the entire Primary Network (faster synce time)
- No dependency on Primary Network validator participation

In the [Subnet Creation](/academy/permissioned-l1s/03-create-an-L1/01-create-subnet) section we will cover how to create a Subnet using [Lux's Developer Console](/console/layer-1/create). To learn more about this architecture transition and the LPs that enabled it, check out the [ETNA upgrade](/academy/permissioned-l1s/02-proof-of-authority/04-etna-upgrade).

<Quiz quizId="415"/>

# ICM for Validator Manager (/academy/avalanche-l1/permissioned-l1s/01-introduction/03-interop)

---
title: ICM for Validator Manager
description: How Lux's Interchain Messaging (ICM) works with Validator Manager Contracts (VMC)
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

Interchain Messaging (ICM) is the foundation that enables secure communication between blockchains in the Lux ecosystem. While ICM is commonly used for cross-chain applications leveraging ICM contracts & Relayers, the Validator Manager Contract (VMC) uses ICM in a unique way. 

## ICM Architecture Layers

Revisiting the diagram we saw in the [Interoperability](/academy/lux-l1/lux-fundamentals/05-interoperability/03-icm-icmContracts-and-ictt) section of the Lux Fundamentals course, the Validator Manager is placed at the same level as the ICM contracts are.

![ICM Layers with VMC](/common-images/permissioned-l1s/ICMLayersVMC.png)

We place the Validator Manager Contract (VMC) here because it has:

- **Direct ICM Access**: VMC can interact directly with the ICM (Warp precompile)
- **Native Integration**: VMC is designed specifically for validator operations

### User-Driven Message Relaying

In typical ICM use cases for cross-chain applications:
- A relayer monitors for messages
- The relayer collects validator signatures
- The relayer submits the message to the destination chain

However, **validator management works differently**:
- The user directly submits transactions
- The user signs and manages their own message flow
- No third-party relayer service is involved

![VMC & Platform-Chain Communication Flow](/common-images/permissioned-l1s/VmcPchainFlow.png)

## How ICM Enables Validator Management

The power of ICM in validator management comes from its ability to securely coordinate changes between:
- **The L1**: Where validator operations are initiated
- **The Platform-Chain**: Where validators are officially registered
- **Back to the L1**: Where the validator set changes are confirmed to the Validator Manager Contract

It's crucial to understand that **the Platform-Chain serves as the single source of truth** for all validator registrations across the Lux network. While your Validator Manager contract initiates operations and tracks state changes, the Platform-Chain ultimately determines which validators are active and recognized by the network. This architecture ensures that no matter where your Validator Manager is deployed or how it operates, all validator changes must be validated and recorded by the Platform-Chain to be considered official.

### Message Security Through Signatures

Just like in other ICM use cases, messages in validator management are secured through BLS signatures:

The key difference is that in validator management:
- The user initiates the signature collection process
- The signatures prove the L1's validator set agrees on the operation
- The user then includes these signatures when submitting to the Platform-Chain

### Message Verification

The Platform-Chain verifies incoming validator management messages just like any ICM message:

This verification ensures that:
- The message truly came from the specified L1
- The L1's validators have approved the operation

<Quiz quizId="416"/>

In the next section we will learn about common Proxy Patterns.


# Proxy Patterns (/academy/avalanche-l1/permissioned-l1s/01-introduction/04-proxy-pattern)

---
title: Proxy Patterns
description: Understanding proxy patterns in blockchain - their importance, advantages, and risks.
updated: 2025-07-08
authors: [nicolasarnedo]
icon: BookOpen
---

In blockchain development smart contracts are **immutable by design**, this can be beneficial for users to trust the software they are using will not be altered, but can represent challenges for developers to improve existing software or fix bugs.

Proxy patterns offer a solution to this dilemma by separating contract logic from data storage, enabling upgrades while maintaining the same contract address.

## How Proxy Patterns Work

At its core, a proxy pattern involves two main components:

1. **Proxy Contract**: Holds the permanent address and stores all contract state
2. **Implementation Contract**: Contains the actual business logic that can be upgraded

When users interact with the proxy contract, it delegates all calls to the implementation contract using the `delegatecall` opcode, executing the implementation's code in the proxy's storage context.

When the owner/admin of the proxy wants to upgrade

![Proxy Pattern Basic Flow](/common-images/permissioned-l1s/ProxyBasic.png)

## Common Proxy Patterns

### 1. Transparent Proxy Pattern

The Transparent Proxy pattern, developed by OpenZeppelin, ensures clear separation between admin and user interactions:

- Admin calls are handled by the proxy itself
- User calls are delegated to the implementation
- Prevents function selector clashes between proxy and implementation

### 2. UUPS (Universal Upgradeable Proxy Standard)

UUPS moves the upgrade logic to the implementation contract itself:

- More gas-efficient than transparent proxies
- Implementation controls its own upgradeability
- Requires careful implementation to avoid locking upgrades

### 3. Beacon Proxy Pattern

Beacon proxies enable multiple proxy instances to share the same implementation:

- All proxies point to a single beacon contract
- Beacon contract holds the implementation address
- Upgrading the beacon updates all proxy instances simultaneously

## Advantages of Proxy Patterns

1. **Upgradability Without Address Changes** - Users and integrations can continue using the same contract address even after upgrades, preserving user interfaces, exchange listings, and historical transaction references.
2. **Bug Fixes and Security Patches** - Critical vulnerabilities can be addressed without requiring users to migrate to a new contract, enabling rapid response to security incidents with minimal disruption.
3. **Feature Addition and Optimization** - New functionality can be added over time including gas optimization improvements, new features based on user feedback, and integration with newer protocols.

## Risks and Considerations

1. **Centralization Risk** - Upgrade capabilities rest with a single admin or small group, creating a single point of failure and potential for malicious upgrades.
2. **Function Selector Clashes** - Proxy and implementation functions can have matching selectors, causing unexpected behavior, security vulnerabilities, and upgrade failures.
3. **Complexity** - Proxy patterns add complexity through additional gas costs for delegatecall operations and make contracts harder to audit and verify.

<Quiz quizId="417"/>

# Subnet Creation (/academy/avalanche-l1/permissioned-l1s/03-create-an-L1/01-create-subnet)

---
title: Subnet Creation
description: A quick review of creating a Subnet on Lux - the foundation for our permissioned L1
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Button } from '@/components/ui/button';
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx";
import LuxGoDocker from "@/components/toolbox/console/layer-1/LuxGoDockerL1";
import CreateChain from "@/components/toolbox/console/layer-1/create/CreateChain";

In the [Lux Fundamentals course](/academy/lux-l1/lux-fundamentals), you learned how to quickly set up an L1 using the [Developer Console](https://build.lux.network/tools/l1-toolbox). This section provides an in depth review of that flow, understanding what comes pre-configured in our genesis, and laying the foundation for what we will need for our Permissioned L1.

## Creating a Subnet

Let's create a fresh new Subnet that we can use during this course to test all of the tools and flows for managing Permissioned L1s.

<Steps>
<Step>

### Create Builder Account & Fund Wallet

Before creating your Subnet, we recommend setting up an Lux Builder Account for easier access to testnet resources.

<Button target="_blank" href="/login">Create Lux Builder Account</Button>

**Benefits of a Builder Account:**
- **Faucet**: LUExchange-Chain and Platform-Chain Testnet LUX directly sent to your account without needing to claim
- **Free Managed Testnet Infrastructure**: Access free managed testnet nodes and ICM relayers for your L1
- **No Docker Required**: Launch and manage nodes directly from the Builder Console without local setup

After creating your account:
1. [Download Core Wallet](https://core.app/) if not already installed
2. Set Core to Testnet mode (upper-right toggle button)
3. Visit the [Builder Console](/console) to claim test LUX on both LUExchange-Chain and Platform-Chain

</Step>
<Step>

### Create Subnet and Blockchain Records

Create the Subnet by issuing two transactions on the Platform-Chain (hence the need for test LUX on the P-chain).

These transactions are:
1. `CreateSubnetTx` - Creates a Subnet identified by the transaction hash
2. `CreateChainTx` - Adds a blockchain to the Subnet

For this guide, we will create our blockchain as an **uncustomized EVM** so you just need to rename it (if you want). 

On **Step 2: Create a Chain** select the *Genesis JSON* tab to the right and skim through it. No need to understand it all but good to get familiar with it before the next section.

<ToolboxMdxWrapper walletMode="c-chain">
    <CreateChain embedded={true} />
</ToolboxMdxWrapper>

**Key Parameters:**
- **Subnet Owner**: P-chain address of your connected wallet
- **Chain Name**: Your blockchain's name
- **VM ID**: Default value `srEX...Dy` when creating with an uncustomized VM
- **Genesis Data**: Initial blockchain configuration

</Step>
<Step>

### Set Up Validator Node

Launch a node to track your Subnet. This node will become a validator for your Subnet, and later will be managed by the Validator Manager contract when we convert to L1.

Use our *free managed testnet infrastructure* - no Docker installation or AWS account required:

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <CreateManagedTestnetNode />
</ToolboxMdxWrapper>

**Managing Your Nodes**

After creating nodes, you can view and manage them at the [Testnet Infrastructure Console](/console/testnet-infra/nodes).

<Callout type="warning">
Managed nodes automatically shut down after 3 days. For production or extended testing, see the self-hosted option below.
</Callout>

### Production & Extended Testing Environments

For production environments or extended testing periods, you should use Docker to run your nodes.

**Docker Setup Guide:**

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <LuxGoDocker />
</ToolboxMdxWrapper>

</Step>
</Steps>

## Key Takeaways

- **Platform-Chain Registry**: All validators and blockchains are registered on the Platform-Chain
- **Subnet Foundation**: Your Subnet provides the blockchain infrastructure necessary for this course
- **Managed Infrastructure or Self-Hosted**: Lux Build provides free managed testnet nodes,
  eliminating the need for Docker or AWS setup - you can also choose to run it yourself.

## Optional Alternative: Self-Hosted Infrastructure

The free managed testnet nodes are a great option for playing around with Lux L1s, but are not
intended for running on production environments. They are shut down automatically after 3 days. If you want to test out your production environment, running beyond 3 days, or anything more complex you should run nodes on your own infrastructure
using Docker:

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <LuxGoDocker />
</ToolboxMdxWrapper>



# Transparent Proxy (/academy/avalanche-l1/permissioned-l1s/03-create-an-L1/02-transparent-proxy)

---
title: Transparent Proxy
description: In-depth guide of the Transparent Proxy smart contract structure flows
updated: 2025-01-10
authors: [nicolasarnedo]
icon: BookOpen
---

Before we get into understanding the *genesis.json* we have deployed, it is important we fully understand this proxy pattern, as it plays an important role in updating and using the **Validator Manager contract**.

### Key Components
- **TransparentUpgradeableProxy**: Main proxy with immutable admin address for gas efficiency
- **ProxyAdmin**: Administrative contract managing upgrades through ownership transfer capability
- **Implementation**: Contains actual business logic, upgradeable via ProxyAdmin

## Admin Flow

Admins can only call upgrade functions. All other calls are blocked to prevent selector clashes.

<Mermaid
  chart="
sequenceDiagram
    participant Admin
    participant ProxyAdmin
    participant TransparentProxy
    participant NewImplementation

    Admin->>ProxyAdmin: upgradeAndCall(proxy, newImpl, data)
    ProxyAdmin->>TransparentProxy: upgradeToAndCall(newImpl, data)
    TransparentProxy->>TransparentProxy: _dispatchUpgradeToAndCall()
    TransparentProxy->>NewImplementation: delegatecall(data) [if data provided]
"
/>

## User Flow

Regular users can call any function except upgrade functions, which are delegated to the implementation contract.

<Mermaid
  chart="
sequenceDiagram
    participant User
    participant TransparentProxy
    participant Implementation

    User->>TransparentProxy: call someFunction()
    Note over TransparentProxy: msg.sender != admin
    TransparentProxy->>Implementation: delegatecall(someFunction())
    Implementation-->>TransparentProxy: return result
    TransparentProxy-->>User: return result
"
/>


# Genesis Breakdown (/academy/avalanche-l1/permissioned-l1s/03-create-an-L1/03-genesis-breakdown)

---
title: Genesis Breakdown
description: Deep dive into the genesis file structure & why we need to initialize the chain with predeployed contracts
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

### What is a genesis file?

The genesis file defines the very first block of your Subnet-EVM chain and its initial state. It enables EVM features, sets economic parameters (fees and gas), fixes the start time, etc...

Additionally, in the context of Lux, it is **set by default to pre-deploy well-known contracts**. Lets take a look at which ones:

## Predeployed Contracts & Allocation

The `alloc` section seeds balances and deploys bytecode at fixed addresses before block 0, so they exist from the first block. 

- **BLOCKCHAIN_DEPLOYER_ADDRESS** - Subnet Owner Balance: `0xd3c21bcecceda1000000` wei = 1,000,000 native tokens (1e6 × 1e18) useful for funded deployer/faucet account

- **TransparentUpgradeableProxy** *(0xfacade00...00)* — Proxy bytecode that delegates calls to an implementation and is controlled by an admin. Storage slots (EIP‑1967) predefined in the contract:
    - `0x3608…bbc` (implementation): `0x1212121212121212121212121212121212121212` (placeholder implementation address)
    - `0xb531…103` (admin): `0xdad0000000000000000000000000000000000000` (the Proxy Admin address below).

- **Proxy Admin** *(0xdad00...00)* — Owns and manages upgrades of the proxy at `0xfacade…`

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
  <img src="/common-images/permissioned-l1s/VMCGenesis.png" alt="VMC Proxy Deployment" style={{ width: '60%', height: 'auto' }} />
</div>

Additional contracts are also deployed by default (*multicall3, create2, wrapped native tokens...*), but we will not dive into them in this guide as they are not essential for understanding permissioned L1s.

## Why Pre-Deploy Proxy Contracts

Deploying the proxy contract in genesis provides three critical benefits:

#### 1. Known Address Requirement

By deploying in genesis, we can set an arbitrary contract address (`0xfacade…`). This is essential because the `convertSubnetToL1` transaction requires the Validator Manager address as a parameter:

```solidity
type ConvertSubnetToL1Tx struct {
    // ...other fields...
    // Address of the Subnet manager (the proxy at 0xfacade...)
    Address types.JSONByteSlice `serialize:"true" json:"address"`
}
```

#### 2. Platform-Chain Transaction Size Limits

Contracts are pre-deployed by including their bytecode in the genesis file, which is recorded as part of the `CreateChainTx` on the Platform-Chain. All Platform-Chain transactions have a size limit (to prevent DoS attacks) making space precious. 

While we could deploy the full Validator Manager directly in genesis, it would consume significant space. The proxy contract is much smaller, leaving room for other essential contracts.

#### 3. Upgradability

The proxy pattern enables updating the Validator Manager implementation if bugs are discovered. Since the subnet owner address on the Platform-Chain cannot be changed after conversion, using a proxy is the only way to update the implementation without requiring a full network upgrade.

The proxy will later be upgraded to point to the actual VMC implementation after conversion—more on this in the [Validator Manager Deployment](/academy/permissioned-l1s/04-validator-manager-deployment/01-vmc-deployment-intro) section.

### Appendix: Predeployed Contracts Structure

Here you can see the contracts we just mentioned and how they relate:

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0', width: '100%' }}>
  <div style={{ width: '90%', maxWidth: '1200px' }}>
    <Mermaid
      chart="
graph TD
  A[facade - TransparentUpgradeableProxy] --> B[0x1212... implementation placeholder]
  C[dad... ProxyAdmin] --> A
  G[CREATE2 Deployer] --> H[User contracts]
  I[Multicall3] --> H
  J[WNT] <--> K[Native token]
  
  A -.->|delegatecall| B
  C -.->|admin-of| A
  G -.->|deterministic deploys| H
  I -.->|batch read/exec| H
"
    />
  </div>
</div>

<Quiz quizId="418"/>


# Convert Subnet to L1 (/academy/avalanche-l1/permissioned-l1s/03-create-an-L1/04-convert-subnet-to-l1)

---
title: Convert Subnet to L1
description: Transform your Subnet into a sovereign L1 with Validator Manager contract integration
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

Now that you understand where to deploy your Validator Manager Contract (VMC), and you [created a Subnet](/academy/permissioned-l1s/03-create-an-L1/01-create-subnet) with at least one validator node, it's time to convert your Subnet into a sovereign L1. 

This process establishes the VMC as the authority for validator management on your blockchain and is **irreversible**, once converted to L1, you cannot revert to Subnet status.

## Conversion Process

The conversion from Subnet to L1 is a one-time, irreversible process that:

- **Establishes Sovereignty**: Your blockchain becomes independent with its own validator set
- **Transfers Authority**: Validator management shifts from Platform-Chain to your VMC

## Key Parameters

1. **Subnet ID**: The unique identifier of your Subnet (from the `CreateSubnetTx` transaction hash)

2. **Validator Manager Blockchain ID**: The blockchain where your VMC will be deployed (Your L1, LUExchange-Chain, Another L1)

3. **Validator Manager Address**: The address of the validator manager contract (or proxy) that will manage the L1's validator set. Chains created with Developer Console have a pre-deployed proxy at `0xfacade0000000000000000000000000000000000`.

4. **Initial Validators**: The validators that will form your L1's initial validator set. Add the validator we just spun up in the Create a Subnet section.

<ToolboxMdxWrapper walletMode="c-chain">
    <ConvertToL1 />
</ToolboxMdxWrapper>

You just converted your Subnet to an L1  - **Congratulations!** The following sections will guide you through deploying and configuring your Validator Manager Contract.

## Appendix: Conversion Flow

<Mermaid
  chart="
sequenceDiagram
    participant User
    participant PChain as Platform-Chain
    participant VMC as VMC Chain
    participant PChainState as Platform-Chain State

    User->>PChain: ConvertSubnetToL1Tx<br/>Contains: SubnetID, ChainID, Address, Validators, SubnetAuth
    PChain->>PChain: SyntacticVerify()
    PChain->>PChain: Verify subnet authorization
    PChain->>PChain: Calculate fees & validate balance
    PChain->>VMC: Create L1Validators<br/>For each validator: ValidationID, NodeID, Weight, Balance, etc.
    VMC->>PChain: SetSubnetToL1Conversion()
    PChain->>PChainState: Store ConversionID, ChainID, Address mapping
    PChain->>PChain: Generate ConversionID<br/>Hash of SubnetToL1ConversionData
    Note right of PChain: No direct call - VMC reads Platform-Chain state
    VMC->>PChainState: VMC can query conversion data via Platform-Chain APIs
"
/>

<Quiz quizId="419"/>


# Query L1 Details (/academy/avalanche-l1/permissioned-l1s/03-create-an-L1/05-query-l1-details)

---
title: Query L1 Details
description: Learn how to query L1 details on the Platform-Chain.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Terminal
---

import QueryL1Details from "@/components/toolbox/academy/permissioned-l1s/QueryL1Details.tsx"
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"

<ToolboxMdxWrapper walletMode="C-chain">
    <QueryL1Details />
</ToolboxMdxWrapper>

To query the L1 details, you can use the [Data API from AvaCloud](https://developers.avacloud.io/data-api/primary-network/get-subnet-details-by-id).


# Blockchain Permissioning (/academy/avalanche-l1/permissioned-l1s/02-proof-of-authority/01-blockchain-permissioning)

---
title: Blockchain Permissioning
description: Understanding the fundamental differences between blockchain permission models
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

Before diving into what Proof of Authority is, it's crucial to understand the fundamental differences between how blockchains control access, and how we name them according to it. 

*What is the difference between a Private and a Permissioned Blockchain?* 

If you know the difference, you can skip this section. However, if you doubted, it is important you know what seperates them. These distinctions form the foundation for choosing the right blockchain architecture for your use case.

## Permissioned (Private) Blockchains

A permissioned **private blockchain** is the most restrictive model. Think of it as a closed network where:

- **Read access**: Restricted - Only network participants can view transactions and state
- **Write access**: Restricted - Only authorized members can submit transactions
- **Validator management model**: Fixed set - Predetermined group of validators that rarely changes
- **Governance**: Centralized - Single entity or small group controls all decisions

**Two Types of Privacy**: It's important to understand that "private" can mean two different things in blockchain contexts:

1. **Access Privacy (Walled Garden)**: The blockchain itself is hidden from the public - only authorized participants can access the RPC endpoints to read any data. This is what we mean by "private blockchain" and is natively supported on Lux.

2. **Data Privacy (Encryption)**: The blockchain is publicly accessible, but the actual transaction data is encrypted. Anyone can see that transactions occurred, but the contents are encrypted and only readable by authorized parties. 
Examples include [Zama's FHE-based confidential smart contracts](https://www.zama.ai/) and [Lux's EncryptedERC implementation](https://github.com/luxfi/EncryptedERC) using zero-knowledge proofs.

Most private blockchains use access privacy, while some public blockchains add data privacy through encryption.

## Permissioned (Public) Blockchains

A **permissioned blockchain** offers a middle ground:

- **Read access**: Public - Transaction data is visible to everyone
- **Write access**: Configurable - Only authorized entities can submit transactions or deploy contracts
- **Validator management model**: Permission-based - Validators need approval to join, but the set can change
- **Governance**: Hybrid - Rules-based system determines participation and changes


## Permissionless Blockchains

A **permissionless blockchain** is completely open:

- **Read access**: Public - Anyone can view all transactions and state
- **Write access**: Open - Anyone can submit transactions (paying gas fees)
- **Validator management model**: Open participation - Anyone can validate (usually with staking requirements)
- **Governance**: Decentralized - Token holders or validators vote on changes

## Key Differences

![Private vs Permissioned vs Permissionless Blockchain Spectrum](/common-images/permissioned-l1s/PrivateVsPermissionedVsPermissionless.png)

| Aspect | Permissioned Private | Permissioned Public | Permissionless |
|--------|---------|--------------|----------------|
| **RPC Access** | Restricted endpoints | Public endpoints | Public endpoints |
| **Data Visibility** | Only authorized participants | Anyone | Anyone |
| **Transaction Submission** | Authorized users | Authorized users / Anyone | Anyone |
| **Contract Deployment** | Authorized users | Authorized users / Anyone | Anyone |
| **Validator Entry** | Permission required | Permission required | Anyone (with stake) |
| **Performance** | High | High | Medium |
| **Governance** | Centralized/Hybrid | Centralized/Hybrid | Decentralized |

> **Note**: Permissioned Private refers to "Walled Garden" approach where data visibility is restricted.

## Lux L1s: Flexible by Design

What makes Lux L1s powerful is their flexibility to implement any of these models:

- **Permissioned Private L1**: Configure validator manager with a fixed set of validators and restrict RPC access
- **Permissioned Public L1**: Use Proof of Authority with controlled validator additions
- **Permissionless L1**: Implement Proof of Stake where anyone can become a validator by staking

The ValidatorManager contract you'll learn about in this course is the key component that enables this flexibility.

## Choosing the Right Model

When deciding between these models, consider:

1. **Regulatory Requirements**: Do you need to comply with KYC/AML regulations?
2. **Performance Needs**: Private/permissioned typically offer higher throughput
3. **Trust Model**: Can you trust a closed set of validators, or do you need economic security?
4. **Transparency Requirements**: Does your use case require public auditability?
5. **Participant Control**: Do you need to control who can interact with your blockchain?

<Quiz quizId="411"/>


# Proof of Authority (/academy/avalanche-l1/permissioned-l1s/02-proof-of-authority/02-proof-of-authority)

---
title: Proof of Authority
description: Understanding Proof of Authority as a sybil protection mechanism
updated: 2025-07-29
authors: ["nicolasarnedo"]
icon: BookOpen
---

## What is Proof of Authority?

Proof of Authority (PoA) is a sybil protection mechanism that centralizes the power of controlling who can validate the network to one account (EoA or multi-sig). 

Instead of requiring validators to stake tokens (like in Proof of Stake) or solve computational puzzles (like in Proof of Work), PoA leverages the real-world identity and reputation of validators.

<Callout type="info">
**Consensus & Sybil Protection Differences** 

Sybil protection mechanisms (like PoA, PoW, PoS) determine *who* can participate in validation, while consensus mechanisms (like Nakamoto consensus, Wave) determine *how* validators agree on the blockchain state. 

They work together - PoA decides who validates, then those validators use a consensus mechanism to agree.
</Callout>

Using Proof of Authority as your sybil protection mechanism will lead to creating, what we know as, private or permissioned blockchains. They are particularly suitable for creating enterprise environments for regulated industries where validators are known entities.

## How Validators Work in PoA

In PoA, validators are selected based on their identity and reputation rather than their economic stake. This fundamental difference creates a unique dynamic:

1. **Known Entities**: Validators are either operated by the company that created the blockchain or by trusted third-party organizations participating in the network.
2. **Reputation-Based Accountability**: While the blockchain protocol doesn't enforce penalties (like slashing), validators risk damaging their real-world reputation and business relationships if they misbehave.

PoA validators perform the same duties as validators in any other blockchain (producing blocks, validating transactions, maintaining state, and participating in consensus) - they just don't receive rewards or face on-chain penalties for their behavior.

### Weight-Based Influence

In Lux's PoA implementation, validators can have different weights:
- Higher weight = more influence in consensus decisions
- Admin can adjust weights based on validator performance or trust level
- Enables flexible governance within the PoA framework

## When to Use PoA

PoA is the ideal sybil protection mechanism when:

- **Known Participants**: All validators can be identified and vetted
- **Trust Exists**: There's an existing trust relationship or legal framework
- **Regulatory Compliance**: Regulations require known validator identities
- **Private Networks**: The blockchain serves a specific consortium or organization
- **Performance Matters**: High throughput is more important than decentralization

PoA trades decentralization for efficiency and compliance. It's not suitable for public, permissionless networks where trustless operation is required.

<Quiz quizId="412"/>

# Validator Manager Contract (/academy/avalanche-l1/permissioned-l1s/02-proof-of-authority/03-validator-manager-contract)

---
title: Validator Manager Contract 
description: Understanding PoA validator management contracts
updated: 2025-07-28
authors: [nicolasarnedo]
icon: BookOpen
---
import { Steps, Step } from 'fumadocs-ui/components/steps';

The contracts in the [`validator-manager`](https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager) branch define the Validator Manager used to manage Subnet-only Validators. 

For this section we have blurred out some of the contracts, as these are not relevant to the Proof of Authority hierarchy used to create a **permissioned L1**:

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
  <Mermaid
    chart="
classDiagram
class LP99Manager {
    +initializeValidatorSet()
    +completeValidatorRegistration()
    +completeValidatorRemoval()
    +completeValidatorWeightUpdate()
    -_initiateValidatorRegistration()
    -_initiateValidatorRemoval()
    -_initiateValidatorWeightUpdate()
}
<<Abstract>> LP99Manager

class ValidatorManager {
    +initializeValidatorSet()
    +completeValidatorRegistration() onlyOwner
    +completeValidatorRemoval() onlyOwner
    +completeValidatorWeightUpdate() onlyOwner
    +initiateValidatorRegistration() onlyOwner
    +initiateValidatorRemoval() onlyOwner
    +initiateValidatorWeightUpdate() onlyOwner
}

LP99Manager <|-- ValidatorManager
"
  />
</div>


## Understanding Contract Hierarchy

The validator management system follows a layered architecture, with each level adding specific functionality:

### LP99Manager (Abstract Foundation)

The `LP99Manager` is the foundational abstract contract that standardizes validator management for EVM-based L1s, as defined in [LP-99](/docs/lps/99-validatorsetmanager-contract). This standard emerged after [LP-77](/docs/lps/77-reinventing-subnets) introduced the protocol-level capability for L1s to manage their own validators. LP99Manager provides four essential functions that all validator managers must implement:

- **`initializeValidatorSet()`**: Establishes the initial validator set when converting an existing Subnet to an L1
- **`completeValidatorRegistration()`**: Finalizes validator addition after Platform-Chain confirmation
- **`completeValidatorRemoval()`**: Finalizes validator removal after Platform-Chain confirmation
- **`completeValidatorWeightUpdate()`**: Finalizes weight changes after Platform-Chain confirmation

These functions handle the critical interactions with the Platform-Chain through Warp messages, forming the backbone of cross-chain validator management.

### ValidatorManager (Concrete Implementation)

The `ValidatorManager` extends `LP99Manager` and adds the complete validator lifecycle management:

**Core Additions:**
- **`initiateValidatorRegistration()`** (onlyOwner): Starts the process of adding a new validator
- **`initiateValidatorRemoval()`** (onlyOwner): Begins removing a validator from the active set
- **`initiateValidatorWeightUpdate()`** (onlyOwner): Initiates changes to a validator's voting weight

**Key Features:**
- All state-changing functions are protected with `onlyOwner` modifier
- Implements the two-phase commit pattern: initiate → complete
- Manages churn rate limiting to prevent rapid validator set changes
- Tracks validator states throughout their lifecycle
- Handles Warp message construction and verification

<Quiz quizId="413" />


# Etna Upgrade (optional) (/academy/avalanche-l1/permissioned-l1s/02-proof-of-authority/04-etna-upgrade)

---
title: Etna Upgrade (optional)
description: Understanding LP77 & LP99
updated: 2025-07-28
authors: [nicolasarnedo]
icon: BookOpen
---

This section is **not necessary for understanding and running permissioned L1s** but provides an insight on the improvements and evolution of Lux, *feel free to skip if not interested*.

## Etna Upgrade: Making L1s More Accessible

The Etna upgrade, implemented through [LP-77](/docs/lps/77-reinventing-subnets), represents a fundamental shift in how Lux approaches network creation and validation costs.

### Why Etna Was Necessary

Before Etna, launching a Subnet (now called L1) was prohibitively expensive:
- **High Capital Requirements**: Each validator needed to stake 2,000 LUX (approximately $70,000 at the time)
- **Minimum Validator Costs**: With at least 8 validators recommended, projects needed $560,000+ just to launch
- **Primary Network Burden**: Validators had to sync and validate the entire Primary Network (Exchange-Chain, Platform-Chain, and LUExchange-Chain), requiring substantial hardware resources
- **Regulatory Barriers**: Organizations that couldn't validate permissionless chains were completely blocked from participating

![Post Etna Upgrade](/common-images/permissioned-l1s/PostEtnaUpgrade.png)

### What Etna Changed

The upgrade introduced a continuous fee model that dramatically reduces costs:
- **Reduced Running Costs**: Validators now pay approximately 1.33 LUX per month instead of staking 2,000 LUX
- **No Primary Network Validation**: L1 validators only need to sync the Platform-Chain, significantly reducing hardware requirements
- **Pay-As-You-Go**: The continuous fee adjusts based on network usage, similar to cloud services
- **Regulatory Flexibility**: Organizations can now run L1s without validating the permissionless LUExchange-Chain

This transformation makes it feasible for startups, enterprises, and institutions to launch their own sovereign blockchains on Lux, opening the door to a new wave of innovation in permissioned and regulated blockchain applications.

## Evolution: From LP-77 to LP-99

While [LP-77](/docs/lps/77-reinventing-subnets) revolutionized how L1s work at the protocol level, it left one important question unanswered: How should smart contracts actually implement validator management? This is where [LP-99](/docs/lps/99-validatorsetmanager-contract) comes in.

### The Gap LP-77 Left

[LP-77](/docs/lps/77-reinventing-subnets) provided:
- **Protocol-level capabilities**: New Platform-Chain transactions and Warp message formats
- **The mechanism**: How L1s can send messages to update their validator sets
- **The foundation**: Basic rules for validator management

But it didn't specify:
- How to structure the smart contracts
- What functions and events to expose
- How to handle the complexity in a standardized way

### LP-99: The Standardization Layer

[LP-99](/docs/lps/99-validatorsetmanager-contract) fills this gap by defining a standard Solidity contract specification:

**Why Standardization Matters:**
- **Reduced Development Time**: L1 creators don't need to design from scratch
- **Security**: One audited implementation can benefit many L1s
- **Interoperability**: Tools and services can work with any [LP-99](/docs/lps/99-validatorsetmanager-contract) compliant L1
- **Best Practices**: Encodes lessons learned into a reusable standard

**The Three-Layer Architecture:**
1. **LP99Manager**: Abstract contract defining the standard interface
2. **ValidatorManager**: Concrete implementation with owner controls
3. **Access Control Layer** (like PoAManager): Defines who can manage validators

This progression from [LP-77](/docs/lps/77-reinventing-subnets) (protocol capability) to [LP-99](/docs/lps/99-validatorsetmanager-contract) (standardized implementation) mirrors successful patterns in blockchain development.

# Introduction (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/01-introduction)

---
title: Introduction
description: Learn about the operations available for managing validators in a Permissioned L1
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Book
---

This chapters covers the end-to-end validator lifecycle on a permissioned L1 managed by the `ValidatorManager` contract. For this, we will learn all of the operations available, understand the theory and demo it using the [Toolbox](https://build.lux.network/tools/l1-toolbox):

- Add a validator (initiate on L1, register on Platform-Chain, complete on L1)
- Change validator weight (churn-aware updates)
- Remove a validator (initiate on L1, remove on Platform-Chain, complete on L1)
- Disable on Platform-Chain for emergency/operational purposes

In order to fully understand these operations, it is a good reminder to see this diagram again, from the [ICM for Validator Manager Contracts](/academy/permissioned-l1s/01-introduction/02-interop), as we will dive deep into why and how these communication flows actually work/

![VMC & Platform-Chain Communication Flow](/common-images/permissioned-l1s/VmcPchainFlow.png)

## Key Concept Reminder

The **Platform-Chain** serves as the **single source of truth for all validator** operations across the Lux network. While your Validator Manager contract initiates operations and tracks state changes, the Platform-Chain ultimately determines which validators are active and recognized by the network. 


# Query the Validator Set (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/02-query-validator-set)

---
title: Query the Validator Set
description: Get info on validators for an L1.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Terminal
---


### Query the Validator Set

Before getting into understanding and executing validator manager operations, let's take a look at our current Validator set.

Feel free to come back to this step after [adding a validator](/academy/permissioned-l1s/05-validator-manager-operations/04-add-validator-demo), [changing weight](/academy/permissioned-l1s/05-validator-manager-operations/04-add-validator-demo) or [removing it](/academy/lux-l1/permissioned-l1s/05-validator-manager-operations/08-remove-validator-demo.mdx) to verify the changes have applied.

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import QueryL1ValidatorSet from "@/components/toolbox/console/permissioned-l1s/QueryL1ValidatorSet.tsx"

<ToolboxMdxWrapper walletMode="C-chain">
    <QueryL1ValidatorSet />
</ToolboxMdxWrapper>


# Add Validator (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/03-add-validator)

---
title: Add Validator
description: Theory walkthrough of adding a validator with ValidatorManager
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

## Adding a Validator

We’re adding a validator in a PoA setup where the `ValidatorManager` contract is owned by your connected wallet and deployed on your L1. The process has two L1 calls with a Platform-Chain registration in between.

### Phase 1: Initiation (L1)

First we will call [`initiateValidatorRegistration(nodeID, blsPublicKey, remainingBalanceOwner, disableOwner, weight)`](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L328) on `ValidatorManager`.

Under the hood, the contract:
- Validates sizes and formats (20-byte `nodeID`, 48-byte `blsPublicKey`, owners, churn limits)
- Builds a `RegisterL1ValidatorMessage` with a bounded expiry
- Computes a unique `validationID`
- Stores pending state mapping `nodeID → validationID`
- Interacts with ICOM to create a warp message that can be submitted to the Platform-Chain

### Phase 2: Platform-Chain Processing

We then will sign and submit the `RegisterL1ValidatorMessage` warped response we got from the last step to the Platform-Chain, this executes a `RegisterL1ValidatorTx`, and upon success signs and returns an `L1ValidatorRegistrationMessage` warped response.

The Platform-Chain processes the following message structure:

```go
// RegisterL1Validator adds a validator to the subnet.
type RegisterL1Validator struct {
	payload

	SubnetID              ids.ID                 `serialize:"true" json:"subnetID"`
	NodeID                types.JSONByteSlice    `serialize:"true" json:"nodeID"`
	BLSPublicKey          [bls.PublicKeyLen]byte `serialize:"true" json:"blsPublicKey"`
	Expiry                uint64                 `serialize:"true" json:"expiry"`
	RemainingBalanceOwner PChainOwner            `serialize:"true" json:"remainingBalanceOwner"`
	DisableOwner          PChainOwner            `serialize:"true" json:"disableOwner"`
	Weight                uint64                 `serialize:"true" json:"weight"`
}
```

### Phase 3: Completion (L1)

We finally will call the [`completeValidatorRegistration(messageIndex)`](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L425), where we will pass the message index of the response we received in step 2. The contract verifies it, activates the validator, sets the start time, and emits `CompletedValidatorRegistration`.

Anyone can call `completeValidatorRegistration(messageIndex)` with the signed message.

## Validator Registration Expiry

When registering validators, it's important to understand the **expiry field**:

- **Default Expiry**: Validator registrations expire after **24 hours** by default
- **Completion Required**: If a validator registration is not completed before the expiry time, the registration becomes invalid
- **Pending State**: Expired registrations remain in the pending registrations list in the Validator Manager contracts
- **Cleanup Required**: Expired registrations must be manually removed to keep your validator management system clean

### What Happens When Registrations Expire?

Expired validator registrations can occur due to various reasons:
- **Network connectivity issues** preventing Platform-Chain registration
- **Configuration errors** in validator node setup
- **Delayed validator setup** taking longer than 24 hours
- **Manual errors** in the registration process

These expired registrations remain in the pending list indefinitely, which can:
- Clutter your validator management interface
- Make it difficult to identify valid pending registrations
- Skew validator count and status reporting

### Managing Expired Registrations

At the end of this chapter, you'll learn how to identify and clean up expired validator registrations using the [Remove Expired Validator Registration tool](/academy/permissioned-l1s/05-validator-manager-operations/09-expired-validator-registration). This tool helps maintain a clean and organized validator management system.

## Appendix: Adding Validator Flow

<Mermaid
  chart="
sequenceDiagram
    participant EOA_Owner as EOA Owner
    participant ValidatorManager as ValidatorManager
    participant WarpMessenger as WarpMessenger (precompile)
    participant PChain as Platform-Chain

    %% Phase 1: Initiation
    EOA_Owner->>ValidatorManager: initiateValidatorRegistration(nodeID, blsPublicKey, remainingBalanceOwner, disableOwner, weight)

    ValidatorManager->>ValidatorManager: _initiateValidatorRegistration()

    ValidatorManager->>ValidatorManager: Validate parameters<br/>(BLS key, nodeID, owner structs, weight, churn limits)

    ValidatorManager->>ValidatorManager: Create RegisterL1ValidatorMessage<br/>+ registration expiry

    ValidatorManager->>ValidatorManager: Compute validationID

    ValidatorManager->>ValidatorManager: Update internal state<br/>(_validationPeriods, _registeredValidators,<br/>_pendingRegisterValidationMessages)

    ValidatorManager->>WarpMessenger: sendWarpMessage(message)

    %% Phase 2: Platform-Chain Processing
    WarpMessenger->>PChain: Deliver RegisterL1ValidatorMessage

    PChain-->>WarpMessenger: L1ValidatorRegistrationMessage (signed)

    %% Phase 3: Completion
    participant AnyCaller as Any Caller

    AnyCaller->>ValidatorManager: completeValidatorRegistration(message)

    ValidatorManager->>ValidatorManager: Verify Warp message signature

    ValidatorManager->>ValidatorManager: Update validator status to Active<br/>Set start time

    ValidatorManager-->>AnyCaller: emit CompletedValidatorRegistration
"
/>

<Quiz quizId="424"/>


# Add Validator Demo (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/04-add-validator-demo)

---
title: Add Validator Demo
description: Practical - initiate, register on Platform-Chain, and complete validator registration using the Toolbox.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import AddValidator from "@/components/toolbox/console/permissioned-l1s/AddValidator.tsx"

<ToolboxMdxWrapper walletMode="l1">
  <AddValidator />
</ToolboxMdxWrapper>

You can view the changes applied to the Validator Set [re-running the query in section 2](/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set).


# Changing Weight (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/05-change-weight)

---
title: Changing Weight
description: Theory walkthrough of changing a validator's weight with ValidatorManager owned by an EOA, including L1 and Platform-Chain calls.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

## Changing a Validator’s Weight

You’re changing an existing validator’s weight in a PoA setup where the `ValidatorManager` contract is owned by an EOA. The process mirrors registration: initiation on L1, processing on the Platform-Chain, and completion on L1.

### Phase 1: Initiation (L1)

The owner calls [`initiateValidatorWeightUpdate(validationID, newWeight)`](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L658) on `ValidatorManager`.

Under the hood, the contract:
- Ensures the validator is currently Active
- Enforces churn constraints so the delta does not exceed the configured maximum churn percentage
- Increments the validator's sent nonce
- Updates the pending weight in storage and constructs a weight message
- Sends a Warp message to the Platform-Chain

### Phase 2: Platform-Chain Processing

We then will sign and submit the `L1ValidatorWeightMessage` warped response we got from the last step to the Platform-Chain, this executes a `SetL1ValidatorWeightTx`, and upon success signs and returns an `L1ValidatorWeightMessage` warped response.

The Platform-Chain processes the following message structure:

```go
type L1ValidatorWeight struct {
	payload

	ValidationID ids.ID `serialize:"true" json:"validationID"`
	Nonce        uint64 `serialize:"true" json:"nonce"`
	Weight       uint64 `serialize:"true" json:"weight"`
}
```

### Phase 3: Completion (L1)

We finally will call the [`completeValidatorWeightUpdate(messageIndex)`](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L690), where we will pass the message index of the response we received in step 2. The contract verifies the Warp message and nonce correspondence, updates the received nonce, and emits `CompletedValidatorWeightUpdate`.

Anyone can call the `completeValidatorWeightUpdate(messageIndex)` with the signed message.

### Sequence Diagram

<Mermaid
  chart="
sequenceDiagram
    participant EOA_Owner as EOA Owner
    participant ValidatorManager as ValidatorManager
    participant WarpMessenger as WarpMessenger (precompile)
    participant PChain as Platform-Chain

    %% Phase 1: Initiation
    EOA_Owner->>ValidatorManager: initiateValidatorWeightUpdate(validationID, newWeight)

    ValidatorManager->>ValidatorManager: _initiateValidatorWeightUpdate()

    ValidatorManager->>ValidatorManager: Validate: isActive + churn rate

    ValidatorManager->>ValidatorManager: Increment sent nonce

    ValidatorManager->>ValidatorManager: Update weight in storage

    ValidatorManager->>WarpMessenger: sendWarpMessage(packL1ValidatorWeightMessage)

    %% Phase 2: Platform-Chain Processing
    WarpMessenger->>PChain: Deliver L1ValidatorWeightMessage

    PChain-->>WarpMessenger: Signed L1ValidatorWeightMessage (ack)

    %% Phase 3: Completion
    participant AnyCaller as Any Caller

    AnyCaller->>ValidatorManager: completeValidatorWeightUpdate(message)

    ValidatorManager->>ValidatorManager: Verify Warp message + nonce match

    ValidatorManager->>ValidatorManager: Update received nonce

    ValidatorManager-->>AnyCaller: emit CompletedValidatorWeightUpdate
"
/>



# Change Weight Demo (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/06-change-weight-demo)

---
title: Change Weight Demo
description: Practical - change a validator's weight using the Toolbox.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ChangeWeight from "@/components/toolbox/console/permissioned-l1s/ChangeWeight.tsx"

<ToolboxMdxWrapper walletMode="l1">
  <ChangeWeight />
</ToolboxMdxWrapper>

You can view the changes applied to the Validator Set [re-running the query in section 2](/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set).


# Removing Validator (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/07-remove-validator)

---
title: Removing Validator
description: Theory walkthrough of removing a validator with ValidatorManager owned by an EOA, including L1 and Platform-Chain calls.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

## Removing a Validator

You're removing an existing Active validator in a PoA setup where the `ValidatorManager` contract is owned by an EOA. The flow has two L1 calls with Platform-Chain processing in between.

### Phase 1: Initiation (L1)

The owner calls [`initiateValidatorRemoval(validationID)`](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L518) on `ValidatorManager`.

Under the hood, the contract:
- Ensures the validator is currently Active
- Sets the validator status to `PendingRemoved`
- Sets the end time of the current validation period to the current timestamp
- Persists updates and constructs a weight message with `weight = 0`
- Sends a Warp message to the Platform-Chain (removal is encoded as a weight update to zero)

### Phase 2: Platform-Chain Processing

We then will sign and submit the `L1ValidatorWeightMessage` warped response we got from the last step to the Platform-Chain, this executes a `SetL1ValidatorWeightTx`. Upon successful processing, it acknowledges the validator exit by signing and returns an `L1ValidatorRegistrationMessage` with `valid = 0` warped response.

The Platform-Chain processes the weight message (with weight set to 0 for removal):

```go
type L1ValidatorWeight struct {
	payload

	ValidationID ids.ID `serialize:"true" json:"validationID"`
	Nonce        uint64 `serialize:"true" json:"nonce"`
	Weight       uint64 `serialize:"true" json:"weight"` // Set to 0 for removal
}
```

And returns a registration message acknowledging the removal:

```go
type L1ValidatorRegistrationMessage struct {
	payload

	ValidationID ids.ID `serialize:"true" json:"validationID"`
	Valid        bool   `serialize:"true" json:"valid"` // Set to false for removal
}
```

### Phase 3: Completion (L1)

We finally will call the [`completeValidatorRemoval(messageIndex)`](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L573), where we will pass the message index of the response we received in step 2. The contract verifies the Warp message, confirms the registration status is false, updates the validator's status to Completed (if previously `PendingRemoved`), removes the node from the registered mapping, persists updates, and emits `CompletedValidatorRemoval`.

Anyone can call the `completeValidatorRemoval(messageIndex)` with the signed message.

### Sequence Diagram

<Mermaid
  chart="
sequenceDiagram
    participant EOA_Owner as EOA Owner
    participant ValidatorManager as ValidatorManager
    participant WarpMessenger as WarpMessenger (precompile)
    participant PChain as Platform-Chain

    %% Phase 1: Initiation
    EOA_Owner->>ValidatorManager: initiateValidatorRemoval(validationID)

    ValidatorManager->>ValidatorManager: _initiateValidatorRemoval()

    ValidatorManager->>ValidatorManager: Validate Active status

    ValidatorManager->>ValidatorManager: Set status = PendingRemoved<br/>Set validation end time

    ValidatorManager->>ValidatorManager: Save validator updates

    ValidatorManager->>WarpMessenger: sendWarpMessage(weightMessage(weight=0))

    %% Phase 2: Platform-Chain Processing
    WarpMessenger->>PChain: Deliver L1ValidatorWeightMessage(weight=0)

    PChain-->>WarpMessenger: Signed L1ValidatorRegistrationMessage(valid=0)

    %% Phase 3: Completion
    participant AnyCaller as Any Caller

    AnyCaller->>ValidatorManager: completeValidatorRemoval(message)

    ValidatorManager->>ValidatorManager: Verify Warp message<br/>Check valid == false

    ValidatorManager->>ValidatorManager: Set status = Completed<br/>Remove from registered validators

    ValidatorManager-->>AnyCaller: emit CompletedValidatorRemoval

    %% Optional: Resend
    EOA_Owner-->>ValidatorManager: resendValidatorRemovalMessage(validationID)
"
/>

<Quiz quizId="425"/>

# Remove Validator Demo (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/08-remove-validator-demo)

---
title: Remove Validator Demo
description: Practical - remove a validator using the Toolbox.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import RemoveValidator from "@/components/toolbox/console/permissioned-l1s/RemoveValidator.tsx"

<ToolboxMdxWrapper walletMode="l1">
  <RemoveValidator />
</ToolboxMdxWrapper>

You can view the changes applied to the Validator Set [re-running the query in section 2](/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set).


# Remove Expired Validator Registration (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/09-expired-validator-registration)

---
title: Remove Expired Validator Registration
description: Learn how to identify and remove expired validator registrations that were not completed within the 24-hour window.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import RemoveExpiredValidatorRegistration from "@/components/toolbox/console/permissioned-l1s/RemoveExpiredValidatorRegistration/RemoveExpiredValidatorRegistration.tsx"

## Understanding Expired Validator Registrations

When validators are registered through the Validator Manager contract, they are given a **24-hour window** to complete their registration on the Platform-Chain. If this window expires without completion, the registration becomes invalid but remains in the pending registrations list.

Expired validator registrations typically occur due to configuration errors or manual mistakes during the registration process that prevent proper Platform-Chain registration.

These registrations create contract clutter by remaining in the pending list indefinitely, making it difficult to identify valid pending registrations.

## Removing Expired Registrations

This tool automatically identifies registrations past their expiry time and removes them from the pending list to keep your validator management system organized.

When removing an expired registration, the tool builds the required justification for Platform-Chain removal, signs the removal message using the appropriate signing mechanism, executes the `completeValidatorRemoval` function, and updates the contract state to remove the expired registration from the pending list.

<ToolboxMdxWrapper walletMode="l1">
  <RemoveExpiredValidatorRegistration />
</ToolboxMdxWrapper>



# Platform-Chain Disable Validator (/academy/avalanche-l1/permissioned-l1s/05-validator-manager-operations/10-pchain-disable-validator)

---
title: Platform-Chain Disable Validator
description: Practical - disable a validator at the Platform-Chain level.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

We can directly disable a validator on the Platform-Chain using the `DisableL1ValidatorTx` transaction and without needing to go through the VMC flow.

### Why Direct Platform-Chain Disabling Exists

The direct disable flow is crucial for possible emergency situations like:
- The L1 goes down or becomes unreachable
- The Validator Manager Contract (VMC) is down or malfunctioning
- Something in the system is malfunctioning and immediate action is needed

These issues all become critical when the owner of the validators needs to retrieve their validator Platform-Chain LUX used to keep it running (e.g; they deposited 1000 LUX to never have to worry about topping up balances and now can't get it back)

### How It Works

**Direct Platform-Chain Transaction**: You can issue a `DisableL1ValidatorTx` directly on the Platform-Chain to disable any validator without interacting with the L1's Validator Manager contract at all.

**Weight Preservation**: When a validator is disabled this way, their weight still counts towards the L1's total weight - they're just inactive.

**Re-activation**: Disabled validators can be re-activated at any time by increasing their balance with an `IncreaseBalanceTx`. Anyone can call this transaction for any validator on the Platform-Chain.

**Key Management**: When a validator is disabled, the keys are no longer stored on disk, providing additional security.

**Permanent Removal Requires Contract**: To completely and permanently remove a validator from the set, you still need to call `initiateValidatorRemoval()` through the contract flow


### Chapter Conclusion

Throughout this chapter, we've explored the complete validator lifecycle - from adding validators through the VMC, modifying their weights, removing them properly, and handling emergency situations with direct Platform-Chain disabling.

This is all you will need to know in order to **manage the validator set of your permissioned L1**. 

## Appendix: Direct Platform-Chain Disable Flow

<Mermaid chart={`sequenceDiagram
    participant User as User/Admin
    participant PChain as Platform-Chain
    participant L1Validator as L1 Validator

    User->>PChain: IssueDisableL1ValidatorTx(validationID)
    PChain->>PChain: Process DisableL1ValidatorTx<br/>Remove keys from disk
    PChain->>L1Validator: Disable validator

    Note left of L1Validator: Validator becomes inactive<br/>Weight still counts toward total<br/>Keys no longer on disk
    Note over User,L1Validator: 2. Optional: Re-activation

    User->>PChain: IncreaseBalanceTx(validationID, amount)
    Note right of User: Anyone can call this<br/>for any validator

    PChain->>PChain: Process IncreaseBalanceTx

    PChain->>L1Validator: Re-activate validator`} />

<Quiz quizId="426"/>


# Read Validator Manager Contract (/academy/avalanche-l1/permissioned-l1s/XX-poa-manager-deployment/01-read-validator-manager)

---
title: Read Validator Manager Contract
description: Learn how to query and read data from the Validator Manager
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---


import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ReadContract from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/ReadContract.tsx"

## Overview

Reading data from the Validator Manager contract is essential for monitoring your L1's validator set and understanding the current state of the system.

## Query Contract State



<ToolboxMdxWrapper walletMode="l1">
    <ReadContract />
</ToolboxMdxWrapper>

## Key Read Functions

### Configuration Data

#### `subnetID()`
Returns your L1's unique identifier:
```solidity
function subnetID() external view returns (bytes32)
```

#### `owner()`
Returns the current contract owner:
```solidity
function owner() external view returns (address)
```

#### Churn Parameters
Get the churn configuration:
```solidity
function churnPeriodSeconds() external view returns (uint64)
function maximumChurnPercentage() external view returns (uint8)
```

### Validator Information

#### `getValidator(bytes32 validationID)`
Get detailed information about a specific validator:
```solidity
struct Validator {
    ValidatorStatus status;  // Current status
    bytes nodeID;           // Node identifier
    uint64 weight;          // Voting weight
    uint64 startedAt;       // Start timestamp
    uint64 endedAt;         // End timestamp
}
```

#### `getWeight(bytes32 validationID)`
Get a validator's current weight:
```solidity
function getWeight(bytes32 validationID) external view returns (uint64)
```

### Aggregate Data

#### `totalWeight()`
Get the total weight of all active validators:
```solidity
function totalWeight() external view returns (uint64)
```

#### `activeValidatorCount()`
Get the number of active validators:
```solidity
function activeValidatorCount() external view returns (uint256)
```

## Understanding Validator Status

Validators can have different statuses:

1. **Active**: Currently validating
2. **PendingAdded**: Registration initiated, not yet complete
3. **PendingRemoved**: Removal initiated, not yet complete
4. **Completed**: No longer active

## Churn Tracker State

Monitor churn consumption:

```solidity
function getCurrentChurnPeriod() external view returns (
    uint256 startTime,
    uint64 initialWeight,
    uint64 totalWeight,
    uint64 churnAmount
)
```

### Interpreting Churn Data

- **startTime**: When current period began
- **initialWeight**: Total weight at period start
- **totalWeight**: Current total weight
- **churnAmount**: Amount changed this period

## Common Queries

### List All Validators
While there's no built-in function to list all validators, you can:
1. Listen to events from contract creation
2. Track `ValidatorRegistered` events
3. Build an off-chain index

### Check Validator Eligibility
Before adding a validator, check:
```javascript
// Get current churn usage
const churn = await validatorManager.getCurrentChurnPeriod();
const maxChange = (churn.totalWeight * maxChurnPercentage) / 100;
const remainingChurn = maxChange - churn.churnAmount;

// Check if new validator weight fits
if (newValidatorWeight <= remainingChurn) {
    console.log("Can add validator");
} else {
    console.log("Must wait for new churn period");
}
```

### Monitor Pending Operations
Check for pending validator operations:
```javascript
// Check if validator has pending operation
const validator = await validatorManager.getValidator(validationID);
if (validator.status === "PendingAdded") {
    console.log("Registration pending completion");
}
```

## Event Monitoring

Subscribe to contract events for real-time updates:

```javascript
// Listen for new validators
validatorManager.on("ValidatorRegistered", (nodeID, weight) => {
    console.log(`New validator: ${nodeID}, weight: ${weight}`);
});

// Listen for removals
validatorManager.on("ValidatorRemoved", (nodeID) => {
    console.log(`Validator removed: ${nodeID}`);
});

// Listen for weight updates
validatorManager.on("ValidatorWeightUpdated", (nodeID, newWeight) => {
    console.log(`Weight updated: ${nodeID}, new weight: ${newWeight}`);
});
```

## Best Practices

1. **Regular Monitoring**: Check validator states periodically
2. **Event Tracking**: Use events for real-time updates
3. **Churn Planning**: Monitor churn usage before operations
4. **State Verification**: Verify state after operations

## Troubleshooting

### Reading Issues

1. **Wrong Network**: Ensure connected to correct chain
2. **Invalid Address**: Verify contract address
3. **ABI Mismatch**: Use correct contract ABI

### Data Interpretation

1. **Timestamps**: All times are Unix timestamps
2. **Weights**: Understand weight units for your system
3. **Status Codes**: Map numeric status to names

## Next Steps

After understanding how to read the contract:
1. Initialize the validator set with existing validators
2. Query and verify the initial state
3. Begin active validator management


# Query Validator Set (/academy/avalanche-l1/permissioned-l1s/XX-poa-manager-deployment/02-query-validator-set)

---
title: Query Validator Set
description: Learn how to query and monitor your L1's validator set
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import QueryL1ValidatorSet from "@/components/toolbox/console/permissioned-l1s/QueryL1ValidatorSet.tsx"

## Overview

Querying the validator set is essential for monitoring your L1's health, planning changes, and ensuring proper operation. This section covers how to effectively query and interpret validator data.

## Query Tools



<ToolboxMdxWrapper walletMode="l1">
    <QueryL1ValidatorSet />
</ToolboxMdxWrapper>

## Query Methods

### Individual Validator Queries

#### Get Validator by ID
```javascript
const validator = await validatorManager.getValidator(validationID);
console.log({
    status: validator.status,
    nodeID: validator.nodeID,
    weight: validator.weight,
    startedAt: new Date(validator.startedAt * 1000),
    endedAt: validator.endedAt > 0 ? new Date(validator.endedAt * 1000) : "Active"
});
```

#### Get Validator Weight
```javascript
const weight = await validatorManager.getWeight(validationID);
console.log(`Validator weight: ${weight}`);
```

### Aggregate Queries

#### Total Network Weight
```javascript
const totalWeight = await validatorManager.totalWeight();
console.log(`Total network weight: ${totalWeight}`);
```

#### Active Validator Count
```javascript
const count = await validatorManager.activeValidatorCount();
console.log(`Active validators: ${count}`);
```

## Building a Validator Registry

Since the contract doesn't provide a built-in list function, you can build a registry by:

### 1. Event-Based Approach

```javascript
// Get all historical events
const registeredEvents = await validatorManager.queryFilter(
    validatorManager.filters.ValidatorRegistered()
);

const removedEvents = await validatorManager.queryFilter(
    validatorManager.filters.ValidatorRemoved()
);

// Build active validator list
const validators = new Map();

registeredEvents.forEach(event => {
    validators.set(event.args.nodeID, {
        nodeID: event.args.nodeID,
        weight: event.args.weight,
        registeredAt: event.blockNumber
    });
});

removedEvents.forEach(event => {
    validators.delete(event.args.nodeID);
});
```

### 2. Off-Chain Index

Maintain a database that tracks:
- Validator additions
- Validator removals  
- Weight updates
- Current state

## Monitoring Validator Status

### Status Types

```javascript
enum ValidatorStatus {
    Active = 0,        // Currently validating
    PendingAdded = 1,  // Addition initiated
    PendingRemoved = 2, // Removal initiated
    Completed = 3      // No longer active
}
```

### Check Pending Operations

```javascript
async function checkPendingOperations(validationID) {
    const validator = await validatorManager.getValidator(validationID);
    
    switch(validator.status) {
        case 1: // PendingAdded
            console.log("Waiting for registration completion");
            break;
        case 2: // PendingRemoved
            console.log("Waiting for removal completion");
            break;
        case 0: // Active
            console.log("Validator is active");
            break;
        case 3: // Completed
            console.log("Validator has been removed");
            break;
    }
}
```

## Churn Analysis

### Current Churn Status
```javascript
const churn = await validatorManager.getCurrentChurnPeriod();

const churnPercentageUsed = (churn.churnAmount * 100) / 
    (churn.totalWeight * maximumChurnPercentage / 100);

console.log(`Churn used: ${churnPercentageUsed.toFixed(2)}%`);
console.log(`Churn resets at: ${new Date(churn.startTime + churnPeriodSeconds * 1000)}`);
```

### Available Churn Capacity
```javascript
function calculateAvailableChurn(churnData, maxPercentage) {
    const maxChurn = (churnData.totalWeight * maxPercentage) / 100;
    const usedChurn = churnData.churnAmount;
    const availableChurn = maxChurn - usedChurn;
    
    return {
        max: maxChurn,
        used: usedChurn,
        available: availableChurn,
        canAddWeight: availableChurn
    };
}
```

## Creating a Validator Dashboard

Build a comprehensive view:

```javascript
async function getValidatorSetInfo() {
    const [totalWeight, activeCount, churn] = await Promise.all([
        validatorManager.totalWeight(),
        validatorManager.activeValidatorCount(),
        validatorManager.getCurrentChurnPeriod()
    ]);
    
    return {
        summary: {
            totalWeight,
            activeValidators: activeCount,
            averageWeight: totalWeight / activeCount
        },
        churn: {
            periodStart: new Date(churn.startTime * 1000),
            used: churn.churnAmount,
            remaining: calculateAvailableChurn(churn, maxChurnPercentage).available
        }
    };
}
```

## Query Patterns

### Regular Health Checks
```javascript
setInterval(async () => {
    const health = await getValidatorSetInfo();
    console.log("Network health:", health);
    
    // Alert if validators drop below threshold
    if (health.summary.activeValidators < MIN_VALIDATORS) {
        console.warn("Low validator count!");
    }
}, 60000); // Check every minute
```

### Pre-Operation Checks
```javascript
async function canAddValidator(weight) {
    const churn = await validatorManager.getCurrentChurnPeriod();
    const available = calculateAvailableChurn(churn, maxChurnPercentage);
    
    return weight <= available.available;
}
```

## Best Practices

1. **Cache Results**: Don't query repeatedly for static data
2. **Batch Queries**: Use multicall for multiple reads
3. **Event Monitoring**: Subscribe to events for real-time updates
4. **Error Handling**: Handle query failures gracefully

## Common Issues

### Query Failures
- **Network Issues**: Check RPC connection
- **Contract Address**: Verify correct address
- **ABI Mismatch**: Ensure using correct ABI

### Data Interpretation
- **Weight Units**: Understand your weight denomination
- **Timestamps**: Convert Unix timestamps properly
- **Status Codes**: Map numeric status correctly

## Next Steps

With query capabilities established:
1. Set up regular monitoring
2. Build dashboards for visibility
3. Plan validator management operations
4. Implement alerting for critical changes


# Deploy PoA Manager (/academy/avalanche-l1/permissioned-l1s/XX-poa-manager-deployment/03-deploy-poa-manager)

---
title: Deploy PoA Manager
description: Deploy the Proof of Authority Manager contract for simplified validator management
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployPoAManager from "@/components/toolbox/console/permissioned-l1s/multisig-setup/DeployPoAManager.tsx"

### PoAValidatorManager

Proof-of-Authority Validator management is provided via `PoAValidatorManager`, which restricts modification of the Validator set to an owner address. After deploying `PoAValidatorManager.sol` and a proxy, the `initialize` function takes the owner address, in addition to standard `ValidatorManagerSettings`.


## Overview

The Proof of Authority (PoA) Manager is a simplified validator management contract that provides an easier interface for managing validators on your L1. It acts as a wrapper around the core Validator Manager contract, offering streamlined operations for PoA-based L1s.

## PoA Manager Benefits

The PoA Manager provides several advantages:

1. **Simplified Interface**: Easier validator management compared to the core Validator Manager
2. **Owner-Based Control**: Single owner can manage all validator operations
3. **Streamlined Operations**: Reduced complexity for adding/removing validators
4. **Integration Ready**: Works seamlessly with your existing Validator Manager setup

## Prerequisites

Before deploying the PoA Manager, ensure you have:

1. **Completed L1 Conversion**: Your Subnet must be converted to L1
2. **Deployed Validator Manager**: Core Validator Manager contract must be deployed and initialized
3. **Proper Permissions**: Owner access to the Validator Manager contract
4. **Network Selection**: Connected to the correct blockchain (where your Validator Manager is deployed)

## Deploy PoA Manager

<ToolboxMdxWrapper walletMode="l1">
    <DeployPoAManager />
</ToolboxMdxWrapper>

## Deployment Parameters

When deploying the PoA Manager, you'll need to configure:

1. **Validator Manager Address**: The address of your deployed Validator Manager contract
2. **Owner Address**: The address that will have control over the PoA Manager
3. **Subnet ID**: Your L1's Subnet ID for validator operations
4. **Network Configuration**: Ensure you're deploying on the correct chain

## Post-Deployment Configuration

After successful deployment:

1. **Verify Deployment**: Confirm the PoA Manager address and configuration
2. **Test Connection**: Ensure the PoA Manager can communicate with your Validator Manager
3. **Set Permissions**: Configure any additional access controls if needed
4. **Document Address**: Save the PoA Manager address for future operations

## PoA Manager Functions

The PoA Manager provides simplified functions for:

### Validator Operations
- **Add Validator**: Simplified validator registration process
- **Remove Validator**: Streamlined validator removal
- **Update Validator**: Modify validator parameters

### Administrative Functions
- **Owner Management**: Transfer ownership if needed
- **Configuration Updates**: Modify PoA Manager settings
- **Emergency Controls**: Safety mechanisms for critical situations

## Security Considerations

When using the PoA Manager:

1. **Owner Security**: Protect the owner private key carefully
2. **Access Control**: Limit who has access to owner functions
3. **Regular Monitoring**: Monitor validator operations and contract state
4. **Backup Plans**: Have procedures for emergency situations

## Common Use Cases

The PoA Manager is ideal for:

- **Private L1s**: Organizations running permissioned blockchains
- **Development Networks**: Testing and development environments  
- **Consortium Chains**: Multi-party controlled networks
- **Simplified Operations**: Teams wanting reduced operational complexity

## Troubleshooting

### Deployment Issues
- **Permission Errors**: Verify you have owner access to the Validator Manager
- **Network Mismatch**: Ensure you're on the correct blockchain
- **Gas Issues**: Check you have sufficient gas for deployment

### Operation Issues
- **Function Failures**: Verify the PoA Manager has proper permissions
- **State Inconsistencies**: Check synchronization with the Validator Manager
- **Access Denied**: Confirm you're using the correct owner address

## Next Steps

With the PoA Manager deployed, you can:

1. **Start Managing Validators**: Use the simplified interface to add/remove validators
2. **Monitor Operations**: Track validator changes and system health
3. **Scale Your Network**: Add more validators as your L1 grows
4. **Integrate Systems**: Connect the PoA Manager to your operational tools

The PoA Manager provides a powerful yet simple way to manage your L1's validator set while maintaining the security and reliability of the underlying Validator Manager system.


# VMC Deployed Structure (/academy/avalanche-l1/permissioned-l1s/XX-poa-manager-deployment/04-vmc-deployed-structure)

---
title: VMC Deployed Structure
description: Summary of deployed smart contract structure up until this point
updated: 2025-01-01
authors: [nicolasarnedo]
icon: FileCode
---

## Overview

Understanding the ValidatorManager contract structure is essential for proper initialization and operation. This section covers the contract's architecture, state variables, and initialization process.

## Contract Inheritance

The ValidatorManager follows a structured inheritance pattern:

```solidity
contract ValidatorManager is 
    IValidatorManager, 
    Initializable, 
    OwnableUpgradeable, 
    LP99Manager 
{
    // Implementation
}
```

### Inherited Contracts

1. **IValidatorManager**: Defines the interface
2. **Initializable**: Enables proxy-safe initialization
3. **OwnableUpgradeable**: Provides access control
4. **LP99Manager**: Implements [LP-99](/docs/lps/99-validatorsetmanager-contract) standard

## State Variables

### Core Configuration

```solidity
struct ValidatorManagerSettings {
    address admin;           // Initial owner address
    bytes32 subnetID;       // Your L1's subnet ID
    uint64 churnPeriodSeconds;      // Time window for changes
    uint8 maximumChurnPercentage;   // Max change per period
}
```

### Validator Tracking

```solidity
struct Validator {
    ValidatorStatus status;  // Active, Pending, Removed
    bytes nodeID;           // Validator's node ID
    uint64 weight;          // Voting weight
    uint64 startedAt;       // Registration timestamp
    uint64 endedAt;         // Removal timestamp
}
```

## Initialization Function

The `initialize` function sets up the ValidatorManager:

```solidity
function initialize(
    ValidatorManagerSettings calldata settings
) external initializer {
    // Set up ownership
    __Ownable_init(settings.admin);
    
    // Store configuration
    _subnetID = settings.subnetID;
    _churnPeriodSeconds = settings.churnPeriodSeconds;
    _maximumChurnPercentage = settings.maximumChurnPercentage;
}
```

### Initialization Parameters

1. **admin**: Address that will own the contract
2. **subnetID**: Your L1's unique identifier
3. **churnPeriodSeconds**: Anti-spam protection period
4. **maximumChurnPercentage**: Limits rapid validator changes

<Callout type="info">
The churn mechanism prevents rapid validator set changes that could destabilize the network. It limits how much stake can be added or removed within a time window.
</Callout>

## Churn Protection

### How Churn Works

The churn mechanism tracks validator changes over time:

```solidity
struct ValidatorChurnPeriod {
    uint256 startTime;      // Period start
    uint64 initialWeight;   // Weight at start
    uint64 totalWeight;     // Current total weight
    uint64 churnAmount;     // Amount changed
}
```

### Churn Calculation

- Tracks changes within `churnPeriodSeconds`
- Limits changes to `maximumChurnPercentage` of total weight
- Resets after period expires
- Prevents network instability

## Key Functions Overview

### Owner Functions

Only the contract owner can call:
- `initiateValidatorRegistration()`: Add new validator
- `initiateValidatorRemoval()`: Remove validator
- `initiateValidatorWeightUpdate()`: Change voting weight

### Public Functions

Anyone can call these to complete pending operations:
- `completeValidatorRegistration()`: Finalize addition
- `completeValidatorRemoval()`: Finalize removal
- `completeValidatorWeightUpdate()`: Finalize weight change

### Query Functions

Read-only functions for information:
- `getValidator()`: Get validator details
- `getWeight()`: Get total or individual weight
- `subnetID()`: Get the L1's ID
- `owner()`: Get contract owner

## Storage Layout

Understanding storage is crucial for upgrades:

1. **Proxy Storage**: State variables live here
2. **Implementation Logic**: Functions live here
3. **Storage Slots**: Must maintain order in upgrades

## Events

The contract emits events for tracking:

```solidity
event ValidatorRegistered(bytes nodeID, uint64 weight);
event ValidatorRemoved(bytes nodeID);
event ValidatorWeightUpdated(bytes nodeID, uint64 newWeight);
```

## Security Considerations

1. **Owner Privileges**: Owner has full control
2. **Churn Limits**: Prevents rapid changes
3. **Two-Phase Operations**: Prevents front-running
4. **Message Validation**: Verifies Platform-Chain messages

## Next Steps

With understanding of the contract structure:
1. Set initial configuration parameters
2. Initialize the ValidatorManager
3. Begin managing your validator set

# Introduction (/academy/avalanche-l1/permissioned-l1s/04-validator-manager-deployment/01-vmc-deployment-intro)

---
title: Introduction
description: Learn the deployment flow and understand the logic behind it
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## Current Infrastructure State

By now, we have:
- **Created a Subnet-EVM L1** with its genesis file
- **Pre-deployed proxy infrastructure** at addresses `0xfacade...` (proxy) and `0xdad...` (admin)
- **Placeholder implementation** at `0x1212...` waiting to be upgraded

If we were to look at our L1, it would like something like this:

![Validator Manager Deployment Layout](/common-images/permissioned-l1s/VMCDeploy1.png)

## Deployment Flow

The deployment process follows a specific sequence designed for safety and clarity:

1. **Deploy the Validator Manager implementation** - Create the actual contract with validation logic
2. **Upgrade the proxy** - Point `0xfacade...` to our new implementation via the admin at `0xdad...`
3. **Initialize the configuration** - Set up the initial validator set and permissions
4. **Activate validation** - Enable the contract to start managing validators on the Platform-Chain

# Deploy Validator Manager (/academy/avalanche-l1/permissioned-l1s/04-validator-manager-deployment/02-deploy-validator-manager)

---
title: Deploy Validator Manager
description: Deploy and configure the Validator Manager implementation contract
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployValidatorManager from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/DeployValidatorManager.tsx"

First you will need to deploy the actual Validator Manager implementation that contains the logic for managing validators. 

Building on the image shown in the introduction, now our L1 will have these contracts deployed:

![Validator Manager Deployment](/common-images/permissioned-l1s/VMCDeploy2.png)

## Implementation Contract

The Validator Manager implementation:
- Contains all validator management logic
- Implements the LP99Manager standard
- Handles Platform-Chain communication
- Can be upgraded without losing state

## Validator Messages Library

The ValidatorManager contract requires a separate library contract called **ValidatorMessages** to be deployed first. This library handles all the message encoding and decoding for communication with the Platform-Chain.

**Why a separate library?**
- Solidity requires libraries to be deployed independently before they can be linked
- The ValidatorManager bytecode contains placeholders that get replaced with the library's deployed address
- This allows multiple validator managers to share the same message handling code

**What it does:**
- Packs validator registration messages for the Platform-Chain
- Unpacks responses from the Platform-Chain 
- Handles weight updates and conversion messages
- Ensures consistent message formatting across all validator operations

<Callout type="info">
The library deployment is a one-time operation - once deployed, multiple validator manager contracts can reference the same library instance.
</Callout>

## Deploy the Implementation

<ToolboxMdxWrapper walletMode="l1">
    <DeployValidatorManager />
</ToolboxMdxWrapper>

<Quiz quizId="420"/>


# Upgrade Proxy (/academy/avalanche-l1/permissioned-l1s/04-validator-manager-deployment/03-upgrade-proxy)

---
title: Upgrade Proxy
description: Learn how to point your proxy contract to the Validator Manager implementation
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import UpgradeProxy from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/UpgradeProxy.tsx"

After deploying both the validator manager contract, we will need to link them by upgrading the proxy to point to your Validator Manager implementation.

Since the **ProxyAdmin** contract was deployed through the genesis with the deployer address set to the owner of the contract, we will call the *upgradeToAndCall()* function.

![Validator Manager Deployment Upgrade Proxy Part 1](/common-images/permissioned-l1s/VMCDeploy3.png)

This will cause the **TransparentUpgradeableProxy** contract to (via *delegatecall*) call our newly deployed **Validator Manager** contract, instead of the empty contract it previously had set by default.

![Validator Manager Deployment Upgrade Proxy Part 2](/common-images/permissioned-l1s/VMCDeploy4.png)

## Perform the Upgrade

- **Proxy Address**: set to 0xfacade...
- **ProxyAdmin Address**: set to 0xdad....
- **Desired Implementation**: set to address of deployed Validator Manager contract on your L1
- **Current Implementation**: set to 0x121212...212

<Callout type="info">
Make sure you have your L1 selected in the wallet component below
</Callout>

<UpgradeProxy />

<Quiz quizId="421"/>


# Set Initial Configuration (/academy/avalanche-l1/permissioned-l1s/04-validator-manager-deployment/04-set-initial-configuration)

---
title: Set Initial Configuration
description: Configure your Validator Manager with initial parameters
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import Initialize from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/Initialize.tsx"

Setting the initial configuration is a critical step that establishes how your Validator Manager will operate. 

This process involves calling the `initialize` function through the **TransparentUpgradeableProxy**, which forwards the call to your ValidatorManager implementation.

![Validator Manager Deployment Initialize](/common-images/permissioned-l1s/VMCDeploy5.png)

## How Initialization Works

### The Initialize Function

The configuration is set by calling `initialize()` with a `ValidatorManagerSettings` struct. This call:
- Goes through the proxy at `0xfacade...` (not directly to the implementation)
- Can only be called once due to OpenZeppelin's `initializer` modifier
- Sets up the ownership structure and operational parameters

## Configuration Parameters

The `ValidatorManagerSettings` struct contains four essential parameters:

1. **Admin Address**: The account that controls validator management operations (your connected wallet). Can be changed through ownership transfer.
2. **Subnet ID**: Links the Validator Manager to your specific L1 & can't be changed after initialization.
3. **Churn Period Seconds**:Time window for tracking validator set changes (must be ≤ 86400 seconds)
4. **Maximum Churn Percentage**: Limits how much validator weight can change per period (1-20% protocol maximum). 
*Example*: 20% means max 1/5 of total weight can change

## Set Configuration

<ToolboxMdxWrapper walletMode="l1">
    <Initialize />
</ToolboxMdxWrapper>

<Quiz quizId="422"/>


# Initialize Validator Set (/academy/avalanche-l1/permissioned-l1s/04-validator-manager-deployment/05-initialize-validator-set)

---
title: Initialize Validator Set
description: Set up the initial validator set when converting a subnet to an L1
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import InitValidatorSet from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/InitValidatorSet.tsx"

When converting an existing subnet to an L1 with sovereign validator management, you need to initialize the Validator Manager with the current validator set. This one-time operation bridges Platform-Chain subnet creation with L1 validator management using cryptographically verified conversion data.

![Validator Manager Deployment Initialize Validator Set](/common-images/permissioned-l1s/VMCDeploy6.png)

## How initializeValidatorSet Works

### Function Implementation

You can view the full source code of the `initializeValidatorSet` function here: [ValidatorManager.sol#L211](https://github.com/luxfi/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L211)

Here you will find pseudo-code that covers the main logic in the function:
```
initializeValidatorSet(conversionData, messageIndex):
    // 1. Validation Checks
    CHECK validator set not already initialized
    VERIFY blockchain ID matches current chain
    VERIFY validator manager address is correct
    
    // 2. Platform-Chain Message Verification
    GET conversion ID from Platform-Chain Warp message at messageIndex
    COMPUTE hash of provided conversion data
    VERIFY hashes match (ensures data integrity)
    
    // 3. Process Initial Validators
    totalWeight = 0
    FOR each validator in conversionData.initialValidators:
        validationID = sha256(subnetID + validator_index)
        
        VALIDATE node ID format and check for duplicates
        REGISTER validator with "Active" status
        STORE validation period data (weight, start time, etc.)
        ADD to total weight
        EMIT registration event
    
    // 4. Final Validation
    ENSURE total weight meets minimum churn requirements
    
    // 5. Complete Initialization
    MARK validator set as initialized (permanent flag)
```

### Platform-Chain Integration & Aggregated Signatures

The initialization leverages Lux Warp Messaging for security:

1. **Platform-Chain Validators Sign** - The subnet's validators collectively sign the conversion data
2. **Aggregated Signature** - Creates a threshold signature proving consensus
3. **Warp Precompile Verifies** - The signature is verified before the contract receives it
4. **Contract Validates** - Additional checks ensure data integrity

The conversion ID is derived through:
```solidity
bytes32 conversionID = keccak256(abi.encode(conversionData));
```

This ID must match the one in the Platform-Chain signed message, ensuring data hasn't been tampered with.

## Understanding Conversion Data

The conversion data structure used by the function:

```solidity
struct ConversionData {
    bytes32 subnetID;                      // Your L1's subnet identifier
    bytes32 validatorManagerBlockchainID;  // Blockchain ID where VM is deployed  
    address validatorManagerAddress;       // This validator manager contract (0xfacade...)
    InitialValidator[] initialValidators;  // Array of current validators
}

struct InitialValidator {
    bytes nodeID;        // Validator's Platform-Chain node ID (e.g., "NodeID-...")
    bytes blsPublicKey;  // BLS public key for signature verification
    uint64 weight;       // Validator's voting weight
}
```

### Required Information

To initialize, you'll need:
- **Conversion Data**: Current validator information from Platform-Chain
- **Message Index**: Position in the Warp message queue
- **Proper Timing**: Must be done before other operations

<Callout type="warning">
Initialization can only be done once! Make sure you have the correct validator data before proceeding.
</Callout>

## Initialize Validator Set

<ToolboxMdxWrapper walletMode="l1">
    <InitValidatorSet />
</ToolboxMdxWrapper>

<Quiz quizId="423"/>

## Next Steps

Congratulations! You just set up your first **Permissioned L1**! In the next chapter you will learn how to manage this validator set:
1. Query the validator set to verify state
2. Add, Chnage Weight & Remove Validators


# Read Deployed VMC (/academy/avalanche-l1/permissioned-l1s/04-validator-manager-deployment/06-check-contract)

---
title: Read Deployed VMC
description: Check the Validator Manager Contract.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ReadContract from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/ReadContract.tsx"

Here you can double check that the `ValidatorManager` contract has been deployed and initialized correctly.

Specifically, you can check the `totalWeight`, `admin`, `subnetID`, `churnPeriodSeconds`, and `maximumChurnPercentage` variables.

<ToolboxMdxWrapper  walletMode="l1">
    <ReadContract />
</ToolboxMdxWrapper>


# Registering Validators (/academy/avalanche-l1/permissioned-l1s/XX-registering-validator/registering-validator)

---
title: Registering Validators
description: Learn how validators are registered on the Lux network post-etna.
updated: 2024-10-14
authors: [owenwahlgren]
icon: Terminal
---

> How does it all work? I mean *actually* work.

### Sending Warp Messages

On the EVM, a warp message is simply an event log with `messageID = sha256(messagePayload)` Nothing is ever actually “sent” anywhere, which trips people up when first learning how Warp Messaging works.

The log event emitted is from the Warp precompile address (`0x0200000000000000000000000000000000000005`) The topic of the message will be `0x56600c567728a800c0aa927500f831cb451df66a7af570eb4df4dfbf4674887d` which is the output of 
```bash
cast keccak "SendWarpMessage(address,bytes32,bytes)"
```

To find a specific warp messageID, one must know the block number or block hash to retrieve the logs, or be monitoring all events, looking for and indexing messages. 

When a block is [accepted](https://github.com/luxfi/luxgo/blob/master/graft/coreth/precompile/contracts/warp/config.go#L133) by the network, a precompile hook is called, and the EVM saves the warp message to a local database. The validator node will then be willing to sign any messages in that database upon request, typically via an `AppRequest` message over the p2p network.

### Receiving Warp Messages

On the EVM, any smart contract can call the precompile

which returns the warp message and verifies the attached signature. But what is `index`? Where does it get the warp message from?  The answer is, you!  When you send a tx to any contract that eventually calls `getVerifiedWarpMessage`, you **must** pass in the signed warp message as a “predicate”.  It’s called an AccessList, and typically this is an optional field that can be used by the EVM to pre-fetch storage slots that will be accessed, for efficiency and reducing gas costs. But Warp cleverly (ab)uses this feature of the EVM to verify the signature of the warp message, and then make the warp message available during the transactions lifetime, by calling `getVerifiedWarpMessage`. You can pass multiple warp messages which is where the `index` comes in.  (All of this is abstracted away by Teleporter for EVM to EVM comms)

Details: [Warp README](https://github.com/luxfi/luxgo/blob/master/graft/coreth/precompile/contracts/warp/README.md)

### Teleporter

[Teleporter](https://github.com/luxfi/teleporter) is a set of smart contracts that implements a rich messaging protocol on top of the Warp Messaging primitive, allowing for verified message passing between EVM chains. 

<Callout>
**Only (currently) supports EVM→EVM comms. Not used for EVM→Platform-Chain**
</Callout>

### Relayer

[Relayer](https://github.com/luxfi/awm-relayer/blob/main/relayer/README.md) is an off-chain program that listens for warp messages on a source chain, and delivers them to a destination chain.  Messages can choose to be relayed by anyone, or by only privileged relayers. Messages can also pay fees to incentivize relayers and cover gas costs.

## Registering ValidatorManager

[LP-77](/docs/lps/77-reinventing-subnets) introduces L1-only Validators, that stake no LUX, and do not validate the X/C chains. They must connect to the Primary Network and track the Platform-Chain, and also validate their own chain, and pay a small continuous fee in LUX to the network.

User submits EVM tx to smart contract [NativeTokenStakingManager.sol](https://github.com/luxfi/teleporter/blob/acp-77-updates/contracts/validator-manager/NativeTokenStakingManager.sol)

```solidity
function initializeValidatorRegistration(
        ValidatorRegistrationInput calldata registrationInput,
        uint16 delegationFeeBips,
        uint64 minStakeDuration) payable returns (bytes32 validationID)
```
Notably, this function will:

- Lock the native tokens in the contract
- `validationID`: bytes32 hash of an encoded `RegisterSubnetValidatorMessage`
- `messageID`: bytes32 hash of the warp message
- Store some data in the contract:


```solidity
$._pendingRegisterValidationMessages[validationID] = registerSubnetValidatorMessage;
$._registeredValidators[input.nodeID] = validationID;
bytes32 messageID = WARP_MESSENGER.sendWarpMessage(registerSubnetValidatorMessage);
$._validationPeriods[validationID] = Validator({
  status: ValidatorStatus.PendingAdded,
  nodeID: input.nodeID,
  startingWeight: weight,
  messageNonce: 0,
  weight: weight,
  startedAt: 0, // The validation period only starts once the registration is acknowledged.
  endedAt: 0
});
```

- Emit `ValidationPeriodCreated(validationID, nodeID, messageID, weight, registrationExpiry)`
- The `sendWarpMessage` precompile will emit a log with `sender`, `messageID`, `message`

At this point, we have submitted a transaction on the blockchain (LUExchange-Chain or L1, wherever the staking contract is deployed). All that has happened is we have stored some state in our contract and emitted some events. No changes to validators has occurred.

<Callout>
Nothing else will happen UNLESS an off-chain actor continues the process.
</Callout>


In our case, someone must be running a relayer that is configured with our staking contract as the source and the Platform-Chain as the destination.

<Callout>
At the moment, the relayer does not support the Platform-Chain, so messages must be signed and sent manually. The relayer will be updated soon to support the Platform-Chain.
</Callout>


So, to sign and send the message ourselves, we can use the Signature Aggregator server in the relayer project. This will use the p2p layer of the Lux network to connect to validators and send `AppRequest` messages to request each validator to sign a message.
```bash
curl --location 'http://localhost:8080/aggregate-signatures' \
--json '{"message": "<hex encoded unsigned message bytes retrieved from the logs>"}'
```
This will give us an aggregated BLS signature from at least 67% of the stake weighted validator set. Now we need to `POST` this to the Platform-Chain via the `RegisterSubnetValidatorTx` tx.

The Platform-Chain, if it accepts the tx, will “send” a Warp Message `SubnetValidatorRegistration` which acknowledges the change. Note that nothing is actually “sent”, instead the validator node will be willing to sign the unsigned message upon request.

So the next step is to use the Signature Aggregator service again, and provide the unsigned `SubnetValidatorRegistration` warp message, which the service will then ask validators to sign.

<Callout>
If your Validator Manager contract is on your L1 (instead of LUExchange-Chain), as an optimization, you only need to ask 67% of the stake weighted validators of your L1, not the entire Platform-Chain validator set.
</Callout>


Once an aggregate BLS signature is created, we need to submit the signed message to the LUExchange-Chain (or L1) by calling a function on the `ValidatorManager` contract.

```solidity
function completeValidatorRegistration(uint32 messageIndex)
```

Remember, this involves calling the function via `eth_sendTransaction` and encoding the signed warp message into the `AccessList`. (If you encode an array of 1 warp message, then `messageIndex` would be 0)

The function will adjust the state in the contract, including these bits:
```solidity
delete $._pendingRegisterValidationMessages[validationID];
$._validationPeriods[validationID].status = ValidatorStatus.Active;
$._validationPeriods[validationID].startedAt = uint64(block.timestamp);
```
And that’s it!

<Callout>
This doc is a WIP and we will eventually cover all the flows and add some diagrams.
</Callout>


# VMC Deployment Options (/academy/avalanche-l1/permissioned-l1s/XX-vmc-other-evms/03-deployment-options)

---
title: VMC Deployment Options
description: Understanding where to deploy the PoA Validator Manager contract
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

While Validator Manager Contract's (VMC) location choice becomes more critical when transitioning to Proof of Stake (PoS) systems due to token staking considetations, it's important to understand these options now because **you'll need to specify the VMC location in the next section when converting your Subnet to an L1**.

## Why can it be located anywhere?

The PoA Validator Manager contract can be deployed on any EVM-compatible chain within the Lux ecosystem. Since the contract communicates with the Platform-Chain through Interchain Messaging (ICM), **the deployment location doesn't affect its core functionality** - validator management operations work the same regardless of where the contract resides.

The Validator Manager Contract and P-chain generally follow a **Request-Process-Confirm** flow. The VMC chain initiates cross-chain communication to interact with the Platform-Chain for all validator operations (e.g: *adding a validator*):

- **Request**: Sends `RegisterL1ValidatorMessage` to Platform-Chain
- **Process**: Platform-Chain verifies signatures and processes the operation  
- **Confirm**: Receives `L1ValidatorRegistrationMessage` confirmations

## Deployment Options

<Tabs items={['Your L1', 'LUExchange-Chain', 'Another L1']} collapsible="true">

<Tab value="Your L1">
Best for L1's that plan to remain always permissioned with PoA

**Advantages**
- Direct integration with your L1's operational setup
- Lower operational costs
- Can configure native token minting privileges for future PoS migration

**Considerations**
- Requires bootstrapping initial validators before contract deployment
</Tab>

<Tab value="LUExchange-Chain">
Best for L1s planning future decentralization (PoS) or DeFi integration

**Advantages**
- Highest security and decentralization (Lux's primary network)
- Can manage multiple L1s from one location
- **DeFi Composability**: Easy integration with existing DeFi ecosystem
- **Decentralization Path**: Ideal for transition to Proof of Stake

**Considerations**
- Higher gas costs compared to L1s
- Potential congestion during high network usage
</Tab>

<Tab value="Another L1">
Best for multi-chain architecture systems owned  by the same company

**Advantages**
- Centralized management across multiple L1s
- Can leverage a "hub" L1 for coordinated operations

**Considerations**
- Technically, the implementation of this architecture is the same as deploying on the C-chain
</Tab>

</Tabs>

## Proof of Authority Recommendation

If you plan to keep your L1 permissioned with PoA, **deploying VMC on it is recommended** for better operational alignment.



# Standards (/academy/blockchain/encrypted-erc/01-what-is-a-digital-asset/01-digital-assets-overview)

---
title: Standards
description: Learn about ERC-20, ERC-721, and ERC-1155 in the Lux ecosystem, starting from the concept of digital assets.
updated: 2025-09-02
authors: [alejandro99so]
icon: Coins
---

A **digital asset** is any representation of value, rights, or property stored and transacted on a blockchain. These can range from cryptocurrencies and stablecoins to in-game items, tokenized real estate, and certificates.  

On Lux, most digital assets are created and managed on the **LUExchange-Chain**, which is fully compatible with the **EVM (Ethereum Virtual Machine)**. This compatibility allows Lux to use the same token standards as the broader EVM ecosystem while adding **high throughput, sub-second finality, and low fees**.  

Because of this, developers building on Lux, whether deploying to **LUExchange-Chain** for **mainnet** or **Testnet** (testnet), use **standards** to ensure their tokens are interoperable with wallets, marketplaces, and decentralized applications. These standards define the rules for how tokens behave, how they are transferred, and how they are recognized across different platforms.

The three most widely used token standards in the EVM ecosystem, and therefore in Lux, are:

---

## ERC-20: Fungible Token Standard
The ERC-20 standard defines fungible tokens where each unit is identical.

**Key Characteristics**
- Fungible: Each token has the same value as any other token of the same contract.
- Divisible: Commonly 18 decimal places for microtransactions.
- Highly interoperable with all EVM-compatible tools and dApps.
- Extremely low-cost transfers on Lux due to low gas fees.

**Common Functions**
- `transfer(address to, uint amount)`
- `approve(address spender, uint amount)`
- `transferFrom(address from, address to, uint amount)`
- `balanceOf(address account)`

---

## ERC-721: Non-Fungible Token Standard
The ERC-721 standard defines unique, non-fungible tokens (NFTs).

**Key Characteristics**
- Each token has a unique `tokenId`.
- Supports metadata for traits, images, descriptions.
- Provides immutable proof of ownership.

**Common Functions**
- `ownerOf(uint256 tokenId)`
- `safeTransferFrom(address from, address to, uint256 tokenId)`
- `tokenURI(uint256 tokenId)`

---

## ERC-1155: Multi-Token Standard
The ERC-1155 standard supports multiple token types (fungible, non-fungible, and semi-fungible) in one contract.

**Key Characteristics**
- Can store and manage different asset types in a single contract.
- Supports batch operations to save gas.
- Flexible for gaming and metaverse applications.

**Common Functions**
- `safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)`
- `safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] amounts, bytes data)`
- `balanceOf(address account, uint256 id)`

---

## Standards Comparison Table (Lux Context)

| Feature | ERC-20 | ERC-721 | ERC-1155 |
|---------|--------|---------|----------|
| Token Type | Fungible | Non-fungible | Fungible + Non-fungible |
| Uniqueness | No | Yes | Optional per token ID |
| Metadata | No | Yes (`tokenURI`) | Yes |
| Batch Transfers | No | No | Yes |
| Typical Use Cases on Lux | Stablecoins, governance, utilities | NFTs, in-game items, certificates | Gaming, collectibles, asset baskets |
| Gas Efficiency on Lux | High | Moderate | High (batch) |
| Privacy | None | None | None |
| Interoperability | Very high | High | Medium–High |

---

These standards are the foundation for asset creation and interaction in Lux’s LUExchange-Chain Mainnet and Testnet (Testnet). They allow developers to build interoperable applications and ensure that tokens can be used across different wallets, marketplaces, and decentralized protocols.  

In the **next section**, we will explore the **current uses of these standards in blockchain**, with real examples from Lux’s ecosystem, including DeFi platforms, NFT marketplaces, gaming L1, and tokenized real-world assets.


# Current Uses in Blockchain (/academy/blockchain/encrypted-erc/01-what-is-a-digital-asset/02-current-uses)

---
title: Current Uses in Blockchain
description: Explore how ERC-20, ERC-721, and ERC-1155 standards are applied in the Lux ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Activity
---

In the previous section, we covered the main **token standards** used on Lux: ERC-20, ERC-721, and ERC-1155. Now, let’s explore **how these standards are applied today** in the Lux ecosystem across the LUExchange-Chain **Mainnet**, **Testnet (Testnet)**, and **custom L1s**.

---

## ERC-20: Fungible Token Use Cases

**On Lux LUExchange-Chain Mainnet**
- **Stablecoins**:  
  USDT: Widely used for DeFi protocols, payments, and trading pairs.  
  USDC: Popular for lending, liquidity provision, and cross-chain settlements.  
- **Native Lux Tokens**:  
  WLUX: Wrapped LUX used for liquidity pools, lending markets, and DEX operations.  
- **Governance Tokens**:  
  JOE: Token powering governance and incentives in Trader Joe.  
  QI: Governance token for Benqi lending and liquid staking platform.

**On L1 Deployments**
- **Custom Ecosystem Tokens**: L1 projects can issue ERC-20 tokens for payments, in-game economies, or DeFi services, with full control over tokenomics.

**On Lux LUExchange-Chain Testnet (Testnet)**
- Developers test token logic, minting, and burning before deploying to LUExchange-Chain or an L1, avoiding the cost of mainnet errors.

---

## ERC-721: Non-Fungible Token Use Cases

**On Lux LUExchange-Chain Mainnet**
- **NFT Marketplaces**:  
  Kalao: Marketplace for art, gaming, and utility NFTs.  
  NFTrade: Cross-chain NFT marketplace supporting Lux.  
- **In-Game Unique Assets**:  
  Gaming NFTs: Rare weapons, characters, and skins in Lux LUExchange-Chain-native games.

**On L1 Deployments**
- **Project-Specific Collections**: L1s can issue NFTs for branding, game achievements, or membership systems, keeping transactions isolated from LUExchange-Chain congestion.
- **Sports & Entertainment**: FIFA+ Collect: Official FIFA digital collectibles platform on L1 Lux, featuring historic moments, iconic goals, and tournament highlights.  

**On Lux LUExchange-Chain Testnet (Testnet)**
- Used to test metadata integration, marketplace listings, and batch minting.

---

## ERC-1155: Multi-Token Standard Use Cases

**On Lux LUExchange-Chain Mainnet**
- **Gaming Projects**:  
  Crabada: Combines fungible resources (minerals, tokens) with unique NFT characters in one contract.  
- **Collectible Platforms**:  
  Multi-series collections: Managed without deploying new contracts for each.

**On L1 Deployments**
- **Metaverse Economies**: L1s can host both in-game currencies and unique items in one ERC-1155 contract, benefiting from low latency and high scalability.

**On Lux LUExchange-Chain Testnet (Testnet)**
- Testing batch transfers, multi-asset minting, and marketplace integrations before L1 or LUExchange-Chain Mainnet launch.

---

## Observations from Lux’s Current Uses

- **Low Fees Enable Microtransactions**: The cost-efficiency of Lux makes even small-value ERC-20 and ERC-1155 transfers practical.  
- **L1s Enable Asset Isolation**: Projects with heavy transaction loads can launch their own L1 to keep asset operations unaffected by LUExchange-Chain activity.  
- **Testnet Testnet is a Critical Step**: Almost every major Lux project tests token standards on Testnet before going live.  
- **Bridging Expands Liquidity**: Lux supports assets from other EVM networks, extending utility and user reach.

---

In the **next section**, we will analyze **the limits companies face when using these standards**, focusing on challenges like **privacy, compliance, and scalability** and set the stage for introducing **privacy-focused solutions like eERC**.


# Limitations of Current Standards (/academy/blockchain/encrypted-erc/01-what-is-a-digital-asset/03-limitations)

---
title: Limitations of Current Standards
description: Challenges companies face when using ERC-20, ERC-721, and ERC-1155 on Lux.
updated: 2025-09-02
authors: [alejandro99so]
icon: Book
---

The ERC-20, ERC-721, and ERC-1155 standards have become the backbone of asset creation and exchange on Lux’s LUExchange-Chain, Testnet Testnet, and custom L1s. However, while they ensure interoperability and simplicity, they also present **important limitations** that companies and developers must address when building real-world solutions.

---

## 1. Privacy Limitations

All three standards: ERC-20, ERC-721, and ERC-1155, operate on **transparent ledgers**.  
- **Balances are public**: Anyone can view wallet holdings.  
- **Transactions are public**: Every transfer amount and counterparty is visible.  
- **Asset ownership is public**: For ERC-721 and ERC-1155, ownership history and metadata are fully transparent.  

This transparency is useful for auditability but problematic for:  
- Regulated financial institutions.  
- Enterprises managing sensitive transactions.  
- Use cases requiring trade secrecy or personal data protection.  

---

## 2. Compliance Challenges

Lux provides speed and low costs, but these standards **do not include compliance tools by default**.  
- No built-in **selective disclosure** for regulators or auditors.  
- No native mechanism to **restrict transactions** based on jurisdiction.  
- Compliance features must be built as **custom layers**, increasing development cost and complexity.

---

## 3. Scalability Concerns

While Lux’s architecture solves many scaling issues, token standards still introduce some constraints:  
- **ERC-20 and ERC-721**: Each transfer is a separate transaction, which can be inefficient for high-volume operations.  
- **ERC-721**: One contract per collection increases deployment and maintenance overhead.  
- **ERC-1155**: More efficient, but not all dApps and marketplaces fully support it yet.

---

## 4. Asset Management Limitations

- **Single-purpose contracts**: ERC-20 can only handle one fungible token per contract.  
- **No native multi-asset governance**: ERC-721 collections and ERC-20 tokens require separate governance or management systems.  
- **Limited metadata security**: Metadata for NFTs is often stored off-chain and can be altered unless proper safeguards are in place.

---

## Summary Table — Key Limitations on EVM Blockchains

| Standard | Privacy | Compliance | Scalability | Asset Management |
|----------|---------|------------|-------------|------------------|
| ERC-20   | No privacy, public balances & transfers | No built-in compliance | One transfer per transaction | Single token per contract |
| ERC-721  | No privacy, public ownership & metadata | No built-in compliance | One contract per collection | Separate governance per collection |
| ERC-1155 | No privacy, public ownership & metadata | No built-in compliance | Batch transfers supported, but partial ecosystem support | Multi-asset capable but complex |

---

These limitations do not prevent successful deployments, but they **create barriers for industries that require privacy, compliance-readiness, and advanced asset control**.

In the **next section**, we will explore **Real Privacy**: how much privacy blockchain truly offers, why compliance is critical, and how privacy-focused standards like **eERC** can address these challenges in the Lux ecosystem.


# How Private is the Blockchain? (/academy/blockchain/encrypted-erc/02-real-privacy/01-how-private-is-the-blockchain)

---
title: How Private is the Blockchain?
description: Understanding the level of privacy in Lux and the difference between transparency and confidentiality.
updated: 2025-09-02
authors: [alejandro99so]
icon: Eye
---

One of the most common misconceptions about blockchain is that it is **private**.  
In reality, on Lux, whether you operate on the LUExchange-Chain **Mainnet**, **Testnet (Testnet)**, or a custom L1, the blockchain is **transparent by design**. Every transaction is recorded in a public ledger and can be inspected by anyone with the right tools.

---

## Transparency in Lux

- **Every transaction is public**: Transfers, mints, burns, and contract interactions are visible in block explorers like [SnowTrace](https://snowtrace.io).  
- **Balances are public**: Anyone can check the token holdings of any address by querying the blockchain.  
- **Ownership history is public**: For NFTs (ERC-721 and ERC-1155), all past owners are permanently recorded.  

This transparency is valuable for:
- **Auditability**: Anyone can verify that a transaction took place and check the exact amounts.  
- **Trustless systems**: No need for a central authority to confirm balances or transaction histories.  
- **Security monitoring**: Easier to detect suspicious activity or exploits in real time.

---

## Pseudonymity vs Anonymity

Lux, like other EVM-compatible blockchains, is **pseudonymous**, not truly anonymous.  
- **Pseudonymity**: Users are identified by their public address (e.g., `0x1234...abcd`), but not by their real name.  
- **Linkability**: Once an address is tied to an identity (via KYC, exchange deposits, or off-chain information), all past and future activity from that address can be analyzed.  
- **Behavioral profiling**: Patterns in interactions (like dApps used, tokens traded, or NFTs purchased) can reveal insights about the owner.

---

## Confidentiality Limitations

While transparency is useful for verification, it creates significant limitations for certain use cases:
- **Business transactions**: Competitors can see volumes, counterparties, and frequency of payments.  
- **Personal privacy**: Anyone can track your activity and build a profile of your blockchain behavior.  
- **Regulated industries**: Some sectors require confidentiality for compliance (e.g., healthcare, finance).

---

## Example on Lux LUExchange-Chain

If a company pays 50 employees using an ERC-20 token on Lux LUExchange-Chain:
- The **amount**, **date**, and **recipient address** of each payment will be public.  
- A competitor or third party could track salary patterns, hiring trends, or even link addresses to individuals.

---

Lux’s transparent design ensures trust and auditability, but **it does not provide native confidentiality** for balances, transaction amounts, or metadata.  
In the **next section**, we will explore **Compliance**, why privacy alone is not enough, and how companies must align with regulatory requirements when designing blockchain solutions.


# Compliance (/academy/blockchain/encrypted-erc/02-real-privacy/02-compliance)

---
title: Compliance
description: Why regulatory alignment matters for privacy tokens on Lux.
updated: 2025-09-02
authors: [alejandro99so]
icon: Scale
---

Privacy is not the only requirement for enterprise-grade blockchain solutions, **compliance** is equally critical.  
On Lux, whether you deploy to LUExchange-Chain **Mainnet**, **Testnet (Testnet)**, or a custom L1, tokens must often meet **regulatory obligations** to operate legally in certain jurisdictions or industries.

---

## Why Compliance Matters

In finance, healthcare, gaming, and government, compliance is not optional, it is enforced through regulations like:
- **KYC/AML** (Know Your Customer / Anti-Money Laundering): Identifying and verifying participants to prevent illegal activity.
- **Jurisdictional restrictions**: Blocking access from certain regions due to sanctions or laws.
- **Data protection laws**: GDPR (EU), HIPAA (US), and other frameworks require handling sensitive data in specific ways.

---

## Challenges with Current Token Standards

Standard ERC-20, ERC-721, and ERC-1155 implementations on Lux offer **no built-in compliance tools**:
- No **whitelisting** or **blacklisting** capabilities at the protocol level.
- No **selective disclosure**: you cannot show transaction details only to authorized parties while hiding them from the public.
- No **transaction-level restrictions** to enforce rules automatically.

As a result, compliance must be built as a **custom layer**, which:
- Increases development and auditing costs.
- Introduces potential security risks if not implemented correctly.
- Creates inconsistency between projects, making interoperability harder.

---

## The Compliance–Privacy Balance

True privacy on Lux must still allow **authorized oversight**:
- **Auditor access**: Regulators, tax authorities, or compliance officers should be able to review specific transactions without making them public.
- **Selective decryption**: Only authorized entities can view transaction amounts and counterparties.
- **Revocable permissions**: The ability to update who has access without redeploying the entire token contract.

---

## Example in the Lux Ecosystem

Imagine an **L1** created for a private lending network:
- Loans are issued in a **privacy-enabled token** to protect borrower data.
- Regulators need to verify the amounts, interest rates, and repayment schedules.
- Without compliance features, the project must either make all data public (losing privacy) or create a parallel off-chain audit system (increasing complexity).

---

In the **next section**, we will explore **Necessities Solved with Privacy**, real-world scenarios where privacy is not just a “nice to have,” but a **critical requirement** for operations, security, and compliance.


# Necessities Solved with Privacy (/academy/blockchain/encrypted-erc/02-real-privacy/03-necessities-solved-with-privacy)

---
title: Necessities Solved with Privacy
description: Real-world scenarios where privacy on Lux is essential.
updated: 2025-09-02
authors: [alejandro99so]
icon: Lock
---

Privacy on Lux is not only about hiding information, it’s about **unlocking use cases that would otherwise be impossible** in a fully transparent blockchain environment.  
By combining confidentiality with auditability, privacy-enabled tokens can meet both **business** and **regulatory** requirements.

---

## 1. Sensitive Transactions

Certain payments and transfers must remain confidential to protect business interests and personal security:
- **Enterprise payments**: Salaries, supplier payments, and investment deals that should not be visible to competitors.
- **Strategic asset moves**: Acquisitions, treasury management, or cross-company settlements.
- **Personal financial data**: Protecting individuals from profiling or targeted attacks based on on-chain activity.

---

## 2. Enterprise Use

Organizations building on Lux, whether on **LUExchange-Chain** or a dedicated **L1**, may require privacy for:
- **Internal token economies**: Reward points, access tokens, or employee incentives where transaction history should remain private.
- **Corporate NFT strategies**: Membership passes, certifications, or asset ownership records that could reveal strategic information.
- **Supply chain confidentiality**: Tracking goods on-chain without exposing trade volumes and partner relationships.

---

## 3. Regulated Financial Products

Financial institutions can benefit from privacy without sacrificing compliance:
- **Tokenized securities or bonds**: Keeping investor details and trade sizes private while allowing regulator access.
- **Private lending protocols**: Concealing borrower data while enabling repayment verification.
- **Confidential DeFi**: Yield farming or liquidity provision without revealing exact positions to the public.

---

## Why Privacy is a Business Enabler

Without privacy, many organizations avoid blockchain entirely due to:
- **Risk of data exposure**: Competitors analyzing public activity to gain market advantage.
- **Regulatory conflicts**: Inability to comply with privacy laws while using transparent ledgers.
- **Security concerns**: Public transaction data can make users targets for scams or hacks.

By enabling **selective transparency** — where only authorized entities can see sensitive details, Lux projects can:
- Attract enterprise and institutional adoption.
- Expand into regulated markets.
- Create safer, more competitive ecosystems.

---

In the **next section**, we will introduce **Encrypted Tokens**, starting with **eERC (Encrypted ERC)** — Lux’s privacy-focused token standard that brings **encrypted balances, private transfers, and compliance-ready auditability** to the EVM ecosystem.


# What Kind of Privacy Does eERC Provide? (/academy/blockchain/encrypted-erc/03-encrypted-tokens/01-privacity-eerc)

---
title: What Kind of Privacy Does eERC Provide?
description: Understanding the privacy features of eERC in the Lux ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Key
---

In the previous section, we explored why privacy is a critical enabler for blockchain adoption in industries like finance, enterprise, and gaming.  
Now we will focus on **eERC (Encrypted ERC)**, Lux’s encrypted token standard and see the exact kind of privacy it delivers on LUExchange-Chain **Mainnet**, **Testnet(Testnet)**, and **custom L1 deployments**.

---

## Encrypted Balances
- Balances are **fully encrypted** on-chain.  
- Only the token holder (and authorized auditor) can see the actual balance.  
- Prevents competitors, analysts, or malicious actors from tracking your holdings.

---

## Private Transaction Amounts
- Transfer amounts are encrypted and not visible on public explorers like SnowTrace.  
- Observers can see that a transfer occurred but not **how much** was sent.  
- Uses **zero-knowledge proofs** to validate transactions without revealing amounts.

---

## Auditor-Ready Privacy
- Built-in **Auditability Module** allows authorized parties to decrypt specific transactions.  
- Access can be **revoked or rotated** without redeploying the contract.  
- Enables compliance with financial regulations while maintaining user privacy.

---

## EVM Compatibility
- Works seamlessly on Lux LUExchange-Chain Mainnet, Testnet (Testnet), and custom L1s without protocol changes.  
- Fully compatible with existing EVM smart contract tooling.  
- Developers can integrate using the **EncryptedERC Repository**.

---

## Flexible Deployment Modes
- **Standalone Mode**: Fully private token from creation, with optional hidden total supply.  
- **Converter Mode**: Wraps an existing ERC-20 into an encrypted token, enabling private transfers while preserving the ability to unwrap it back to ERC-20.

---

## Example Use Cases

**Confidential DeFi**  
- Private yield farming, liquidity provision, and staking allocations.

**Enterprise Payments**  
- Payroll systems where salaries are encrypted but verifiable to auditors.  
- Supplier payments that conceal exact deal sizes.

**Private Asset Management**  
- Managing tokenized real-world assets without revealing portfolio composition.  
- In-game transactions in private gaming economies.

---

In the **next section**, we will compare **ERC-20 vs eERC** to see exactly how these standards differ in privacy, compliance, and deployment options.


# ERC-20 vs eERC (/academy/blockchain/encrypted-erc/03-encrypted-tokens/02-comparison)

---
title: ERC-20 vs eERC
description: Comparing traditional ERC-20 tokens with eERC in the Lux ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Table
---

In the previous section, we learned what kind of privacy **eERC** offers on Lux.  
Now, let’s compare it directly to **ERC-20**, the most widely used fungible token standard in the EVM ecosystem.

---

## Key Differences

| Feature | ERC-20 | eERC (Encrypted ERC) |
|---------|--------|----------------------|
| **Balance Visibility** | Public: anyone can see wallet balances on-chain. | Private: balances are encrypted, visible only to the holder and authorized auditors. |
| **Transaction Amount Visibility** | Public: amounts are visible in every transfer. | Private: transfer amounts are encrypted and hidden from the public. |
| **Privacy Technology** | None: all data is transparent. | Zero-knowledge proofs (zk-SNARKs) + homomorphic encryption. |
| **Compliance Options** | Requires custom solutions for compliance and auditability. | Built-in Auditability Module allows selective decryption for authorized auditors. |
| **Blockchain Compatibility** | Works on any EVM-compatible chain. | Works on any EVM-compatible chain, including Lux LUExchange-Chain Mainnet, Testnet (Testnet), and custom L1s. |
| **Gas Efficiency** | Very efficient for transfers and approvals. | Slightly higher cost due to encryption and proof verification, but optimized for Lux’s low fees. |
| **Modes Available** | Single implementation. | Standalone Mode and Converter Mode for different privacy needs. |
| **Total Supply Visibility** | Public by default. | Concealed in Standalone Mode (optional in Converter Mode). |
| **Use Cases** | Public tokens, open DeFi, governance tokens. | Confidential DeFi, enterprise payments, private RWA, regulated financial use. |

---

## Summary

While **ERC-20** remains the foundation for most tokens in the EVM ecosystem, it offers no privacy features.  
**eERC**, on the other hand, is designed for scenarios where confidentiality, compliance, and selective transparency are required, making it ideal for enterprise, regulated markets, and advanced DeFi protocols on Lux.

---

In the **next section**, we will explore the **Technology Behind eERC**, understanding the cryptographic tools, on-chain components, and modes of operation that make this privacy possible.


# Technology Behind eERC (/academy/blockchain/encrypted-erc/03-encrypted-tokens/03-technology-behind)

---
title: Technology Behind eERC
description: Understanding the cryptographic tools and architecture that power eERC on Lux.
updated: 2025-09-02
authors: [alejandro99so]
icon: Cpu
---

The **eERC (Encrypted ERC)** standard combines modern cryptography with Lux’s high-performance infrastructure to deliver **confidential transactions** while remaining compatible with the EVM ecosystem.  
In this section, we will break down the key technologies and architecture that make this possible.

---

## Core Privacy Technologies

### 1. Zero-Knowledge Proofs (zk-SNARKs)
- Used to **prove** that a transaction is valid without revealing its details.
- Ensures the sender has enough balance and the transaction respects the rules, without disclosing amounts or balances.
- Highly gas-efficient when deployed on Lux due to its low base fees.

### 2. Homomorphic Encryption
- Allows operations on encrypted values **without decrypting them**.
- Enables balance updates and validations while keeping amounts hidden.
- Balances remain encrypted on-chain at all times.

### 3. BabyJubJub Elliptic Curve
- A **twisted Edwards elliptic curve** optimized for zk-SNARKs.
- Offers fast signature verification inside zero-knowledge circuits.
- Used in eERC for **efficient key generation and proof validation**.

### 4. ElGamal Encryption
- Public-key encryption scheme adapted for elliptic curve cryptography.
- Used to encrypt token balances and transfer amounts on BabyJubJub.
- Supports **homomorphic addition** so encrypted balances can be updated without decryption.

### 5. Poseidon Ciphertext Hashing
- **Poseidon hash** is a ZK-friendly hashing algorithm designed for use inside proof circuits.
- Optimized for minimal gas cost and high efficiency in zk-SNARK verification.
- In eERC, used for commitments and ciphertext integrity checks.

---

## Auditability Module
- Built directly into the eERC architecture.
- Enables **selective decryption** of transactions for authorized auditors or regulators.
- Permissions can be **rotated or revoked** without redeploying the contract.
- Maintains **compliance-readiness** without compromising user privacy.

---

## On-Chain Components

1. **Registrar Contract**  
   - Manages the list of authorized auditors.
   - Handles public keys for encryption and decryption permissions.

2. **EncryptedUserBalances Contract**  
   - Stores all encrypted balances for token holders.
   - Updates balances through zk-SNARK validated operations.

3. **AuditorManager Contract**  
   - Controls access and permissions for auditors.
   - Integrates with the Auditability Module.

4. **Proof Verification Circuits**  
   - Specialized zk circuits that verify transactions meet the protocol’s rules.
   - Operates without revealing transaction details.
   - Optimized for BabyJubJub, Poseidon hashing, and ElGamal operations.

---

## Modes of Operation

### Standalone Mode
- Token is **fully private** from the moment it is created.
- Total supply can be hidden from the public.
- Ideal for enterprise deployments or regulated private markets.

### Converter Mode
- Wraps an existing ERC-20 token into eERC form for private transfers.
- Allows unwrapping back into the original ERC-20 token.
- Perfect for projects that want optional privacy without changing their base asset.

---

## Developer Integration

- Contracts, circuits and scripts to be used.
- Compatible with Lux LUExchange-Chain Mainnet, Testnet (Testnet), and custom L1s.
- Does not require modifying the underlying blockchain protocol.

---

In the **next section**, we will cover **Usability of eERC**, focusing on Standalone vs Converter modes, real-world use cases, and how developers and users interact with encrypted tokens on Lux.


# Deployment Modes of eERC (/academy/blockchain/encrypted-erc/04-usability-eerc/01-deployments-mode)

---
title: Deployment Modes of eERC
description: Understanding Standalone and Converter deployment modes of eERC in the Lux ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Split
---

The **eERC** standard offers two deployment modes to fit different project needs: **Standalone Mode** and **Converter Mode**.  
Both deliver encrypted balances and private transfers, but they differ in how the token is created and used.

---

## Standalone Mode
- Token is **private from creation**, all balances and amounts are encrypted from the first mint.
- Uses **ElGamal encryption** over the **BabyJubJub** curve for privacy.
- Transaction proofs use **Poseidon hashing** for efficiency in zk-SNARKs.
- **Optional hidden total supply** to prevent public insight into circulation.
- Best suited for:
  - Enterprise payment systems.
  - Regulated financial assets with selective auditor access.
  - Private gaming economies on Lux L1s.

---

## Converter Mode
- Wraps an **existing ERC-20 token** into an encrypted form.
- Allows private transfers using the eERC format while preserving the option to unwrap back to the public ERC-20.
- Uses the same encryption and proof flow as Standalone Mode.
- Best suited for:
  - Adding privacy to an already deployed public token.
  - Hybrid systems where some transactions are public and others private.
  - Bridging between public liquidity pools and private markets.

---

In the **next section**, we will explore **Use Cases of eERC**, including examples from Lux LUExchange-Chain Mainnet, Testnet (Testnet), and custom L1 deployments, along with a step-by-step view of a private transfer flow.


# Use Cases of eERC (/academy/blockchain/encrypted-erc/04-usability-eerc/02-use-cases)

---
title: Use Cases of eERC
description: Real-world applications of eERC on Lux and the flow of a private transfer.
updated: 2025-09-02
authors: [alejandro99so]
icon: Rocket
---

The **eERC** standard can be deployed across Lux LUExchange-Chain **Mainnet**, **Testnet (Testnet)**, and **custom L1s**, enabling privacy in a variety of scenarios.

---

## Lux LUExchange-Chain
- **Private DeFi operations**: Farming, lending, and trading without exposing transaction sizes.
- **Confidential payments**: Salaries and supplier payments visible only to participants and authorized auditors.

---

## Custom L1 Deployments
- **Tokenized real-world assets (RWA)**: Privacy-enabled trading with compliance auditability.
- **Private gaming economies**: Fungible and non-fungible in-game assets with encrypted transfers.

---

## Step-by-Step: Private Transfer Flow (Standalone Mode)

1. **Transaction Creation**  
   - Wallet integrates.  
   - Amount is encrypted using **ElGamal** over **BabyJubJub**.  
   - A **Poseidon hash** of the ciphertext is generated for proof validation.

2. **Proof Generation**  
   - User creates a **zk-SNARK** proving the transaction’s validity without revealing details.

3. **On-Chain Verification**  
   - Smart contract verifies the proof in a zk-friendly circuit optimized for BabyJubJub and Poseidon.  
   - Encrypted balances in the `EncryptedUserBalances` contract are updated.

4. **Auditor Access (Optional)**  
   - Authorized auditors can decrypt specific transactions if enabled in the **Registrar Contract**.

5. **Finalization**  
   - Transaction is recorded on Lux with encrypted values only.  
   - Explorers show the transfer occurred, but not the amount or updated balances.

---

In the **next section**, we will examine the **eERC Contracts Flow**, covering how to create an eERC, configure auditor access, choose zk-proof types, and interact with it as a user.


# eERC Contracts Flow (/academy/blockchain/encrypted-erc/05-eerc-contracts-flow/01-step-by-step)

---
title: eERC Contracts Flow
description: Step-by-step process to create, configure, and use eERC on Lux.
updated: 2025-09-02
authors: [alejandro99so]
icon: GitBranch
---

The **eERC (Encrypted ERC)** standard on Lux provides privacy-preserving tokens while remaining EVM-compatible.  
This section walks through the full lifecycle of an eERC, from deployment to interaction, including key considerations for developers.

---

## 1. Creating Your eERC

### Step 1: Select Deployment Mode
- **Standalone Mode**: Fully private token from creation, optional hidden total supply.
- **Converter Mode**: Wrap an existing ERC-20 into an encrypted format using a TokenTracker.

### Step 2: Deploy the Core Contracts
- **encryptedERC**: Stores encrypted balances.
- **Registrar Contract**: Manages auditor keys and permissions.
- **Proof Verifier**: Validates zk-SNARK proofs for transfers.

### Step 3: Configure Auditor Access (Optional)
- Register auditors in the **Registrar Contract**.
- Provide them with decryption permissions for compliance scenarios.

---

## 2. About the zk-Proof Type

In the current **EncryptedERC** implementation, the proving system is **not chosen by the end-user**.  
By default, the official Lux eERC contracts use **Groth16** for proof generation and verification.

If a developer wants to change the proving system (e.g., to PLONK or Halo2), they must:
1. Modify the Circom circuits.
2. Regenerate the zk verifiers.
3. Deploy new contract versions using those verifiers.

| Proof System | Why it Matters | Current Status in eERC |
|--------------|---------------|------------------------|
| **Groth16** | Fast verification, small proof size, low gas cost | ✅ Default in official repo |
| **PLONK** | Universal setup, flexibility for new circuits | ❌ Requires custom build |
| **Halo2** | No trusted setup, recursion support | ❌ Requires major changes |

> **Lux Tip:** Groth16 is optimal for most L1 and LUExchange-Chain deployments due to its low gas cost and existing integration in the eERC stack.

---

## 3. Encryption & Hashing Details
- **Curve**: BabyJubJub for zk-friendliness.
- **ElGamal**: ElGamal for balance and transfer amounts.
- **Poseidon**: Poseidon Cipher Text for proof inputs and Merkle trees.

---

## 4. Backend Deployment Flow

### Step 1: Set Up Environment
```bash
git clone https://github.com/alejandro99so/eerc-backend-converter.git
cd eerc-backend-converter
```

### Step 2: Configure `.env` variables in Hardhat

- This step is VERY important because you need those private keys to run `zkit` files.

- Create `.env` file:
- Add to `.env` file: RPC_URL = YOUR_RPC_URL // If you are using Testnet LUExchange-Chain (https://api.lux-test.network/ext/bc/C/rpc)
- Add to `.env` file: PRIVATE_KEY = PRIVATE_KEY_1
- Add to `.env` file: PRIVATE_KEY_2 = PRIVATE_KEY_2

### Step 3: Install dependencies and create `zkit` files

```bash
npm install
```

### Step 4: Choose your way (Converter way) and deploy main contracts

```bash
npm run converter:init
npm run converter:core
```

### Step 5: Register Users

```bash
npm run converter:register
```
 
- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to register PRIVATE_KEY_2 in the `scripts/converter/03_register-user.ts` file

```bash
npm run converter:register
```

### Step 6: Set auditor

```bash
npm run converter:auditor
```

### Step 7: Get faucet tokens for PRIVATE_KEY_2

- Let's check our first balance (PRIVATE_KEY_2)
```bash
npm run converter:balance
```

- Let's get faucet tokens for PRIVATE_KEY_2
```bash
npm run converter:faucet
```

### Step 8: Deposit tokens

#### To PRIVATE_KEY_1 

- Change `WALLET_NUMBER = 2;` to `WALLET_NUMBER = 1;` to get token balance from PRIVATE_KEY_1 in `scripts/converter/08_check_balance.ts` file
- Let's check our first balance
```bash
npm run converter:balance
```
- Let's deposit some ERC20 tokens to get eERC20 tokens
```bash
npm run converter:deposit
```
- Let's check our new balance
```bash
npm run converter:balance
```

#### To PRIVATE_KEY_2

- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to get token balance from PRIVATE_KEY_2 in `scripts/converter/08_check_balance.ts` file
- Let's check our first balance
```bash
npm run converter:balance
```
- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to deposit tokens from PRIVATE_KEY_2 in the `scripts/converter/06_deposittx.ts` file
- Let's deposit some ERC20 tokens to get eERC20 tokens
```bash
npm run converter:deposit
```
- Let's check our new balance
```bash
npm run converter:balance
```

### Step 9: Transfer tokens
- Let's transfer encrypted tokens from PRIVATE_KEY_1 to PRIVATE_KEY_2
```bash
npm run converter:transfer
```

### Step 10: Withdraw tokens from `PRIVATE_KEY_2`

#### To PRIVATE_KEY_1

- Let's transfer encrypted tokens from PRIVATE_KEY_1 to PRIVATE_KEY_2
```bash
npm run converter:transfer
```
- Change `WALLET_NUMBER = 2;` to `WALLET_NUMBER = 1;` to get token balance from PRIVATE_KEY_1 in `scripts/converter/08_check_balance.ts` file
- Let's check our new balance after transferring tokens
```bash
npm run converter:balance
```

#### To PRIVATE_KEY_2

- Let's withdraw encrypted tokens (eERC20) from PRIVATE_KEY_2 to get tokens (ERC20)
```bash
npm run converter:withdraw
```
- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to get token balance from PRIVATE_KEY_2 in `scripts/converter/08_check_balance.ts` file
- Let's check our new balance for `PRIVATE_KEY_2` after transferring tokens
```bash
npm run converter:balance
```

### Step 11:  Choose your way (Standalone way)

- Follow the flow by yourself and reach out to us at https://t.me/luxacademy

## 6. Considerations for Production

- **Gas Costs**: Proof verification adds overhead; optimize circuits.  
- **Auditor Key Rotation**: Plan for secure revocation and re-assignment.  
- **Compliance**: Align privacy settings with jurisdictional requirements.


# What is a Blockchain? (/academy/blockchain/blockchain-fundamentals/02-what-is-a-blockchain/01-what-is-a-blockchain)

---
title: What is a Blockchain?
description: Understand the high-level structure of this chapter.
updated: 2024-09-01
authors: [martineckardt]
icon: Book
---

Blockchains introduce a lot of new concepts. In this chapter we will approach the concept from a high level and see how it compares with other kinds of computers we are used to:

- **Decentralized Computer:** How is a blockchain different from computers we know?
- **Decentralized Applications:** What are dApps? 
- **Use Cases:** When does it make sense to use Blockchain?


# Decentralized Computer (/academy/blockchain/blockchain-fundamentals/02-what-is-a-blockchain/02-decentralized-computer)

---
title: Decentralized Computer
description: Explore how different types of computers, including smartphones, PCs, web servers, and blockchains, serve specific functions based on their unique characteristics. Understand the benefits and trade-offs of blockchain as a decentralized computer, ideal for secure transactions but less efficient and more complex than traditional centralized systems.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

We interact with various types of computers every day, each designed to serve specific functions based on its unique characteristics. Smartphones, for example, are portable and convenient, offering powerful computing capabilities in a compact form. They are ideal for tasks that require mobility, such as communication, navigation, and media consumption. However, their small screen size and limited processing power compared to larger computers make them less suitable for tasks that require intensive computing power or extensive multitasking. PCs, on the other hand, provide more robust processing power and versatility. They are well-suited for tasks like video editing, gaming, or software development, where performance and the ability to use larger screens and peripherals like a mouse and keyboard are crucial. Yet, they lack the portability of smartphones and often require more space and power to operate.

![](/common-images/blockchain-basics/decentralized-computer/different-kinds-of-computer.png)

Web servers represent another type of computer, designed to handle large volumes of data and manage multiple simultaneous requests from users across the internet. They are optimized for reliability, speed, and the ability to run continuously without interruption, making them crucial for hosting websites, online services, and cloud computing platforms. While web servers excel at handling complex backend processes and large-scale operations, they are not intended for direct user interaction or tasks requiring a graphical user interface, which is where PCs and smartphones come in. Each type of computer has its strengths and weaknesses, and they often work together within the broader digital ecosystem, each performing tasks that suit their design and capabilities best.

The internet, as we know it today, is built on a centralized architecture, where data and services are controlled and maintained by a few large entities like data centers and internet service providers. However, the advent of blockchain technologies has opened up new possibilities for a more decentralized internet, often referred to as Web 3.0 or the decentralized web.

## Blockchains are Decentralized Computers

Blockchain can be thought of as a new kind of computer. The key advantage of this new kind of computer is decentralization, meaning that no single entity has control over the entire system. Instead, control is distributed across many participants, which enhances security and transparency, as all transactions are verified by consensus and recorded on an immutable ledger. 

![](/common-images/blockchain-basics/decentralized-computer/blockchain-computer.png)

However, this decentralization comes with trade-offs. Blockchains are inherently less efficient than traditional centralized systems. The complexity of managing and maintaining a decentralized network, along with slower transaction speeds, can be significant downsides compared to more traditional, centralized computing models. 

This makes blockchain ideal for certain use cases, like secure financial transactions or decentralized applications, but less suitable for tasks requiring high speed and efficiency.


# Decentralized Applications (/academy/blockchain/blockchain-fundamentals/02-what-is-a-blockchain/03-decentralized-applications)

---
title: Decentralized Applications
description: TBD
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

Programs and apps are software applications designed to run on different types of computers, such as smartphones, PCs, and web servers. On smartphones, apps are typically designed for specific tasks like messaging, gaming, or social media, optimized for touch interfaces and mobile connectivity. PCs run more complex programs, such as word processors, video editors, or development tools, which take advantage of larger screens, more powerful hardware, and the ability to handle multitasking. Web servers, on the other hand, run server-side applications that power websites, process data, and handle multiple user requests simultaneously. These programs often provide the backend services that apps on smartphones and PCs rely on to function.

![](/common-images/blockchain-basics/decentralized-computer/decentralized-applications.png)

Similarly, smart contracts or decentralized applications (dApps) are programs that run on a blockchain. A smart contract is a self-executing program with the terms of the agreement directly written into code, operating without the need for a trusted central authority. dApps are more complex, often consisting of multiple smart contracts that together offer a full application experience on the blockchain. Like traditional apps, these blockchain-based programs can perform a wide range of tasks, from managing digital assets to running decentralized finance (DeFi) protocols.

![](/common-images/blockchain-basics/decentralized-computer/decentralized-applications-connected.png)

Different types of applications can interoperate across these platforms, enabling a seamless user experience. For instance, a mobile app can interact with a backend running on a web server to fetch or update data. Similarly, the same app could also interact with a smart contract on a blockchain to verify transactions or access decentralized services. This interoperability allows users to benefit from the strengths of each platform, combining the user-friendliness of mobile apps, the processing power of web servers, and the security and transparency of blockchain technology.

# Use Cases (/academy/blockchain/blockchain-fundamentals/02-what-is-a-blockchain/04-use-cases)

---
title: Use Cases
description: Explore the unique advantages and challenges of blockchain technology in finance, supply chain management, and voting systems. Learn how blockchain enhances security, transparency, and decentralization, while also considering its limitations in efficiency and complexity.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

Blockchains have unique properties that make them an excellent fit for certain use cases where security, transparency, and decentralization are paramount:

### Finance
Blockchains enable secure, transparent transactions without the need for intermediaries. This is the foundation of cryptocurrencies and decentralized finance (DeFi) platforms. The immutability of blockchain records ensures that financial transactions are tamper-proof and can be audited at any time, making it ideal for high-stakes environments where trust is critical.

### Supply Chain Management
Blockchain can provide an immutable record of a product's journey from origin to consumer, increasing transparency and reducing fraud. This helps ensure that every step of the supply chain is accurately tracked and verified.

### Voting Systems
Blockchain's transparency and security ensure that votes are accurately counted and cannot be altered. This is crucial for maintaining democratic integrity and building trust in electoral processes.

## Downsides

However, the same properties that make blockchains so powerful in these areas also introduce significant challenges. Blockchains are inherently less efficient than traditional databases because they require consensus among distributed nodes, which can slow down transaction speeds and increase the complexity of operations. This makes blockchain less suitable for use cases where high speed and efficiency are critical, such as real-time data processing or high-frequency trading. Additionally, the complexity of developing and maintaining blockchain systems can be a barrier, particularly for applications that don't require the levels of security and decentralization that blockchains offer.

When deciding whether to use blockchain, consider whether your use case requires the specific advantages of decentralization, transparency, and security. Blockchain is well-suited for applications where trust between parties is a major concern and where an immutable record of transactions is essential. However, if your application demands high throughput, real-time processing, or simplicity, a traditional centralized system might be more appropriate. In short, blockchain is a powerful tool for the right situations, but its use should be carefully considered against the specific needs of your application.

# Payments Use Case (/academy/blockchain/blockchain-fundamentals/03-payments-use-case/01-payments-use-case)

---
title: Payments Use Case
description: Explore how blockchain technology can revolutionize payments by building decentralized systems. This chapter delves into account balances, transactions, and user interactions, highlighting the benefits of blockchain for security, transparency, and decentralization. Discover how these concepts apply to various use cases beyond payments, including decentralized finance, voting systems, and supply chain management.
updated: 2024-09-01
authors: [martineckardt]
icon: Book
---

In this chapter we will dive deeper in the payments use case. We will explore how blockchain technology can be used to build a decentralized payment system. We will look at the different components of a payment system, such as account balances, transactions, and user interactions. We will also discuss the benefits of using blockchain technology for payments, such as security, transparency, and decentralization.

| Use Case                  | Data Structures  	| User Interactions  	|
|-----------------------	|------------------	|--------------------	|
| Payments              	| Account Balances 	| Transfer Funds     	|
| Decentralized Finance 	| Loans, ...       	| Borrow, Repay, ..  	|
| Voting Systems        	| Votes            	| Vote               	|
| Supply Chain          	| Shipments        	| Hand Over, Deliver 	|
| Identity Management   	| Certificates     	| Issue, Proof       	|

Many of the concepts we will discuss in this chapter are applicable to other use cases as well. For example, the idea of account balances and transactions is not unique to payments but can be found in other applications like decentralized finance (DeFi) or supply chain management. Similarly, user interactions such as transferring funds or voting can be applied to various use cases, each with its unique requirements and challenges.

So while we are discussing this specific use case, try to think about how these concepts could be adapted to other scenarios. This will help you understand the broader implications of blockchain technology and how it can be used to solve a wide range of problems across different industries and domains.

# Account Balances & Transfers (/academy/blockchain/blockchain-fundamentals/03-payments-use-case/02-account-balances-transfers)

---
title: Account Balances & Transfers
description: Learn about account balances, which reflect the current amount of money or assets in an account after credits and debits. Discover how transfers work by moving funds between accounts, ensuring balance integrity across financial systems.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

## Account Balances

Account Balances refer to the current amount of money or assets held in a specific account at a given time. This number reflects the total value after all credits (additions) and debits (subtractions) have been accounted for, indicating how much the account holder has available to use or withdraw. For example, in a bank account, the balance represents the amount of money that the account holder can access, whether for spending, saving, or transferring.

<div className="max-w-96 mx-auto">
    ![](/common-images/blockchain-basics/payments/account-balances.png)
</div>

## Transfers

A Transfer is the process of moving money or assets from one account to another. During a transfer, the balance of the sending account is reduced by the amount being transferred, while the balance of the receiving account is increased by the same amount. This operation ensures that the total value across all accounts remains constant, maintaining the integrity of the overall financial system. 

![](/common-images/blockchain-basics/payments/transfer.png)

## Invalid Transfers

An invalid transfer occurs when a transaction request exceeds the available balance in the sending account. In such cases, the transfer cannot be executed, and the system will reject the transaction to prevent overdrafts. As a result, both the sending and receiving account balances remain unchanged, preserving the integrity of the financial records. This safeguard ensures that accounts do not inadvertently fall into negative balances and maintains accurate and reliable financial tracking.

![](/common-images/blockchain-basics/payments/transfer-invalid.png)

# Ledger (/academy/blockchain/blockchain-fundamentals/03-payments-use-case/03-ledger)

---
title: Ledger
description: Understand the high-level structure of this chapter.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

A ledger is a comprehensive record-keeping system that documents all transactions. It maintains a detailed and chronological list of transactions, capturing every transfers across accounts. This ensures that every action is accurately tracked and traceable, providing a clear and complete view of the system's activity.

![](/common-images/blockchain-basics/payments/ledger.png)

## Immutability

An immutable ledger means that once a transaction is recorded, it cannot be altered or deleted. This immutability ensures that the historical record of all transactions remains intact and unchangeable, which is crucial for maintaining transparency and trust. Even if errors are made or transactions are invalid, the ledger preserves the original data, preventing tampering or unauthorized modifications.

## Append-Only

An append-only ledger operates by adding new transactions to the end of the record without altering any previous entries. This means that while the ledger grows with each new transaction, past transactions remain unchanged and preserved. Invalid transactions, which fail to execute due to issues like insufficient funds, are still recorded in the ledger to maintain a complete history. To reverse the effects of a transaction, a new transaction must be appended that counteracts the previous one, ensuring the integrity and consistency of the ledger’s overall state.

# Transaction Ordering through Consensus (/academy/blockchain/blockchain-fundamentals/04-tx-ordering-through-consensus/01-tx-ordering-through-consensus)

---
title: Transaction Ordering through Consensus
description: Explore how blockchain networks achieve agreement on transaction order through consensus mechanisms. Learn why consistent transaction ordering is critical for preventing double-spending and maintaining a unified ledger state across all network participants.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

In a blockchain network, thousands of participants may be submitting transactions simultaneously from anywhere in the world. For the system to function correctly, all participants must agree on a single, consistent order of transactions. This agreement is achieved through **consensus mechanisms**: the protocols that enable distributed networks to coordinate and maintain a unified view of the blockchain's state.

## Why Transaction Ordering Matters

Imagine two people trying to spend the same money at the same time, this is called a **double-spending problem**. In traditional banking, a central server processes transactions one by one and ensures you can't spend the same dollar twice. But in a decentralized blockchain, there's no central authority to determine which transaction came first.

Consider this scenario:

- Alice has 10 tokens in her account
- She creates two transactions almost simultaneously:
  - Transaction A: Send 10 tokens to Bob
  - Transaction B: Send 10 tokens to Charlie
- Both transactions are valid on their own, but Alice doesn't have enough tokens to fulfill both

The network must decide which transaction to process first. Whichever transaction is ordered first will succeed, and the second will be rejected as invalid (insufficient balance). Without a consensus mechanism to establish a definitive order, different nodes might process these transactions in different orders, leading to inconsistent ledger states across the network.

This is why **transaction ordering through consensus** is fundamental to blockchain technology.

## What Is Consensus?

**Consensus** is the process by which distributed network participants agree on a single, authoritative version of the truth: in this case, the order and validity of transactions. A consensus mechanism is the set of rules and procedures that enables this agreement.

Key objectives of consensus mechanisms:

1. **Agreement**: All honest nodes eventually agree on the same transaction order
2. **Validity**: Only valid transactions (properly signed, sufficient balance, etc.) are included
3. **Termination**: The network reaches consensus in a reasonable time
4. **Integrity**: The agreed-upon order cannot be altered retroactively

## How Consensus Orders Transactions

Different consensus mechanisms use different approaches, but they generally follow a similar pattern:

### The Basic Process

1. **Transaction Submission**: Users create and broadcast transactions to the network

2. **Transaction Pool**: Each node maintains a pool (or mempool) of unconfirmed transactions it has received

3. **Block Proposal**: Specific nodes (miners, validators, or leaders, depending on the consensus mechanism) are selected or compete to propose the next block of transactions

4. **Block Validation**: Other nodes verify that the proposed block contains valid transactions in a valid order

5. **Block Acceptance**: Through the consensus mechanism, the network agrees to accept or reject the proposed block

6. **Blockchain Extension**: Once accepted, the block is added to the blockchain, and its transaction order becomes permanent

7. **State Update**: All nodes update their local copy of the blockchain state based on the newly confirmed transactions



## Consensus vs. Transaction Ordering

It's important to understand the relationship between these concepts:

- **Consensus Mechanism**: The overall protocol that enables distributed agreement
- **Transaction Ordering**: The specific outcome achieved through consensus—determining the sequence in which transactions are processed

The consensus mechanism is the tool, and transaction ordering is one of the primary goals it achieves. But consensus mechanisms do more than just order transactions, they also:

- Determine who can add new blocks to the chain
- Prevent malicious actors from rewriting history
- Ensure the network remains operational even when some nodes fail or act dishonestly
- Distribute decision-making power across the network

## Why Decentralized Consensus Is Challenging

Achieving consensus in a decentralized network is remarkably difficult because:

1. **No Central Authority**: There's no trusted party to make final decisions

2. **Network Delays**: Messages take time to propagate across the network, so different nodes may see transactions in different orders

3. **Byzantine Actors**: Some participants may be malicious and try to disrupt consensus or manipulate transaction ordering for their benefit

4. **Asynchrony**: The network doesn't operate in perfect synchronization—nodes may go offline, come back online, or experience varying network conditions



# Longest Chain Consensus (/academy/blockchain/blockchain-fundamentals/04-tx-ordering-through-consensus/02-longest-chain-consensus)

---
title: Longest Chain Consensus
description: Understand the longest chain rule and how it resolves conflicts in blockchain networks. Learn why accumulated chain weight determines the valid chain and how this mechanism prevents forks from permanently splitting the network.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: BookOpen
---

The **Longest Chain Rule** is a fundamental principle used in many blockchain networks to resolve conflicts and maintain a single, unified ledger. It's the mechanism that ensures all nodes eventually agree on which version of the blockchain is the "correct" one, whether the network uses Proof of Work, Proof of Stake, or other mechanisms.

## The Problem: Competing Chains

In a distributed network where multiple block producers are working simultaneously, it's possible for two validators to propose valid blocks at nearly the same time. When this happens:

- Both validators broadcast their blocks to the network
- Different nodes might receive different blocks first
- The blockchain temporarily "forks" into two competing versions
- Each version is valid on its own, but the network must choose one

Without a clear rule for resolving this situation, the network could permanently split into different chains, destroying the consensus that makes blockchain valuable.

## What Is the Longest Chain Rule?

The **Longest Chain Rule** states: **when multiple valid versions of the blockchain exist, nodes should accept the chain with the most accumulated weight as the authoritative chain.**

"Longest" doesn't necessarily mean the most blocks—it means the chain representing the greatest cumulative weight according to the protocol's rules. The specific weight metric varies by consensus mechanism, but the principle remains the same.

### A Simpler Way to Think About It

Think of it as the "preferred" chain—the one that the protocol considers most valid based on its consensus rules. The chain with the most accumulated weight represents the majority's view of the transaction history, whether that majority is measured by computational resources, stake, or other validation criteria.

## How the Longest Chain Rule Works

Let's walk through a typical scenario:

### Step 1: The Fork

1. Block 100 is the latest confirmed block
2. Validator Alice proposes Block 101A at the same moment Validator Bob proposes Block 101B
3. Both blocks are valid and properly reference Block 100
4. Alice broadcasts Block 101A; Bob broadcasts Block 101B
5. Nodes closer to Alice add 101A to their chain; nodes closer to Bob add 101B
6. The network now has two competing chains

### Step 2: The Race

Both chains continue:
- Some validators build on top of Block 101A
- Other validators build on top of Block 101B
- Each chain is growing independently
- Neither is "wrong"—they're both valid according to protocol rules

### Step 3: Resolution

Eventually (usually within seconds or minutes):
- A validator building on Block 101A proposes Block 102A
- Now the chain ending in Block 102A is longer (has more cumulative weight)
- Nodes following the 101B chain see the longer chain
- According to the longest chain rule, they switch to the longer chain
- Block 101B is "orphaned"—it's valid but no longer part of the main chain
- Transactions in Block 101B return to the mempool to be included in future blocks

### Step 4: Convergence

- All nodes now agree on the chain: Block 100 → Block 101A → Block 102A
- The network has re-converged on a single version
- Normal operation continues

## Why Does This Work?

The longest chain rule works because of several key properties:

### Honest Majority Assumption

If honest validators control the majority of the network's validation power:
- The honest chain will grow faster on average
- Eventually, the honest chain will always be longer
- The network naturally converges on the honest version

### Self-Reinforcing Mechanism

Once one chain gets ahead:
- More validators see it as the valid chain
- More validators build on top of it
- It extends even further ahead
- The gap becomes insurmountable for the shorter chain

### Economic Incentives

Validators are incentivized to build on the longest chain:
- Only blocks in the longest chain earn rewards
- Building on a shorter chain wastes resources and validation opportunities
- Rational validators immediately switch to the longest chain when they see it

## Implications for Transaction Finality

The longest chain rule has important implications for when transactions can be considered "final":

### Confirmations

A transaction's **confirmation count** is the number of blocks added after the block containing that transaction:

- **0 confirmations**: Transaction is in the mempool but not yet in a block (unconfirmed)
- **1 confirmation**: Transaction is in the latest block
- **2 confirmations**: One block has been added after the block containing the transaction
- **Multiple confirmations**: The more confirmations, the more secure the transaction

### Why Wait for Multiple Confirmations?

The more confirmations a transaction has, the deeper it is in the blockchain:

- To reverse a transaction with 1 confirmation, an attacker needs to produce 2 blocks faster than the honest network
- To reverse a transaction with 6 confirmations, an attacker needs to produce 7 blocks faster than the honest network
- This becomes exponentially harder with each additional confirmation

**Probabilistic Finality**: In systems using the longest chain rule, finality is never 100% absolute—there's always a theoretical possibility of reversal. However, this probability becomes negligibly small after several confirmations.

## When the Longest Chain Rule Can Be Attacked

### The 51% Attack

If an attacker controls more than 50% of the network's validation power:

1. **They can create a private chain**: Produce blocks in secret without broadcasting them
2. **Outpace the honest chain**: Because they control the majority, their secret chain grows faster
3. **Release the longer chain**: Suddenly broadcast their chain, which is now longer
4. **Network switches**: Nodes follow the longest chain rule and switch to the attacker's version
5. **Transactions reversed**: Transactions in the honest chain are reversed

**Why This Rarely Happens**:
- Acquiring 51% of validation power is extremely expensive (billions of dollars for major networks)
- The attack would crash the cryptocurrency's value, destroying the attacker's investment
- The attack is detectable and the community can respond (fork to a new chain, change consensus algorithm)

### Deep Reorgs

A **deep reorganization** (reorg) occurs when a long chain is replaced by an even longer competing chain:

- **Shallow reorgs** (1-2 blocks): Common and expected, happen naturally due to network delays
- **Deep reorgs** (6+ blocks): Extremely rare and usually indicate an attack or major network problem
- **Protection**: Waiting for more confirmations protects against all but the most resourced attackers

## Key Takeaways

- The longest chain rule resolves temporary forks by having nodes accept the chain with the most accumulated weight
- It ensures the network converges on a single, consistent version of transaction history
- Transaction finality is probabilistic—more confirmations mean exponentially higher security
- The rule works because honest validators control the majority of validation power and have incentives to follow it
- 51% attacks are theoretically possible but economically impractical for large, decentralized networks

The longest chain rule is a cornerstone of many blockchain consensus mechanisms, transforming a chaotic distributed system into an ordered, synchronized ledger that all participants can trust. It's a beautifully simple solution to a complex problem: letting the network reach agreement through a clear, objective metric rather than requiring explicit coordination.

<Quiz quizId="1002"/>


# Transaction Lifecycle (/academy/blockchain/blockchain-fundamentals/04-tx-ordering-through-consensus/xx-tx-lifecycle)

---
title: Transaction Lifecycle
description: Follow a blockchain transaction from creation to finalization. Learn each step in the journey—from signing with your private key to achieving confirmation deep within the blockchain.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Notebook
---

Understanding the complete lifecycle of a blockchain transaction helps demystify how decentralized systems process payments and maintain security. Let's follow a transaction from start to finish, exploring what happens at each stage.

## Creation

A transaction begins when a user decides to transfer assets. This involves specifying several key pieces of information:

**What's Included**:
- **Sender's address**: Derived from the sender's public key, identifying who is sending the assets
- **Recipient's address**: The destination address where the assets will be sent
- **Amount**: How much cryptocurrency or tokens to transfer
- **Transaction fee**: Payment offered to miners/validators for including the transaction in a block
- **Nonce**: A sequence number that prevents the same transaction from being processed multiple times
- **Additional data**: Optional fields for smart contract interactions or notes

**User Interaction**:
The user typically interacts with wallet software (desktop app, browser extension, mobile app, or hardware wallet) that provides a user-friendly interface for creating the transaction. Behind the scenes, the wallet constructs the transaction data structure according to the blockchain's protocol specifications.

**Example**:
Alice wants to send 10 LUX to Bob. She opens her wallet, enters Bob's address (0x742d35Cc...), specifies 10 LUX, and reviews the estimated transaction fee of 0.01 lux. She confirms she wants to proceed.

## Signing

Once the transaction is created, it must be cryptographically signed to prove authorization:

**The Signing Process**:
1. The transaction data is hashed to create a unique fingerprint of the transaction
2. This hash is encrypted using the sender's **private key**, creating a digital signature
3. The signature is attached to the transaction along with the sender's public key
4. The combined package (transaction + signature + public key) is now ready for broadcasting

**Why Signing Matters**:
- **Authentication**: Proves the transaction was authorized by the owner of the private key
- **Integrity**: Any modification to the transaction data would invalidate the signature
- **Non-repudiation**: The sender cannot later deny creating the transaction

**Security Note**: The private key never leaves the wallet and is never transmitted over the network. Only the signature (produced using the private key) is shared.

**Example**:
Alice's wallet uses her private key to sign the transaction. The wallet computes a unique signature like "0x8f3b2a..." that mathematically binds Alice's authorization to this specific transaction sending 10 LUX to Bob.

## Broadcasting

After signing, the transaction is broadcast to the peer-to-peer network:

**How Broadcasting Works**:
1. The wallet sends the signed transaction to one or more nodes it's connected to
2. Each node that receives the transaction performs basic validation
3. If valid, the node forwards the transaction to its peer nodes
4. This process continues until the transaction propagates throughout the network
5. Within seconds, most nodes have received the transaction

**Network Topology**:
Blockchain networks use a peer-to-peer (P2P) gossip protocol where each node connects to multiple other nodes. When a node receives a new transaction, it shares it with its neighbors, who share it with their neighbors, creating exponential propagation.

**What Gets Broadcast**:
- The complete transaction data
- The digital signature
- The sender's public key

**Example**:
Alice's wallet connects to several Lux nodes and sends them her signed transaction. Within 1-2 seconds, the transaction has propagated to thousands of nodes worldwide. Each node now knows that Alice wants to send 10 LUX to Bob.

## Verification

Before accepting a transaction, nodes perform multiple checks:

**Validation Checks**:

1. **Signature Verification**:
   - Use the provided public key to verify the signature
   - Confirm the transaction was signed by the owner of the sender's address
   - Reject if signature is invalid or doesn't match the public key

2. **Balance Check**:
   - Query the current blockchain state to check the sender's balance
   - Ensure the sender has enough assets to cover both the transfer amount and the transaction fee
   - Reject if insufficient balance

3. **Nonce Verification** (account-based systems):
   - Check that the transaction nonce matches the expected sequence number
   - Prevents replay attacks and ensures transactions are processed in order
   - Reject if nonce is incorrect

4. **Format Validation**:
   - Verify the transaction follows the correct data structure
   - Check that addresses are valid
   - Ensure the transaction isn't malformed

5. **Double-Spend Prevention**:
   - Check that the same input hasn't already been spent in another transaction (UTXO systems like Bitcoin)
   - Compare against pending transactions in the mempool

**Two-Stage Validation**:
- **Fast validation**: Nodes do lightweight checks when receiving a transaction via broadcast
- **Full validation**: Miners/validators do comprehensive checks before including it in a block

**What Happens If Verification Fails**:
- The node rejects the transaction and doesn't forward it to peers
- The transaction dies and doesn't enter the mempool
- The sender's wallet may receive an error message
- The sender must fix the issue and create a new transaction

**Example**:
Nodes receive Alice's transaction and verify: (1) The signature is valid using Alice's public key, (2) Alice's account has at least 10.01 LUX (10 LUX + 0.01 LUX fee), (3) The nonce is 47, which is correct for Alice's next transaction, (4) The transaction format is valid. All checks pass, so the transaction enters the mempool.

## Mempool (Transaction Pool)

After verification, valid transactions wait in a temporary holding area:

**What Is the Mempool**:
- Short for "memory pool"—a collection of unconfirmed transactions stored in each node's RAM
- Each node maintains its own mempool (they may differ slightly due to network propagation times)
- Transactions wait here until a miner or validator includes them in a block

**Transaction Ordering in Mempool**:
Transactions are typically prioritized by:
- **Fee level**: Higher fees get priority (especially important during network congestion)
- **Time received**: Older transactions may get preference among same-fee transactions
- **Dependencies**: Some transactions must wait for others to be confirmed first

**Mempool Dynamics**:
- Size fluctuates based on network activity
- During high congestion, mempools grow large and low-fee transactions may wait hours or days
- Transactions can be evicted if mempool becomes too full (lowest-fee transactions removed first)
- Users can often replace pending transactions by resubmitting with higher fees (Replace-By-Fee)

**Example**:
Alice's transaction sits in the mempool of thousands of nodes. She offered a fee of 0.01 LUX, which is above the minimum required. The transaction will likely be included in the next block as validators select transactions to process.

## Consensus (Block Inclusion)

Validators select transactions from the mempool to include in the next block:

**Block Construction**:
1. The validator selects transactions from their mempool
2. Transactions are typically chosen by fee level and arrival time
3. The block has size or gas limits, so not all transactions can fit
4. The validator arranges transactions in order and creates a block

**Consensus Process**:
Different networks use different approaches:

In systems with Proof of Work:
- Block producers compete to solve a cryptographic puzzle
- First to solve it gets to propose their block
- Other nodes verify the solution and accept the block if valid
- Can take several minutes or even hours per block

In systems with Proof of Stake:
- Validators are selected (often based on their stake) to propose blocks
- Other validators attest that the block is valid
- Block is accepted once enough validators attest to it
- Can take seconds or minutes depending on implementation

**Block Reward**:
The validator who successfully adds the block typically receives:
- Block reward (newly created cryptocurrency, if applicable)
- All transaction fees from transactions in the block

**Example**:
A validator selects Alice's transaction along with hundreds of others and includes it in a block. Through the consensus process, the network validates and accepts the block. Alice's transaction now has 1 confirmation.

## Finalization

The final stage is when the transaction becomes permanently part of the blockchain:

**Confirmation Count**:
- **1 confirmation**: Transaction is in the most recent block
- **2 confirmations**: One additional block has been added after the block containing the transaction
- **6 confirmations**: Six blocks deep (generally considered secure in Bitcoin)
- **12+ confirmations**: Very secure, reversal extremely unlikely

**Why Multiple Confirmations Matter**:
- The deeper a transaction is in the blockchain, the harder it is to reverse
- To reverse a transaction with 6 confirmations, an attacker would need to remine 6 blocks faster than the honest network
- This becomes exponentially more difficult and expensive with each confirmation

**Finality Types**:

* **Probabilistic Finality** (PoW, longest-chain systems):
   - Never 100% final, but probability of reversal approaches zero
   - Each additional block makes reversal exponentially more difficult
   - Standard in Bitcoin, Ethereum (pre-merge), and similar systems

* **Absolute Finality** (Some PoS systems):
   - Once finalized, transactions are mathematically impossible to reverse
   - Used in systems with finality gadgets or BFT consensus
   - Provides faster economic certainty but may sacrifice some decentralization

**State Update**:
Once confirmed, the transaction's effects are reflected in the blockchain state:
- Sender's balance decreases by the amount plus fee
- Recipient's balance increases by the amount
- The nonce is incremented
- Smart contract state may be updated (if applicable)

**Example**:
A few seconds after being included in a block, Alice's transaction is considered final on Lux's LUExchange-Chain due to its fast-finality consensus. Bob's wallet now shows the 10 LUX as confirmed and available to spend. Alice's balance shows 10.01 LUX less than before (10 LUX transferred + 0.01 LUX fee). The transaction is complete and irreversible.

## Summary: Complete Lifecycle Visualization

```
1. CREATION
   User creates transaction
   ↓
2. SIGNING
   Wallet signs with private key
   ↓
3. BROADCASTING
   Propagates across P2P network
   ↓
4. VERIFICATION
   Nodes validate signature, balance, format
   ↓
5. MEMPOOL
   Waits in memory pool
   ↓
6. CONSENSUS
   Included in block by validator
   ↓
7. FINALIZATION
   Gains confirmations, becomes irreversible
```

## Key Takeaways

- **Creation**: User specifies transaction details in wallet software
- **Signing**: Private key cryptographically signs the transaction to prove authorization
- **Broadcasting**: Transaction propagates through P2P network in seconds
- **Verification**: Nodes check signature, balance, and format before accepting
- **Mempool**: Validated transactions wait to be included in a block
- **Consensus**: Miners/validators include transaction in a block through consensus mechanism
- **Finalization**: Additional blocks make transaction increasingly irreversible

Understanding this lifecycle helps explain why blockchain transactions take time (consensus process), why fees matter (mempool prioritization), and why multiple confirmations are recommended (finality assurance). Each step serves a crucial purpose in maintaining the security and integrity of the decentralized system.

<Quiz quizId="1003"/>

<Quiz quizId="1006"/>


# Signatures (/academy/blockchain/blockchain-fundamentals/04-signatures/01-signatures)

---
title: Signatures
description: Learn how digital signatures ensure transaction authenticity and security in blockchain systems through public-key cryptography. Understand the role of private and public keys in creating verifiable, tamper-proof transactions that maintain trust in decentralized networks.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

Digital signatures are a fundamental component of blockchain technology, providing the cryptographic foundation for secure, authentic, and tamper-proof transactions.

As handwritten signatures do, digital signatures enable users to prove their identity, authorize transactions or attest events.

## What Are Digital Signatures?

A **digital signature** is a cryptographic mechanism that ensures the authenticity, integrity, and non-repudiation of digital messages or transactions. Think of it as an electronic "fingerprint" that uniquely binds a transaction to its originator. Unlike physical signatures, digital signatures are mathematically generated and virtually impossible to forge.

In blockchain systems, every transaction must be signed by the sender to prove that they authorize the transfer of assets. This signature provides:

- **Authentication**: Confirms the identity of the transaction sender
- **Integrity**: Ensures the transaction data hasn't been altered
- **Non-repudiation**: Prevents the sender from denying they made the transaction

## How Digital Signatures Work

Digital signatures rely on **asymmetric cryptography**, which uses a pair of mathematically related keys:

### Key Pairs

1. **Private Key**: A secret key known only to the owner. This key is used to sign transactions and must be kept secure. If someone gains access to your private key, they can impersonate you and authorize transactions on your behalf.

2. **Public Key**: A publicly shared key derived from the private key. Anyone can use this key to verify signatures created by the corresponding private key. The public key serves as your address or identity on the blockchain.

These keys are mathematically linked in a special way: data signed with the private key can be verified using the public key, but the private key cannot be derived from the public key.

### The Signing Process

When a user wants to make a transaction on a blockchain:

1. **Create Transaction**: The user creates a transaction specifying details like the recipient's address and the amount to transfer.

2. **Sign Transaction**: The user's wallet software uses their private key to create a unique digital signature for this specific transaction. The signature is generated by applying a cryptographic algorithm (like ECDSA - Elliptic Curve Digital Signature Algorithm) to the transaction data and the private key.

3. **Broadcast**: The transaction, along with the digital signature and the user's public key, is broadcast to the network.

4. **Verification**: Network nodes receive the transaction and use the provided public key to verify the signature. This confirms that:
   - The transaction was signed by the holder of the private key corresponding to the public key
   - The transaction data hasn't been modified since it was signed

5. **Accept or Reject**: If the signature is valid, the transaction is accepted for inclusion in a block. If invalid, it's rejected.

## Why Digital Signatures Matter

Digital signatures solve several critical problems in decentralized systems:

### Ownership and Authorization

In traditional systems, a bank verifies your identity when you make a transaction. In a decentralized blockchain, there's no central authority to verify identity. Digital signatures provide a mathematical proof that the person initiating a transaction owns the account and authorizes the transfer.

### Tamper Detection

If anyone tries to modify a signed transaction—even by changing a single character—the signature becomes invalid. This makes it immediately obvious that the transaction has been tampered with, and network nodes will reject it.

### Privacy with Accountability

Digital signatures allow you to prove you own an account without revealing your private key. You can transact publicly while keeping your credentials private. Every transaction is traceable to a public key, but the identity behind that key can remain pseudonymous.

### Trustless Verification

Anyone can verify a signature using the public key without needing to trust a third party. This enables the trustless, peer-to-peer nature of blockchain networks where participants don't need to know or trust each other to transact safely.

## Common Signature Schemes

Different blockchains use different cryptographic algorithms for digital signatures:

- **ECDSA (Elliptic Curve Digital Signature Algorithm)**: provides strong security with relatively small key sizes, making it efficient for blockchain applications.

- **EdDSA (Edwards-curve Digital Signature Algorithm)**: alternative to ECDSA, offering improved performance and security properties.

- **BLS (Boneh-Lynn-Shacham) Signatures**: provide small sized signature aggregations to maintain security while saving space when multiple signatures are needed.

- **Schnorr Signatures**: enable more complex use cases like multi-signature transactions in a more efficient way.

## Security Considerations

The security of digital signatures depends entirely on keeping private keys secure:

- **Never share your private key**: Anyone with access to your private key can sign transactions as you
- **Use secure storage**: Store private keys in hardware wallets or secure software wallets
- **Backup carefully**: Lose your private key, and you lose access to your assets forever
- **Beware of phishing**: Never enter your private key on untrusted websites or applications

Digital signatures are the cornerstone of blockchain security, enabling trustless, verifiable transactions in a decentralized environment. Understanding how they work is essential to grasping how blockchains maintain security without central authorities.

<Quiz quizId="1001"/>

# Sybil Protection (/academy/blockchain/blockchain-fundamentals/05-sybil-protection/01-sybil-protection)

---
title: Sybil Protection
description: Understand Sybil attacks and how blockchain networks defend against fake identities attempting to gain disproportionate influence. Learn the crucial distinction between consensus mechanisms that order transactions and Sybil defense mechanisms that prevent identity manipulation.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

Decentralized networks face a unique challenge: how do you prevent a single malicious actor from creating thousands of fake identities to manipulate the system? This threat is known as a **Sybil attack**, and defending against it is critical for maintaining the security and fairness of blockchain networks.

## What Is a Sybil Attack?

A **Sybil attack** occurs when a single entity creates multiple fake identities (Sybil nodes) to gain disproportionate influence or control over a network. The name comes from a famous case study of a patient with dissociative identity disorder who had multiple personalities.

In a blockchain context, imagine if:

- One person could create 1,000 fake "validator" identities
- Each identity appears to be a different, independent participant
- Together, these fake identities control enough voting power to manipulate the network
- The attacker could approve fraudulent transactions, censor legitimate transactions, or even rewrite blockchain history

### Why Sybil Attacks Are Dangerous

In a decentralized network, decision-making power is supposed to be distributed among many independent participants. But if one entity can masquerade as many participants, they can:

1. **Manipulate Consensus**: Control which transactions are included in blocks or influence the order of transactions
2. **Launch 51% Attacks**: Gain majority control to double-spend or rewrite history
3. **Censor Transactions**: Prevent specific users or types of transactions from being processed
4. **Corrupt Voting**: In governance systems, vote multiple times on protocol changes
5. **Drain Resources**: Spam the network or monopolize scarce resources

The fundamental problem is that in a truly open, permissionless network, creating a new identity is essentially free—you can generate a new public/private key pair instantly at no cost.

## Sybil Defense Mechanisms

**Sybil defense mechanisms** (also called Sybil resistance) are strategies designed to make it expensive or impractical for an attacker to create multiple identities. The goal is to ensure that influence in the network is tied to something scarce and difficult to fake.

### Making Identity Creation Costly

The most common approach is to attach a real-world cost to each identity or vote in the system:

**Resource-Based Defenses:**

1. **Computational Resources**: Require identities to perform expensive computations (Proof of Work)
2. **Financial Resources**: Require identities to stake valuable assets (Proof of Stake)
3. **Physical Resources**: Require identities to control unique hardware or network capabilities
4. **Human Verification**: Require identities to prove they are unique human beings (Proof of Personhood)

The key principle is: if creating each identity requires spending something valuable and scarce, an attacker cannot create unlimited identities without unlimited resources.

## The Crucial Difference: Consensus vs. Sybil Defense

This is one of the most important distinctions in blockchain technology, and they're often confused because the same mechanisms serve both purposes. Let's clarify:

### Consensus Mechanisms

**Purpose**: Achieve agreement among network participants on the state of the blockchain

**What They Do**:
- Determine the order of transactions
- Decide which block to add to the blockchain next
- Ensure all honest nodes converge on the same history
- Resolve conflicts when multiple blocks are proposed simultaneously

**The Question They Answer**: "What is the correct state of the blockchain that we all agree on?"

### Sybil Defense Mechanisms

**Purpose**: Prevent a single entity from controlling multiple identities to gain disproportionate influence

**What They Do**:
- Make it expensive to create new identities
- Tie influence to scarce, real-world resources
- Ensure each participant's power is limited
- Prevent attackers from simulating a large number of network participants

**The Question They Answer**: "How do we ensure that each identity in the network represents a truly independent entity?"

## Real-World Example: Bitcoin

Bitcoin uses Proof of Work:

**Consensus Role**:
- Miners compete to find valid blocks
- The network follows the longest valid chain
- This ensures all nodes agree on transaction history

**Sybil Defense Role**:
- Creating 100 fake miner identities doesn't give you more power
- What matters is computational power (hash rate), not number of identities
- To control the network, you need 51% of total hash rate, which requires massive investment in hardware and electricity
- This makes Sybil attacks prohibitively expensive

## Why Both Are Necessary

You need both consensus mechanisms AND Sybil defense for a secure blockchain:

**Without Consensus**: Nodes wouldn't agree on the transaction order or blockchain state, leading to fragmentation and inconsistency.

**Without Sybil Defense**: An attacker could create unlimited fake identities to manipulate the consensus process, undermining the entire system.

Think of it this way:
- **Sybil Defense** ensures the participants are legitimate and their influence is fair
- **Consensus Mechanisms** use these legitimate participants to agree on the blockchain state

Together, they create a system where decentralized coordination is possible without trusted authorities, and where influence is earned through real-world resources rather than granted freely to anyone who creates an account.

The choice of Sybil defense mechanism fundamentally shapes the security model, accessibility, and decentralization characteristics of a blockchain network.

<Quiz quizId="1004"/>

# Smart Contracts (/academy/blockchain/blockchain-fundamentals/06-smart-contracts/01-smart-contracts)

---
title: Smart Contracts
description: Discover how smart contracts revolutionize digital agreements by automatically executing code when conditions are met. Learn how these self-enforcing programs enable decentralized applications, eliminate intermediaries, and create trustless systems on blockchain networks.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

Blockchains began as systems for recording and transferring digital currency, but they evolved into something much more powerful: platforms for running code. **Smart contracts** are self-executing programs that run on blockchains, automatically enforcing agreements without intermediaries. They represent one of the most transformative applications of blockchain technology.

## What Are Smart Contracts?

A **smart contract** is a program stored on a blockchain that automatically executes when predetermined conditions are met. Think of it as a digital agreement written in code rather than legal language, where the blockchain automatically enforces the terms without requiring trust in any person or institution.

### Traditional Contracts vs. Smart Contracts

**Traditional Contract:**
- Written in legal language
- Requires trusted intermediaries (lawyers, courts, escrow services) to enforce
- Enforcement can be slow, expensive, and subjective
- Parties must trust the legal system to be fair

**Smart Contract:**
- Written in programming code
- Automatically enforced by the blockchain network
- Execution is immediate and deterministic
- No need to trust intermediaries—the code and blockchain guarantee execution

## How Smart Contracts Work

Smart contracts are deployed on blockchain platforms that support programmable logic, with Ethereum being the most well-known example and Lux being out favorite one ;).

### The Basic Process

1. **Write the Code**: A developer writes a smart contract in a programming language. The contract defines:
   - The conditions that must be met
   - The actions to take when conditions are satisfied
   - The data the contract stores and manages

2. **Deploy to Blockchain**: The compiled contract is deployed to the blockchain by submitting a special transaction. Once deployed:
   - The contract gets a unique address on the blockchain
   - The code becomes permanent and immutable
   - Anyone can interact with the contract at its address

3. **Interact with the Contract**: Users send transactions to the contract's address to:
   - Call functions defined in the contract
   - Send cryptocurrency or tokens to the contract
   - Read data stored in the contract
   - Trigger the contract's automatic behaviors

4. **Automatic Execution**: When someone interacts with the contract:
   - Every node on the network executes the contract code
   - The contract's logic determines what happens (transfer funds, update data, etc.)
   - All nodes reach consensus on the outcome
   - The blockchain records the state changes

### Key Characteristics

**Deterministic**: Given the same inputs and blockchain state, the contract always produces the same outputs. There's no randomness or external influence.

**Autonomous**: Once deployed, the contract runs exactly as programmed without human intervention. No one can stop it or change how it behaves.

**Transparent**: The contract's code and its current state are visible to everyone on the blockchain. Anyone can verify what it does and audit its behavior.

**Immutable**: After deployment, the contract's code cannot be changed. This ensures that the rules can't be altered after people start using it.

**Trustless**: Users don't need to trust the contract creator or any third party—they only need to trust that the code does what it says (which they can verify) and that the blockchain will execute it correctly.

## Real-World Applications

Smart contracts enable a vast ecosystem of decentralized applications (dApps) across many domains:

### Decentralized Finance (DeFi)

DeFi uses smart contracts to recreate traditional financial services without banks or brokers:

- **Lending Protocols**: Automatically lend cryptocurrency and calculate interest in real-time
- **Decentralized Exchanges**: Trade tokens directly with others without a centralized exchange
- **Stablecoins**: Maintain stable cryptocurrency values through algorithmic smart contracts
- **Yield Farming**: Automatically optimize returns across multiple platforms

### Non-Fungible Tokens (NFTs)

Smart contracts power the creation, ownership, and trading of unique digital assets:

- Prove ownership of digital art, collectibles, or virtual items
- Automatically pay royalties to creators on secondary sales
- Enable fractional ownership of high-value assets

### Supply Chain Management

Track goods as they move through complex supply chains:

- Record each step in a product's journey automatically
- Verify authenticity and prevent counterfeits
- Trigger payments automatically

### Decentralized Autonomous Organizations (DAOs)

Organizations governed entirely by smart contracts:

- Members vote on proposals using tokens
- Approved proposals execute automatically
- Treasury funds are managed transparently by code

### Gaming and Virtual Worlds

Enable true ownership and interoperability of digital items:

- Players truly own their in-game items as tokens
- Items can be traded or used across different games
- Game economies run on transparent, automated smart contracts

### Insurance

Automate claims processing and payouts:

- Parametric insurance that pays out automatically based on data (e.g., weather data for crop insurance)
- No claims adjusters needed for straightforward cases
- Faster payouts with lower overhead

## A Detailed Example: Token Swap

Let's walk through how a smart contract enables a trustless cryptocurrency exchange:

**Scenario**: Alice has 100 LUX and wants to trade it for Bob's 2,000 USDC. Neither party trusts the other.

**Traditional Solution**: Use a centralized exchange to facilitate the trade. Both parties must trust the exchange to handle their funds honestly and not freeze accounts.

**Smart Contract Solution**:

```solidity
contract TokenSwap {
    address public alice;
    address public bob;
    uint256 public luxAmount;
    uint256 public usdcAmount;
    bool public aliceDeposited;
    bool public bobDeposited;
    uint256 public deadline;
    
    IERC20 public usdcToken;
    
    // Alice creates the swap offer
    constructor(address _bob, uint256 _usdcAmount, address _usdcToken) payable {
        alice = msg.sender;
        bob = _bob;
        luxAmount = msg.value;  // Alice deposits LUX
        usdcAmount = _usdcAmount;
        usdcToken = IERC20(_usdcToken);
        aliceDeposited = true;
        deadline = block.timestamp + 1 hours;  // 1 hour to complete
    }
    
    // Bob deposits his USDC to complete the swap
    function depositUSDC() public {
        require(msg.sender == bob, "Only Bob can deposit");
        require(block.timestamp < deadline, "Swap expired");
        
        usdcToken.transferFrom(bob, address(this), usdcAmount);
        bobDeposited = true;
        
        // Automatically execute the swap
        executeSwap();
    }
    
    // Execute the swap once both have deposited
    function executeSwap() private {
        require(aliceDeposited && bobDeposited, "Both must deposit");
        
        // Send LUX to Bob
        payable(bob).transfer(luxAmount);
        
        // Send USDC to Alice
        usdcToken.transfer(alice, usdcAmount);
    }
    
    // If Bob doesn't deposit before deadline, Alice gets her LUX back
    function refund() public {
        require(block.timestamp >= deadline, "Deadline not reached");
        require(!bobDeposited, "Swap already completed");
        
        payable(alice).transfer(luxAmount);
    }
}
```

**How It Works**:

1. Alice creates the swap contract, specifying Bob's address and the amount of USDC she wants
2. Alice sends 100 LUX to the contract when creating it
3. Bob has 1 hour to deposit 2,000 USDC into the contract
4. **If Bob deposits**: The contract automatically swaps—Bob gets the LUX, Alice gets the USDC
5. **If Bob doesn't deposit**: After the deadline, Alice can call `refund()` to get her LUX back

This is truly trustless! Neither Alice nor Bob can cheat because:
- Alice can't take back her LUX once Bob deposits (the swap executes automatically)
- Bob can't get the LUX without depositing his USDC
- If Bob doesn't participate, Alice simply gets her funds back
- No centralized exchange can freeze, confiscate, or misuse the funds, they are just put on a contract that can't do anything other than executing the swap with them.
- The swap is atomic: either both sides happen, or neither happens

## Challenges and Limitations

While powerful, smart contracts face several challenges:

### Security Vulnerabilities

**The Problem**: Bugs in smart contract code can be exploited. Because contracts are immutable, bugs can't be fixed after deployment.

**Famous Example**: The DAO hack in 2016 resulted in $50 million stolen due to a reentrancy vulnerability.

**Solution**: Rigorous testing, professional audits, formal verification, and secure coding patterns.

### Oracle Problem

**The Problem**: Smart contracts can't access external data (weather, stock prices, sports scores) on their own. They need "oracles" to feed them real-world information.

**Challenge**: Oracles reintroduce trust and potential points of failure into the system.

**Solution**: Decentralized oracle networks that aggregate data from multiple sources.

### Legal Uncertainty

**The Problem**: The legal status of smart contracts is unclear in many jurisdictions. What happens when code conflicts with law?

**Challenge**: Dispute resolution and liability are not always clear.

**Evolution**: Legal frameworks are gradually adapting to recognize smart contracts.

### Immutability Double-Edged Sword

**Benefit**: No one can change the rules

**Risk**: No way to fix bugs or upgrade functionality

**Solutions**: Upgradeable contract patterns or designing migration paths into new contracts.

## The Future of Smart Contracts

Smart contracts are still evolving, with exciting developments on the horizon:

- **New Languages**: Enabling more complex logic and safer programming
- **Cross-Chain Contracts**: Contracts that operate across multiple blockchains
- **Formal Verification**: Mathematical proofs that contracts behave correctly
- **Privacy-Preserving Contracts**: Using zero-knowledge proofs to execute contracts privately

Smart contracts represent a fundamental shift in how we create and enforce agreements. By removing intermediaries and automating execution, they enable new forms of trust, coordination, and economic activity that were previously impossible. As the technology matures, smart contracts are poised to reshape industries from finance to governance to entertainment, creating a more automated, transparent, and accessible digital economy.

## Key Takeaways

- Smart contracts are self-executing programs on blockchains that automatically enforce agreements
- They eliminate the need for trusted intermediaries in many situations
- Once deployed, they are immutable, transparent, and execute deterministically
- They enable decentralized applications across finance, gaming, supply chain, and more
- While powerful, they require careful design to avoid security vulnerabilities

Understanding smart contracts is essential for anyone looking to build on or understand modern blockchain platforms. They're the foundation of the decentralized application ecosystem and represent one of blockchain technology's most significant innovations beyond simple currency.

<Quiz quizId="1005"/>


# Native Tokens (/academy/blockchain/blockchain-fundamentals/07-independent-tokenomics/01-native-tokens)

---
title: Native Tokens
description: Learn about native tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

A **native token** in a blockchain running the Ethereum Virtual Machine (EVM) refers to the primary digital currency or cryptocurrency native to that blockchain. Native tokens act as the foundation for value transfer and network operation within their respective ecosystems.

- **Ethereum**: ETH
- **Lux LUExchange-Chain**: LUX
- **Dexalot**: ALOT
- many more...

---

### The Role of Native Tokens

Native tokens serve multiple key roles within EVM-based blockchain networks, such as:

- **Value Transfer**: Native tokens act as the primary currency for peer-to-peer transactions within the network, enabling value exchange between participants.
- **Gas Fees**: Native tokens are used as **gas** to pay for transaction fees, contract deployments, and other network operations. This ensures that resources are allocated efficiently within the network.
- **Security**: In Proof-of-Stake (PoS) networks, native tokens are often used for staking to secure the network and validate transactions.
- **Governance**: In some cases, native tokens grant holders governance rights, allowing them to participate in decision-making processes that shape the blockchain’s future.

---

Native tokens are the backbone of blockchain ecosystems, serving multiple roles that maintain the network's stability, security, and functionality.

# ERC-20 Tokens (/academy/blockchain/blockchain-fundamentals/07-independent-tokenomics/02-erc-20-tokens)

---
title: ERC-20 Tokens
description: Learn about ERC-20 tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

While a blockchain has a single **native token**, the **ERC-20** token standard was developed to allow for the representation of a wide range of assets on EVM-compatible chains. 

**ERC** stands for **Ethereum Request for Comment**, and **20** is the identifier for the specific proposal that defines the standard.

ERC-20 tokens are **fungible**, meaning each token is identical to another and can be exchanged on a one-to-one basis. These tokens are created and managed through smart contracts that adhere to the ERC-20 standard, ensuring interoperability between different tokens and decentralized applications (DApps).

---

### ERC-20 Token Architecture

At the core of every ERC-20 token is a simple **mapping** of addresses to balances, representing the number of tokens an address holds.

```solidity
abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
    
  mapping(address account => uint256) private _balances;
  
  //...
}
```

Addresses holding ERC-20 tokens can belong to either **Externally Owned Accounts (EOAs)** or **smart contracts**. Both types of accounts can store and transfer ERC-20 tokens, making ERC-20 tokens versatile in decentralized finance (DeFi) and decentralized applications.

---

### Role of ERC-20 Tokens in Blockchain Ecosystems

ERC-20 tokens play an essential role in enabling the creation of decentralized applications with various functionalities:

- **Tokenized Assets**: ERC-20 tokens can represent anything from digital currencies to tokenized real-world assets.
- **DeFi Protocols**: Many DeFi protocols use ERC-20 tokens for lending, staking, and liquidity pools.
- **Token Sales**: ICOs (Initial Coin Offerings) and other fundraising models rely heavily on ERC-20 tokens.

---

### The ERC-20 Interface

All ERC-20 tokens follow a standard interface to ensure compatibility with decentralized applications (DApps). This allows tokens to be easily transferred, approved for spending, and managed by any DApp that follows the same rules.

```solidity
interface IERC20 {
    function name() external view returns (string memory);

    function symbol() external view returns (string memory);

    function decimals() external view returns (uint8);

    function totalSupply() external view returns (uint256);

    function balanceOf(address _owner) external view returns (uint256 balance);

    function transfer(address _to, uint256 _value) external returns (bool success);

    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);

    function approve(address _spender, uint256 _value) external returns (bool success);

    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```

You can review the full **ERC-20 standard** [here](https://eips.ethereum.org/EIPS/eip-20).

---

### Transferring ERC-20 Tokens

To transfer ERC-20 tokens between accounts, you use the `transfer()` function, where the sender specifies the recipient’s address and the amount to be transferred.

For more complex interactions, such as allowing a smart contract to transfer tokens on behalf of someone else, the ERC-20 standard includes the `approve()` and `transferFrom()` functions. 


<Accordions>
<Accordion title="transfer()">
Transfers tokens from the sender’s account to another account, decreasing the sender's balance and increasing the recipient’s.
</Accordion>
<Accordion title="approve()">
This function allows the owner of a token balance to approve another account (the **spender**) to withdraw up to a specified amount of tokens. The spender can withdraw from the owner's balance multiple times, as long as the total amount doesn’t exceed the approved limit.
</Accordion>
<Accordion title="allowance()">
The `allowance()` function returns the amount that a spender is still allowed to withdraw from an owner's balance.
</Accordion>
<Accordion title="transferFrom()">
This function facilitates the transfer of tokens from one account to another on behalf of the account owner. It is typically used in scenarios where smart contracts need to execute token transfers according to the contract's logic.
</Accordion>
</Accordions>

---

ERC-20 tokens revolutionized the blockchain space by enabling the tokenization of assets and simplifying the creation of decentralized applications. Their standardization ensures compatibility across platforms and DApps, making them an integral part of the broader crypto ecosystem.

# Deploy and Transfer an ERC-20 Token (/academy/blockchain/blockchain-fundamentals/07-independent-tokenomics/03-deploy-and-transfer-erc-20-tokens)

---
title: Deploy and Transfer an ERC-20 Token
description: Learn how to deploy an ERC-20 token and transfer it between accounts.
updated: 2024-09-03
authors: [0xstt]
icon: Terminal
---

In this section, you will follow a step-by-step guide to deploy an ERC-20 token on a blockchain network and transfer it between accounts. This will provide practical experience with token creation, deployment, and handling transactions.

### Objectives:
- Deploy an ERC-20 token smart contract.
- Interact with your token by transferring it between different accounts.

To learn how to deploy an ERC-20 token and interact with your token on a blockchain, follow [this guide](/academy/interchain-token-transfer/03-tokens/08-transfer-an-erc-20-token) to explore the deployment process using the CLI on our Lux L1.

<Quiz quizId="201"/>


# Wrapped Native Tokens (/academy/blockchain/blockchain-fundamentals/07-independent-tokenomics/04-wrapped-tokens)

---
title: Wrapped Native Tokens
description: Learn about wrapped tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

**Wrapped tokens** are blockchain assets that represent a native cryptocurrency (e.g., LUX, ALOT, ETH) in a tokenized form, typically conforming to the **ERC-20 token standard**. Wrapping a native token allows it to be used in decentralized applications (dApps) and protocols that require ERC-20 tokens.

---

### What Are Wrapped Tokens?

Wrapped tokens are created through a process where the native cryptocurrency is locked in a smart contract, and an equivalent amount of the wrapped token is minted. These wrapped tokens are backed 1:1 by the underlying native asset, ensuring that the value of the wrapped token mirrors that of the original native cryptocurrency.

This **ERC-20 compatibility** is crucial for enabling the native asset to interact with dApps, decentralized exchanges (DEXs), and smart contracts within the EVM ecosystem, where ERC-20 tokens are the standard.

---

### Why Are Wrapped Tokens Important?

Wrapped tokens play an essential role in **interoperability** within the EVM ecosystem, facilitating seamless use across decentralized applications and protocols. Some key benefits include:

- **Liquidity**: Wrapped tokens increase liquidity in DeFi by enabling users to participate in protocols that require ERC-20 tokens, even when their original asset is a native token.
- **Cross-Chain Compatibility**: Wrapped tokens allow assets from one blockchain (e.g., Bitcoin) to be used on another chain, enhancing cross-chain functionality.
- **DeFi Integration**: Wrapped tokens are vital in DeFi protocols such as lending, borrowing, staking, and liquidity pools, where ERC-20 tokens are the standard.

---

### Wrapped Token Contract Interface

A **wrapped token contract** is typically an implementation of the ERC-20 token standard, with added functions for minting and burning tokens to facilitate the wrapping and unwrapping process. Here's a basic contract interface for a wrapped token:

```solidity
interface IWrappedToken {
    function deposit() external payable;
    function withdraw(uint256 amount) external;
    
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
}
```

<Accordions>
<Accordion title="deposit()">
This function is used to wrap native tokens. When a user calls deposit(), they send the native cryptocurrency (e.g., LUX, ETH) to the contract, which then mints an equivalent amount of the wrapped token.
</Accordion>
<Accordion title="withdraw()">
This function is used to unwrap the tokens. It burns the specified amount of wrapped tokens and returns the equivalent amount of native cryptocurrency to the user.
</Accordion>
</Accordions>

# Deploy and Interact with Wrapped Token (/academy/blockchain/blockchain-fundamentals/07-independent-tokenomics/05-deploy-and-interact-wrapped-tokens)

---
title: Deploy and Interact with Wrapped Token
description: Learn how to deploy and interact with wrapped tokens
updated: 2024-09-03
authors: [0xstt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, we will deploy and interact with a wrapped token using **Forge** and **cast** commands. Forge simplifies smart contract deployment, and cast allows you to interact with deployed contracts.

---

<Steps>
<Step>

#### 1. Write the Wrapped Token Contract
Here is a basic implementation of a wrapped token contract in Solidity:

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

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract WrappedToken is ERC20 {
    address public nativeTokenHolder;

    constructor() ERC20("Wrapped Token", "WTKN") {}

    function deposit() external payable {
        _mint(msg.sender, msg.value);
        nativeTokenHolder = msg.sender;
    }

    function withdraw(uint256 amount) external {
        _burn(msg.sender, amount);
        payable(msg.sender).transfer(amount);
    }
}
```

</Step>
<Step>

### Deploy ERC20 Receiver
Deploy the Contract Using Forge's `create` Command

```bash
forge create --rpc-url myblockchain --private-key $PK WrappedToken.sol:WrappedToken --broadcast
```

</Step>

<Step>

### Save the Wrapped Token Address

Save the `Deployed to` address in an environment variable.

```bash
export WRAPPED_TOKEN=<address>
```

</Step>

<Step>

### Interacting with the Deployed Contract

Once the contract is deployed, you can interact with it using **cast** commands.


<Accordions>
<Accordion title="Depositing Native Tokens (Wrapping)">

To deposit native tokens and mint wrapped tokens, use the following `cast send` command:

```bash
cast send $WRAPPED_TOKEN "deposit()" --value <AMOUNT> --rpc-url myblockchain --private-key $PK
```

- `<AMOUNT>`: The amount of native tokens you want to wrap (in wei).
</Accordion>
<Accordion title="Withdrawing Native Tokens (Unwrapping)">

To burn the wrapped tokens and retrieve the equivalent amount of native tokens:

```bash
cast send $WRAPPED_TOKEN "withdraw(uint256)" <AMOUNT> --rpc-url myblockchain --private-key $PK
```

- `<AMOUNT>`: The number of wrapped tokens to burn and convert back to native tokens.
</Accordion>
</Accordions>

You can use the following page for [**wei conversions**](https://snowtrace.io/unitconverter).

</Step>

</Steps>

<Quiz quizId="202"/>

# Token Decimals (/academy/blockchain/blockchain-fundamentals/07-independent-tokenomics/06-token-decimals)

---
title: Token Decimals
description: Learn about token decimals and their impact on blockchain applications.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

**Token decimals** refer to the level of precision used to define a token’s smallest unit. When a token contract is created, the number of decimals is specified to determine how divisible the token will be. This can have significant implications for user experience, application development, and overall token functionality.

For example:
- **6 decimals**: A token with 6 decimals means the smallest unit is 0.000001.
- **18 decimals**: A token with 18 decimals means the smallest unit is 0.000000000000000001.

---

### Why Are Token Decimals Important?

Token decimals are critical because they determine how small a fraction of the token can be used in transactions. The choice of decimals directly affects how the token is used in various applications, including decentralized finance (DeFi), payments, and staking.

- **Greater Precision**: More decimals allow for finer divisions of the token, which is useful in systems where very small amounts of a token need to be handled (e.g., high-frequency trading, micro-payments, or rewards distribution).
- **User Perception**: The number of decimals can also influence how users perceive the value of the token. A token with fewer decimals might appear more “whole,” making it seem like larger amounts are being used in transactions.

---

**Conclusion**: Token decimals are a fundamental aspect of token design. Choosing the right number of decimals depends on the token's use case, balancing the need for precision with user experience and technical requirements.

# Virtual Machines and Blockchains (/academy/blockchain/blockchain-fundamentals/08-vms-and-blockchains/01-vms-and-blockchains)

---
title: Virtual Machines and Blockchains
description: Learn about Virtual Machines.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="b-slW7w65VQ" />

Virtual Machines are defining the behaviour of a blockchain. They can be the execution environment for smart contracts and decentralized applications. In this section, you will learn about the Virtual Machines used in Lux.

## What You Will Learn

In this section, you will go through the following topics:

- **State Machine:** Understand what a State Machine is and how it works
- **Blockchain:** Learn about the role of VMs in blockchains
- **Variety of VMs:** Learn how Lux supports different VMs

# What is a State Machine? (/academy/blockchain/blockchain-fundamentals/08-vms-and-blockchains/02-state-machine)

---
title: What is a State Machine?
description: Learn about the State Machines in blockchain systems.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

A virtual machine in the context of a blockchain system is like a decentralized computer that can execute a program in a controlled environment. A Virtual Machine (VM) defines the application-level logic of a blockchain. In technical terms, it specifies the blockchain’s state, state transition function, transactions, and the API through which users can interact with the blockchain.

When you write a VM, you don't need to concern yourself with lower-level logic like networking, consensus, and blockchain structure. Lux does this behind the scenes, so you can focus on building.

The most popular VM in blockchain is the Ethereum Virtual Machine (EVM) used in the Ethereum blockchain and others. It enables the creation and execution of smart contracts. However, blockchain systems are not limited to the EVM and many blockchains operate with different virtual machines today. For instance, Solana and Cardano use completely different Virtual Machines.

## Soda Dispenser: A Simple Machine

To better comprehend Virtual Machines, take this analogy of a simple, everyday machine: a soda dispenser. 

For optimal functionality, this machine must **consistently monitor its state**. In this instance, the state may represent the current balance, total revenue, and the number of cans available per brand.



<Quiz quizId="109"/>

This dispenser permits several **operations**, such as:
- Inserting coins
- Selecting a soda flavor

User operations trigger **state transitions**. For example, when a user inserts a coin, the balance increases. Selecting a soda brand leads to a decrease of the balance by the soda's price and reduces the quantity of that specific brand by one. 

<Quiz quizId="110"/>

Additionally, certain logic might be incorporated to dictate various operational outcomes based on the current state. For example, the machine checks if the balance is sufficient when a user chooses a soda brand. As a result, the outcome could be different in cases where the balance is adequate compared to instances where it isn't.


## Advantages of VMs

Implementing state machines comes with several advantages:

**Clear Interface:** The range of operations provides clarity on how to interact with it. Once familiarized with the interface, you can interact with all soda machines (following the same blueprint) in the same manner.

**Reproducibility:** With a Virtual Machine blueprint, one can create multiple identical instances. These behave consistently, implying that if you conduct the same operations in the same sequence on two different machines, the state will remain identical.

<Quiz quizId="111"/>

# Blockchains (/academy/blockchain/blockchain-fundamentals/08-vms-and-blockchains/03-blockchains)

---
title: Blockchains
description: Learn about how VMs work in blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Let’s look at how VMs work in blockchain. Each validator operates an instance of our hypothetical soda dispenser. So, they have their own instance of a machine running on their server. They do this so they do not have to trust a single party with the operation of a soda dispenser,  and to make it easy for everyone to verify the outcome of operations.

When a user wishes to execute an operation on this distributed soda dispenser, they transmit the transaction to the network. The validators then reach consensus on the sequence in which transactions are carried out. In Lux, validators use Lux Consensus, which we talked about earlier.

<Quiz quizId="112"/>

Next, each validator executes the operation on their instance of the VM independently. Because each instance of our Virtual Machine behaves identically, validators maintain a uniform view of the machine’s state, so they balance and the number of available soda per flavor.



Subsequently, each validator executes the operation on their instance independently. Again, because each instance behaves identically, validators maintain a uniform view of the system's state, encompassing balance and available soda quantities. 

Let’s take the example further. Assume we have 100 validators in our Soda Dispenser Lux L1. I submit multiple operations to the validators:

- Insert a quarter
- A little while later, I Insert another quarter
- Choose lemonade

Each of the validators executes the operations on their own machine. After the first quarter the state of the machine states that the balance is 25 cents. After the second operation the balance is 50 cents. After choosing lemonade, the balance goes back to zero and the amount of available lemonades decreases from 8 to 7 on each instance running on each validators server.

This is the fundamental principle of Blockchains in Lux: A collective of validators operate identical virtual machines, come to consensus on the order of transactions, execute them, and have a uniform view on the machine's current state.

<Quiz quizId="113"/>

# Variety of Virtual Machines (/academy/blockchain/blockchain-fundamentals/08-vms-and-blockchains/04-variety-of-vm)

---
title: Variety of Virtual Machines
description: Learn about different types of Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

We can take this concept even further: The same network of validators can run two or more blockchains. These could operate different VMs, like a soda dispenser and a candy dispenser, or identical VMs, like two soda dispensers. When a user wants to issue an operation, they specify which blockchain to interact with.



You can think of a Virtual Machine (VM) as a blueprint for a blockchain, where the same VM can create multiple blockchains, each adhering to the same rules but remaining logically independent from the others. 

Even though two blockchains may use the same virtual machine, they each have an independent state. As an example, it could be the case that in one soda dispenser, a user has a credit of 1 dollar to their name while in the other soda dispenser, they do not have any credits to their name.



The number of blockchains a validator can validate is primarily limited by the additional computational resources required to operate the virtual machines of all the chains.

<Quiz quizId="114"/>

# Why Test Networks Like Testnet Exist — and Who They're For (/academy/blockchain/blockchain-fundamentals/08-vms-and-blockchains/05-testnets)

---
title: Why Test Networks Like Testnet Exist — and Who They're For
description: Test networks, or testnets, play a critical role in the lifecycle of blockchain development. Testnet, Lux's public test network, exists to give developers a safe, low-stakes environment to build, experiment, and validate before deploying to Mainnet.
date: 2025-01-09
authors: [meagfitzgerald]
topics: [Testnets, Testnet Testnet, Lux Testnet, Testnet Tokens, Testnet Faucet]
comments: true
---

Test networks, or *testnets*, play a critical role in the lifecycle of blockchain development. Testnet, Lux's public test network, exists to give developers a safe, low-stakes environment to build, experiment, and validate before deploying to Mainnet.

## Why Testnets Matter

Testnets mirror the functionality of the main network but use valueless tokens and non-production infrastructure. This setup lets developers test smart contracts, infrastructure updates, or protocol-level features without risking real assets or network stability.

They're where bugs are caught, upgrades are trialed, and new ideas are validated — all without consequences to real-world users.

## Who Should Use Testnet

Testnet is ideal for:

* Developers building or testing dApps, tooling, or validators before Mainnet deployment.
* Integrators validating compatibility with Lux APIs, SDKs, or network changes.
* Researchers and educators experimenting with network parameters or teaching blockchain fundamentals.

## Who Shouldn't Use Testnet

Testnet should not be used for:

* Any production-grade systems or client-facing environments.
* Workloads that require high uptime or data persistence.
* Situations where service reliability is critical — because testnets, by design, may be reset, upgraded, or experience downtime without notice.

## The Takeaway

Testnet is where innovation happens first — but not where reliability is guaranteed. It's a proving ground for what's next on Lux. Once your application, validator, or integration is stable and tested, Mainnet is the place to go live.

## Resources

- [Get Testnet Testnet tokens](https://build.lux.network/console/primary-network/faucet)
- [View the Testnet Testnet explorer](https://subnets-test.lux.network/)


# Regulation (/academy/blockchain/blockchain-fundamentals/xx-regulation/01-regulation)

---
title: Regulation
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---


# Proof of Work (/academy/blockchain/blockchain-fundamentals/xx-tbd-sections/02-proof-of-work)

---
title: Proof of Work
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

TBD

# Proof of Stake (/academy/blockchain/blockchain-fundamentals/xx-tbd-sections/03-proof-of-stake)

---
title: Proof of Stake
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

- Carrots and Sticks

## Staking Rewards

- Carrot

## Slashing

- Stick

# Signature Schemes (/academy/blockchain/blockchain-fundamentals/xx-tbd-sections/xx-signature-schemes)

---
title: Signature Schemes
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: Notebook
---

While transactions on ledgers in the analogue world were often authorized by hand-written signatures, that is not going to work for the adoption in blockchain. To utilize the concept of a ledger in the modern age, we leverage cryptography instead. 

import SignatureSchemes from "@/content/common/cryptography/signature-schemes.mdx"

import defaultMdxComponents from "fumadocs-ui/mdx";

<SignatureSchemes components={defaultMdxComponents}/>

# Lux Starter Kit (/academy/blockchain/solidity-foundry/02-avalanche-starter-kit/01-avalanche-starter-kit)

---
title: Lux Starter Kit
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

To make easier your journey through this course, we have prepared a Starter Kit repo consisting of everything you will need to start developing your own dApps on Lux. This repo will provide a self-contained environment with Lux-CLI, and Foundry so you can follow the course without the need of installing anything else other than launching the environment.

## What You Will Learn

In this section, you will go through the following topics:

- How to launch and manage your own Codespace
- How to create your own Interchain Messaging Enabled Custom Blockchain

At the end of this section, you will have your environment ready to create smart contracts.

# Set Up Lux Starter Kit (/academy/blockchain/solidity-foundry/02-avalanche-starter-kit/02-set-up)

---
title: Set Up Lux Starter Kit
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SetUp from "@/content/common/lux-starter-kit/set-up.mdx";

<SetUp />

# Close and Reopen Codespace (/academy/blockchain/solidity-foundry/02-avalanche-starter-kit/03-close-and-reopen-codespace)

---
title: Close and Reopen Codespace
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CloseAndReopen from "@/content/common/codespaces/close-and-reopen-codespace.mdx";

<CloseAndReopen />

# Create a Blockchain (/academy/blockchain/solidity-foundry/02-avalanche-starter-kit/03-create-blockchain)

---
title: Create a Blockchain
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CreateDefaultBlockchain from "@/content/common/lux-starter-kit/create-default-blockchain.mdx";

In order to send messages between two chains, we need to create a blockchain. In this guide, we will spin up a local Lux network that has it's own Primary Network (C-, P- and Exchange-Chain) using the Lux CLI. Furthermore, we will create a blockchain in that Lux network, so we can send messages between the LUExchange-Chain and the newly created blockchain in the next chapters.

<CreateDefaultBlockchain/>

# Networks (/academy/blockchain/solidity-foundry/02-avalanche-starter-kit/04-networks)

---
title: Networks
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import Networks from "@/content/common/lux-starter-kit/networks.mdx";

You just deployed and interacted with your first local network. But what does that mean? You can interact with your Lux L1, but you will notice that no one else can. Therefore, we have to understand what different Networks are in Lux.

<Networks/>

# Pause and Resume (/academy/blockchain/solidity-foundry/02-avalanche-starter-kit/05-pause-and-resume)

---
title: Pause and Resume
description: If you've deployed an Lux L1, you can preserve and restore the state of your deployed Lux L1s.
updated: 2024-10-07
authors: [0xstt]
icon: BookOpen
---

import PauseAndResume from "@/content/common/lux-starter-kit/pause-and-resume.mdx";

<PauseAndResume />


# Building Programs on Blockchain (/academy/blockchain/solidity-foundry/03-smart-contracts/01-building-programs-on-blockchain)

---
title: Building Programs on Blockchain
description: Learn what a Smart Contract is
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Book
---

First off, thank you for enrolling in this course! We assume that you are taking this course in order to learn how to write smart contracts. This begs the question - what are smart contracts?

From a high-level, you may have heard that smart contracts are just code that automate a process. Want to create a decentralized insurance protocol? You can build a smart contract for that. Want to create and distribute NFTs? You can also build a smart contract for that as well. So while we might understand the capabilities of a smart contract, this course will be focused on defining the actual code (and therefore, business logic) required for such intents.

## The EVM Model
In this course, we will learn Solidity, a high-level programming language that we will use to design smart contracts. Before we delve into learning Solidity, it is important to understand how our smart contracts operate in the grand scheme of things.

Smart contracts are defined by the following: their behaviors and their state. Focusing first on the behaviors of a smart contract, this is simply the functions that one can call on the smart contracts. Examples of such behaviors can be found below:

- __Tokens__: behaviors include creating tokens, transferring them, getting the balances of token holders
- __Decentralized Exchange__: behaviors include swapping tokens, adding liquidity to a pool, getting the adresses of both tokens of a liquidity pools
- __DAO__: behaviors include submitting a proposal, voting on a proposal, checking if someone is a governance member

We now focus on the state of a contract. Abstractly, we can define the state of a contract as being the values and stateful data structures that are associated with said contract. Examples of the state of a smart contract are listed below:

- __Tokens__: the name of the token, the symbol of the token, the balances of the users
- __Decentralized Exchange__: the number of tokens of a liquidity pool, the amount of tokens a liquidity provider is entitled to
- __DAO__: a list of all governance members, a list of all outstanding proposals

Understanding what a smart contract under the EVM model consists of, we are now ready to understand the relationship between Solidity and the underlying blockchain.

# What is Solidity (/academy/blockchain/solidity-foundry/03-smart-contracts/02-what-is-solidity)

---
title: What is Solidity
description: Learn what a Smart Contract is
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: BookOpen
---
Our objective throughout this course is to learn how to define the code required to implement a smart contract that matches our intent. The previous section, furthermore, told us that all smart contracts are defined by their state and their behaviors. Therefore, we claim the following:

> Solidity is a high-level programming language which allows us to define both the state and behaviors of a smart contract.

Although these behaviors can be almost anything, the majority of the time, such behaviors manipulate the state of the contract. 

## Solidity v.s. Other Programming Languages

The first question one might have when learning a new language is the following: what does the language even look like? To start, we consider the following code snippet:

```solidity
contract A {
    function getOne() public pure returns(uint) {
        return 1;
    }
}
```

In the above, we have a contract named A. Furthermore, we see that A contains a function getOne() that, when called, returns 1. Even though you might not understand everything that is going on in the code snippet, web developers may realize that the code snippet looks similar to JavaScript. The Solidity syntax, as a matter of fact, is actually inspired by JavaScript, and is a testament to the fact that Solidity itself is a high-level programming language.

Now that we have an idea of what both Solidity allows us to do and what the actually syntax of Solidity looks like, its time to learn the actual language itself.

<Quiz quizId="501"/>

# Foundry Quickstart (/academy/blockchain/solidity-foundry/03-smart-contracts/03-foundry-quickstart)

---
title: Foundry Quickstart
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import FoundryQuickstart from "@/content/common/lux-starter-kit/foundry-quickstart.mdx";

In this chapter, we will look into the Foundry that will be used to deploy and interact with smart contracts on the Lux network in our Lux Starter kit.

<FoundryQuickstart/>

# Create a new Smart Contract (/academy/blockchain/solidity-foundry/03-smart-contracts/04-create-new-smart-contract)

---
title: Create a new Smart Contract
description: Learn what a Smart Contract is
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Terminal
---

Alright, let's create our first contract. Head to the Lux Starter Kit Codespace and create a new folder called _my-contracts_ in the _contracts_ folder.

<Callout type="info">
**Remember, when restarting your Lux Starter Kit Codespace, you should restart your Lux network running the command `lux network start` in the terminal**
</Callout> 

Now in there create a new file called HelloWorld.sol and paste the following contents:

```solidity
contract HelloWorld {
    function sayHello() public pure returns (string memory) {
        return "Hello World";
    }
}
```

Now let's deploy the contract:

```bash
forge create --rpc-url local-c --private-key $PK contracts/my-contracts/HelloWorld.sol:HelloWorld --broadcast
```

If deployed successfully we should see something like this:

```bash
[⠒]
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922
Transaction hash: 0x28247e1292e9489c3b51456e2b848eeb6b82ccbcda18836a638f5d81605ac508
```

This means we have deployed our contract to the address 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922. Using this address we can now call our contract:

```bash
cast call --rpc-url local-c 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922 "sayHello()(string)"
```

Don't forget to replace the contract address with the one your contract was deployed to. The result should look like this:

```solidity
"Hello World"
```

# Hello World! Part 1 (/academy/blockchain/solidity-foundry/04-hello-world-part-1/01-intro)

---
title: Hello World! Part 1
description: Learn about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Book
---
In this chapter, our main objective will be to learn about the necessary components require to compile and deploy a smart contract. In particular, we want to be able to:

- Properly create a new Solidity file
- Understand how to organize the business logic of our contract

After learning the two main points above, you will be tasked with building your first smart contract! With the above in mind, let's get started.

# Primitive Values and Types (/academy/blockchain/solidity-foundry/04-hello-world-part-1/02-primitive-value-and-types)

---
title: Primitive Values and Types
description: Learn about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

All code, regardless of the language it is written in, can be described (in very very simple terms) as the manipulation of values. Therefore, if we want to learn a new language, we should start at the type of values we will be manipulating; this is where we will start our Solidity journey.

## Declaring Variable

We first note that Solidity is a statically-typed language; this means that for any variable that we declare, we must declare its type at the time of initialization. Therefore, the general syntax for declaring a variable is as follows:

```solidity
<type> <name>;
```

The following are examples of us declaring variables in Solidity:

```solidity
address addr;
uint256 num;
bool b;
```

For right now, we won't focus on what the types mentioned above actually mean. However, the biggest takeaway is that for any variable that we initialize, we must declare its type.

## Defining Variables

Now that we know how to declare a variable in Solidity, the other half of the puzzle that we want to solve for is actually assigning a value to these variables. The following code snippet is an example of how we would assign values to variables:

```solidity
addr = 0x7f610402ccc4CC1BEbcE9699819200f5f28ED6e3;
num = 0;
b = false;
```

Rather than having to take the two separate steps of declaring a variable and then defining said variable, we can do these two steps in just line; the following code shows how we would do this:

```solidity
address addr = 0x7f610402ccc4CC1BEbcE9699819200f5f28ED6e3;
uint256 num = 0;
bool b = false;
```

## Types

Now that we've discussed the process of both declaring and defining a variable, let's return to the topic of types. In Solidity, the following is a (non-exhaustive) list of elementary types that are available:

- Unsigned Integers: any value which is an unsigned integer is a nonnegative integer. Furthermore, the unsigned integer type is not a singular type, but rather a group of unsigned integers types differentiated by their bit size. Any unsigned integer type has a bit size that is a multiple of 8. So the following types are valid unsigned integer types: uint8, uint16, uint24, uint32, ..., uint256 (uint256 is the maximum unsigned integer bit size). Furthermore, for any unsigned integer uintx (where x is a multiple of 8 and between 0 and 256), we have that the range of uintx is from 0 up to (but not including) 2^(x).
- Signed Integers: any value which is a signed integer is a integer that can be either negative or positive. Like the unsigned integer type, the signed integer type is a group of signed integer types differentiated by their bit size. Any signed integer type has a bit size that is a multipe of 8. Examples of signed integer types are the following: int8, int16, int24, ..., int256 (int256 is the maximum signed integer size). Furthermore, for any signed integer intx (where x is a multiple of 8 and between 0 and 256), we have that the range of intx is from -2^(x - 1) up to (but not including) 2^(x - 1)
- Addresses: the address type consists of a 20-byte value. This type, as its name might suggest, represents the address of an EVM account.
- Booleans: can be either true or false. Treating booleans as integers, a true value is equal to 1 while a false value is equal to 0.

<Quiz quizId="502"/>


# Functions (/academy/blockchain/solidity-foundry/04-hello-world-part-1/03-functions)

---
title: Functions
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt, katherineavalabs]
icon: BookOpen
---

In this section, we will look at functions. Recall from the beginning of this course that all smart contracts consist of a state and their behaviors. With regards to the latter, functions allow us to define the behavior of a smart contract. 
## Structure of a Function
Similar to other programming languages, all functions consist of two sections: their header and their body. An example of the following can be found below:

```solidity
function getOne() public pure returns(uint) {
    return 1; 
}
```
In the above, we have the code `function getOne() public pure returns(uint)` as the **header** of the function, while the code `return 1;` is the **body** of the function (the body of a function is always encapsulated by curly brackets). 

## Function Header
Focusing first on the header of a function, below is the required syntax that all function must have:

```solidity
function <function_name>(<args>) <visibility>
```

In the parentheses, we list the parameters of the function. In addition to having a name, each parameter of a function must also be marked with its type. The only concept that might be new for most developers is the visibility of a function. In Solidity, we can mark a function with the following visibility traits (we'll understand their descriptions):

- **Public**: Accessible both externally (by other contracts or transactions) and internally (from other functions in the same contract).
- **Private**: Accessible only within the contract where they are defined. Not accessible to derived contracts (we'll learn more about them further on) or externally.
- **Internal**: Accessible within the contract and by derived contracts. Not accessible externally.
- **External**: Accessible only from other contracts and transactions. Cannot be called internally using a direct function call (e.g., `f()`), but can be called using `this.f()` which performs an external call.

Additionally, functions can specify their return type(s) using the `returns` keyword followed by the type(s) in parentheses. For example, `returns(uint)` indicates the function returns a single unsigned integer. When multiple return types are specified, such as `returns(uint, bool)`, the function returns a tuple (a fixed-size collection of elements) containing those values.

## Function Body
As of right now, the only thing we know what to do inside the body of a function is declaring/defining local variables. Inside the bodies of functions, we can also use regular mathematical operations like in other programming languages; the following code demonstrates this:

```solidity
function getSquare(uint num) public returns(uint) {
    uint square = num ** 2;
    return square;
}
```

<Quiz quizId="503"/>

# Contracts (/academy/blockchain/solidity-foundry/04-hello-world-part-1/04-contracts)

---
title: Contracts
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

As the halfway mark between knowing absolutely nothing about programming smart contracts and being able to deploy smart contracts, we arrive at the concept of defining contracts themselves. Recall that smart contracts consist of the following:

- A state
- A set of behaviors

We will first start by defining the general structure of a smart contract, before diving into defining each individual component that makes a smart contract what it is.

## General Contract Structure
Below is the general syntax for a smart contract in Solidity:

```solidity
contract <ContractName> {
 
  // State Variables go here
  
  // Contract functions go here
  
}
```

We declare a contract with the contract keyword, followed by the name of the smart contract (which usually follows [PascalCase notation](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/)). Afterwards, we use curly brackets to encapsulate the body of the smart contract.

## State Variables

The same workflow and rules regarding the declaration and definition of variables apply to variables associated with the state of a smart contract. State variables, as they're called, are persistent between transactions and can only be modified in the following two scenarios:
- During the initialization of the smart contract itself
- By a function of the smart contract itself

No other account can modify the variables of a smart contract directly; only the contract itself can. An example of state variables with a smart contract is as follows:

```solidity
contract A {
 
    uint256 num = 5;
  
}
```

## State Variable Visibility

Solidity is an object-oriented programming language (where contracts act as classes) and so as we will see soon, contracts are able to inherit other contracts. However, we still want to define the inheritance properties of the state variables of a contract. Therefore, we introduce state variable visibility. The following are the three possible type of state variable visibilities:
- Public: the state variable is found in the parent contract and all children contract. Furthermore, any state variable defined as public will contain a getter function of the same name
- Internal: this is the same as public, except a getter function is not created. Any state variable not annotated with a visibility is, by default, set as internal
- Private: the state variable is found only in the parent contract - children contract do not inherit the state variable

> In this context, the private visibility does not mean that the value of the associated variable is accessible only to the contract. Anyone with access to the blockchain can find the value of a private variable. 

Below are examples of explicitly declaring the visibility of state variable:

```solidity
contract A {
​
    address private addr;
    uint internal num;
    int public numTwo;
  
}
```

## Contract Functions

Having gone over the state of a contract, we'll now discuss about contract functions: the second property of smart contracts and the logic that allows us to modify state variables. The same way in which we declared and defined functions earlier also applies here. The only new thing here is that our contract functions can modify the state variables of the associated contract. As an example, below is a contract with a state variable, and associated functions to get/set the values of the variable:

```solidity
contract A {
 
    uint num;
  
    function setNum(uint _num) public {
        num = _num; 
    }
  
    function getNum() public view returns(uint) {
        return num; 
    }

}
```

<Quiz quizId="504"/>

# Solidity File Structure (/academy/blockchain/solidity-foundry/04-hello-world-part-1/05-solidity-file-structure)

---
title: Solidity File Structure
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Now that we understand how to write (very basic) smart contracts in their entirety, we are certainly ready to deploy smart contracts onto the blockchain... right?

Unfortunately, we are not yet ready to do so. To understand why, consider the EVM, the virtual machine which will be executing the logic of your smart contract. The EVM does not execute Solidity code - rather, it executes opcodes in the form of bytes. Therefore, for any Solidity smart contract that we develop, we need a way to convert it into EVM bytecode that the EVM can then parse. 

Although the above sounds like a complex task, this is actually not the case! All we need to do is put our smart contract logic into a .sol file, which a Solidity compiler can then convert into EVM bytecode!

## Compiler and License
At the top of every Solidity file goes the SPDX-License-Identifier. This identifier specifies how you wish for the source code of your file to be used by other people. The most popular SPDX-License-Identifier is the MIT identifier. Afterwards, we will want to specify the version of Solidity that we want to use to compile our source code. This is usually in the format of the following:

```solidity
pragma solidity <version>;
```

For more information regarding which version of Solidity you should use, head over to the official Solidity [documentation](https://docs.soliditylang.org/en/v0.8.28/) where you can find more information about the details of each release version. Generally speaking though, the following can be observed about the age of release versions:

- Older release versions are less optimized and lack many features of newer Solidity versions, but they have been battle-tested over the years and are thus more secure
- Newer release versions bring much-desired features and are more optimized, but have had less time to be tested for security purposes

Sometimes, you might see the following inside a Solidity file:

```solidity
pragma solidity ^<version>;
```

The caret specifies that the source file is meant to be compiled with any version of Solidity that is compatible with version. As an example, consider the line:
pragma solidity ^0.6.4;

Then the source file can be compiled with any version of Solidity that has the prefix 0.6. However, any compiler whose prefix does not match that of 0.6 cannot compile the source file above.

## Tying Everything Together
The below is an example of a Solidity source file that can be compiled into bytecode:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
​
contract A {
 
    uint256 num;
  
    function getNum() public view returns(uint) {
        return num; 
    }
  
    function setNum(uint _num) public {
        num = _num;
    }
  
}
```

<Quiz quizId="505"/>

# Build Basic Smart Contract (/academy/blockchain/solidity-foundry/04-hello-world-part-1/06-build-basic-smart-contract)

---
title: Build Basic Smart Contract
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Let's create and interact with the basic smart contract. Create a new solidity file called NumberStorage.sol and fill it with the contract below:

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

contract NumberStorage {
 
    uint256 num;
  
    function getNum() public view returns(uint) {
        return num; 
    }
  
    function setNum(uint _num) public {
        num = _num;
    }
  
}
```

Now let's deploy it:

```bash
forge create --rpc-url local-c --private-key $PK contracts/my-contracts/NumberStorage.sol:NumberStorage --broadcast
```

The result should look something like this:
```bash
[⠒] Compiling...
[⠢] Compiling 1 files with 0.8.18
[⠆] Solc 0.8.18 finished in 14.67ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25
Transaction hash: 0x5717e501e12f40d644c60030bc0ab9569ddb9f4cba968546ab597fb516eae09b
```

Next, let's store a number:

```bash
cast send --rpc-url local-c --private-key $PK 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 "setNum(uint)" 42
```

Since we are now writing to and not just reading from the blockchain we will see the transaction details:
```bash
blockHash               0x02eb13d317a43976ea8ba21a76e5deb6d02d257a0b98c1a84734e0609b8a6fec
blockNumber             3
contractAddress         
cumulativeGasUsed       43516
effectiveGasPrice       28000000000
from                    0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
gasUsed                 43516
logs                    []
logsBloom               0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
root                    
status                  1
transactionHash         0xd382101a4955f05f8a96e4ab4b62457700697930dc6ed84246a346e51d41d3cb
transactionIndex        0
type                    2
to                      0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25
```

Next, let's get the number from the storage:

```bash
cast call --rpc-url local-c 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 "getNum()(uint)"
```
As a result we should get the number we have stored earlier:

```bash
@martineckardt ➜ /workspaces/lux-starter-kit (main) $ cast call --rpc-url local-c 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 "getNum()(uint)"
42
```

# Contract Standarization (/academy/blockchain/solidity-foundry/06-contract-standarization/01-contract-standarization)

---
title: Contract Standarization
description: Learn how to reuse standard code
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

Perhaps the most famous contract standard, the ERC-20 interface allows for users to develop their own tokens that other users/contracts are able to interact with. To understand what the ERC-20 is from a high-level and why it's almost necessary, let's first consider the following scenario:

## Lack of Information

The concept of a token contract, while intuitive at first, begins to become quite complex when we consider what the implementation of such a contract consists of. As an example, consider a car. We know that a car is a vehicle that takes us from point A to point B; furthermore, we can say that cars move via wheels and we can dictate the direction of a car via a steering wheel. However, consider the following:

- How many seats does a car have?
- Do all cars come with a retractable sunroof?
- How is the car powered (i.e. via gasoline, electric, hydrogen, etc)?

The questions above do not break down the concept of a car, but rather, they complicate any product meant to complement a car. Let's now focus on tokens. Abstractly, we can state the following:

- All accounts have a balance of the token (even if its zero)
- We can transfer tokens from one account to another
- The token contract does not allow for double-spending and related forms of manipulation

Let's now write a token smart contract which achieves the following:

```solidity
contract Token {
​
    mapping(address => uint) balances;
​
    function transfer(address to, uint amount) public {
        require(balances[msg.sender] >= amount);
        balances[msg.sender] -= amount;
        balances[to] += amount;
    }
}
```

Tying back to our car example, lets assume we have another Token contract with the following implementation:

```solidity
contract Token {
​
    mapping(address => uint) balances;
​
    function transferTokens(address to, uint amount) public {
        require(balances[msg.sender] >= amount);
        balances[msg.sender] -= amount;
        balances[to] += amount;
    }
}
```

The code block above, logically, does the exact same thing as the original Token contract before it. However, notice that the function name in this case changed - we went from transfer to transferTokens. The above demonstrates for a user to interact with the either Token contract, they would first need to find out the name of the function associated with transferring tokens. 

But why stop there? We can also name the transfer function the following:

```solidity
function transferSomeTokens() public {}
function doTransfer() public {}
function sendTokens() public {}
// ...
```

As it might have become obvious, for any user that wants to interact with a particular Token contract, they would need to somehow find a way to get the correct function name or risk their transaction reverting. Furthermore, consider the case of a smart contract trying to call a Token contract. We would need to hardcode every single possible function name into our contract - something which is practically impossible. 

This entire section leads us to the conclusion that for concepts like token contracts to work, there cannot be a lack of information regarding the behaviors (and their associated names). There needs to be consensus regarding a standard for token contracts which everyone can turn to. The ERC-20 contract, in essence, is this standard.

# Inheritance (/academy/blockchain/solidity-foundry/06-contract-standarization/02-inheritance)

---
title: Inheritance
description: Learn how to reuse standard code
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
In the previous section, we foreshadowed inheritance, a concept that Solidity shares with other object-oriented programming languages. In this section, we will go over how to inherit other smart contracts and introduce inheritance in the concept of contract constructors.

## B is A

At the most fundamental level, contract inheritance works as follows:

```solidity
contract A {}
​
contract B is A {}
```

In the code snippet above, we have an arbitrary contract A and a contract B which inherits A. Although simple, this doesn't really explain the full concept of inheritance. Let's consider a more sophisticated example:

```solidity
contract A {
  uint num;
  
  function square(uint base) public pure returns(uint) {
        return base ** 2;
  }
}
​
contract B is A {}
```

In the code above, we have two contract A and B. The definition of contract A is nothing new, but what about contract B? Well, since B is inheriting A, this implies that B has the following properties:

- B has the state variable num
- B has the function square

To really drive home the idea of inheritance, let's consider this final code snippet:

```solidity
contract A {
  
  uint private num1;
  string internal name;
  
  function getOne() private pure returns(uint) {
    return 1;
  }
  
  function getTwo() public pure returns(uint) {
    return 2;
  }
}
​
contract B is A {}
```

The code snippet above is more sophisticated in that we are explicitly introducing visibility in the context of inheritance. Again, the definition of A should be trivial. Focusing on B, we have the following:

- B does not have the state variable num1 and the function getOne, since these are marked as private and therefore, belong only to A
- B has the state variable name since it is marked as internal and therefore, able to be derived by B
- B has the function getTwo since it is marked as public

## Constructors and Inheritance

Just like we can inherit functions from parent functions, we can also inherit constructors from parent contracts. The syntax for inheriting parent functions is as follows:

```solidity
constructor() <parent-name>() {}

```

An example of constructor inheritance can be found below:

```solidity

contract A {
  uint numl;
  constructor() {
    num1 = 5;
  }
}
​
contract B is A {
  uint num2;
  constructor() A() {
    num2 = 7;
  }
}   
```

For contract A, we are setting num1 equal to 5 at the time of initialization. For contract B, we first call the constructor of A (which sets num1 in B to 5) and then sets num2 to 7.

<Quiz quizId="512"/> 

# Interfaces (/academy/blockchain/solidity-foundry/06-contract-standarization/03-interfaces)

---
title: Interfaces
description: Understanding Smart Contract Interfaces and Their Role in Standardization
updated: 2025-01-24
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

# Interfaces in Smart Contracts

## Introduction

In smart contract development, **interfaces** play a crucial role in ensuring standardization and interoperability between different contracts. By defining a consistent structure that contracts must adhere to, interfaces enable seamless integration across various decentralized applications (dApps), wallets, and protocols.

Some contracts such as **ERC-20, ERC-721, and ERC-1155** that we will cover later, leverage interfaces to create widely accepted token standards. These standards help different smart contracts interact efficiently without needing to understand each contract's internal implementation.

In this lesson, we will explore how interfaces work in Solidity, why they are important, and how they contribute to the broader ecosystem of dApps.

---

## What Is an Interface?

In Solidity, an **interface** is a contract type that defines function signatures without implementing them. This means that an interface only specifies which functions must exist in a contract but does not provide their actual logic.

Here’s an example of a simple Solidity interface:

```solidity
interface IExample {
    function getValue() external view returns (uint256);
    function setValue(uint256 _value) external;
}
```

Any contract that implements `IExample` must provide concrete implementations for the `getValue` and `setValue` functions.

---

## Why Are Interfaces Important?

Interfaces provide several benefits in smart contract development:

### 1. **Standardization**
   - Interfaces ensure that different contracts follow a common structure.
   - Examples include **ERC-20** for fungible tokens and **ERC-721** for NFTs, allowing various dApps and protocols to interact with them effortlessly.

### 2. **Interoperability**
   - Contracts that adhere to a shared interface can seamlessly interact without knowing each other’s internal implementation.
   - This is essential for decentralized finance (DeFi) protocols, where lending, staking, and trading contracts often need to communicate.

### 3. **Security and Modularity**
   - Developers can create separate implementations for different use cases while ensuring compatibility with existing protocols.
   - Security audits become easier since standardized interfaces limit unexpected behaviors.

---

## Implementing an Interface

A contract that implements an interface **must** include all the functions defined in the interface. Here’s an example implementation:

```solidity
// Define the interface
interface IExample {
    function getValue() external view returns (uint256);
    function setValue(uint256 _value) external;
}

// Implement the interface in a contract
contract ExampleContract is IExample {
    uint256 private value;

    function getValue() external view override returns (uint256) {
        return value;
    }

    function setValue(uint256 _value) external override {
        value = _value;
    }
}
```

### Key Points:
- The `ExampleContract` explicitly states that it implements `IExample` using the `is` keyword.
- The `override` keyword is used to ensure the function implementations match the interface definitions.
- The contract **must** implement all functions declared in `IExample`; otherwise, it will fail to compile.

---

## Conclusion

Interfaces are a foundational concept in Solidity that enable **standardization, interoperability, and security** in smart contract development. By enforcing a predefined structure, interfaces allow different contracts to communicate efficiently, fostering the seamless integration of protocols in Ethereum and beyond.

In the next section, we will explore **abstract contracts** and how they compare to interfaces when designing modular and reusable smart contract architectures.

---

By understanding and utilizing interfaces correctly, developers can ensure their smart contracts remain flexible, compatible, and scalable across the decentralized ecosystem.

<Quiz quizId="514"/>
<Quiz quizId="515"/>
<Quiz quizId="516"/>


# Abstract Contracts (/academy/blockchain/solidity-foundry/06-contract-standarization/04-abstract)

---
title: Abstract Contracts
description: Understanding Abstract Contracts and Their Role in Smart Contract Inheritance
updated: 2025-01-24
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

# Abstract Contracts in Smart Contracts

## Introduction

When developing smart contracts on the EVM, developers often need to create reusable and modular contract structures. **Abstract contracts** provide a way to define base contract logic that other contracts can inherit while leaving certain details for implementation in derived contracts.

Abstract contracts are particularly useful when building **standardized contract templates**, **frameworks for protocols**, and **secure upgradeable contract architectures**. Unlike interfaces, abstract contracts can contain both **implemented and unimplemented (abstract) functions**, making them more flexible for **inheritance-based development**.

In this lesson, we will explore what abstract contracts are, how they work, and their role in designing scalable and maintainable smart contract architectures.

---

## What Is an Abstract Contract?

An **abstract contract** is a contract that **cannot be deployed on its own** because it contains at least one function without an implementation. Instead, it serves as a **base contract** that other contracts can inherit and extend.

Here's an example of an abstract contract:

```solidity
// Abstract contract defining a base structure
abstract contract BaseContract {
    function getValue() public view virtual returns (uint256);
}
```

Since `getValue()` is not implemented, `BaseContract` cannot be deployed directly. Any contract inheriting `BaseContract` **must provide an implementation** for `getValue()`.

---

## Why Are Abstract Contracts Important?

Abstract contracts offer several benefits for **EVM smart contract development**:

### 1. **Code Reusability**
   - Developers can define **common logic** in an abstract contract and extend it in multiple derived contracts.
   - This reduces code duplication and improves maintainability.

### 2. **Flexibility in Design**
   - Abstract contracts allow developers to create **modular architectures** where child contracts can implement logic differently based on specific needs.

### 3. **Secure Standardization**
   - By enforcing the implementation of required functions in child contracts, abstract contracts help prevent **inconsistent implementations**.
   - This is useful for **token standards, access control mechanisms, and governance contracts**.

---

## Implementing an Abstract Contract

To use an abstract contract, a child contract must **inherit** from it and implement its unimplemented functions. Here’s an example:

```solidity
// Abstract contract defining a required function
abstract contract BaseContract {
    function getValue() public view virtual returns (uint256);
}

// Concrete contract inheriting from BaseContract
contract DerivedContract is BaseContract {
    uint256 private value = 42;

    function getValue() public view override returns (uint256) {
        return value;
    }
}
```

### Key Points:
- `BaseContract` defines `getValue()` as a **virtual** function, meaning it must be overridden in a derived contract.
- `DerivedContract` **inherits** `BaseContract` and provides an implementation for `getValue()`, making it deployable.

---

## Abstract Contracts vs. Interfaces

Both **abstract contracts** and **interfaces** define required function structures, but they have key differences:

| Feature            | Abstract Contract | Interface |
|-------------------|------------------|-----------|
| Function Implementation | Yes (can have implementations) | No (only function signatures) |
| State Variables | Yes | No |
| Constructor | Yes | No |
| Multiple Inheritance | Yes (but trickier because conflicts can occur with parents having contradicting logic) | Yes |

### When to Use Which?
- **Use an abstract contract** when:
  - You need to provide **some** reusable logic alongside function definitions.
  - You want to define **shared state variables** that child contracts can inherit.
  - You are building **modular contract frameworks** with base functionality.

- **Use an interface** when:
  - You only need to **define function signatures** without implementation.
  - You want to ensure compatibility with **multiple unrelated contracts**.

---

## Abstract Contracts in Token Standards

Abstract contracts are frequently used in **EVM token standards** to provide **reusable logic**. For example, OpenZeppelin’s implementation of ERC-20 and ERC-721 uses abstract contracts to define **common functionality**:

```solidity
abstract contract ERC20 {
    function transfer(address recipient, uint256 amount) public virtual returns (bool);
}

contract MyToken is ERC20 {
    function transfer(address recipient, uint256 amount) public override returns (bool) {
        // Token transfer logic
        return true;
    }
}
```

By extending the abstract `ERC20` contract, `MyToken` **inherits** its structure while allowing specific implementations for token transfers.

---

## Using Abstract Contracts for Access Control

Another common use case for abstract contracts is **access control**. Developers can create a base contract that **enforces role-based permissions**, allowing child contracts to inherit this functionality.

Example of an **abstract access control contract**:

```solidity
abstract contract AccessControl {
    address public owner;

    constructor() {
        owner = msg.sender;
    }

    modifier onlyOwner() {
        require(msg.sender == owner, "Not the owner");
        _;
    }

    function restrictedFunction() public view virtual onlyOwner returns (string memory);
}

contract SecureContract is AccessControl {
    function restrictedFunction() public view override onlyOwner returns (string memory) {
        return "Access granted!";
    }
}
```

### Key Takeaways:
- `AccessControl` defines an **owner** variable and an `onlyOwner` modifier to restrict access.
- The function `restrictedFunction()` is declared **virtual**, meaning any child contract **must implement it**.
- `SecureContract` inherits from `AccessControl` and provides an implementation for `restrictedFunction()`.

---

## Conclusion

Abstract contracts are a **powerful tool** for **modular, reusable, and secure** smart contract development on the **EVM**. They allow developers to define **base contract logic** while enforcing **required implementations** in child contracts.

By leveraging **abstract contracts**, developers can:

- Reduce code duplication  
- Improve security through **standardized implementations**  
- Design flexible and scalable smart contract architectures  

In the next section, we will explore one of the most common contract standard used for **Fungible Tokens**, diving deeper into this standard, and how it extends and interact with one another efficiently in **EVM-based smart contract development**.

<Quiz quizId="517"/>
<Quiz quizId="518"/>
<Quiz quizId="519"/>


# Hello World Part. 2 (/academy/blockchain/solidity-foundry/05-hello-world-part-2/01-intro)

---
title: Hello World Part. 2
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

If you've made it this far into the course, congratulations! At this point so far, you are now able to write very simple smart contracts which can be compiled down into EVM bytecode and deployed onto the blockchain! In this chapter, we will consider the following questions:

- How can we utilize Solidity's built-in data structures?
- How can we use control flow in our functions?
- How can we store data on the blockchain in a cheap manner?
- How can we utilize contract constructors?
- What does the Solidity inheritance model look like?

In this chapter, we will tackle the questions above. By looking into these questions, we will learn the skills necessary for taking our smart contracts from being simple programs to complex ones.

# Control Flow (/academy/blockchain/solidity-foundry/05-hello-world-part-2/02-control-flow)

---
title: Control Flow
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

When first learning about how to write smart contract functions, we first focus on making sure that our syntax is correct before everything else. Therefore, if you have looked deeply into your starter code, you will notice that your code is purely sequential. That is, every single line of code inside of your functions are executed in a linear manner. While easy to write and understand, writing purely sequential code means that our contracts will behave the exact same way, regardless of the arguments passed in or the state of the contract. If we want our functions to behave differently based on the arguments passed in and the state of the contract, we will want to embrace control flow in our code
## If/Else Statements
The first type of control flow that we will examine is the if/else statement; below is an example of an if/else statement in Solidity:
```solidity
if (<boolean-statement>) {
    
} else {
  
}
```
If we wanted to add multiple branches to our if/else statement, we would do the following:

```solidity
if (<boolean-statement>) {
    
} else if (<boolean-statement>) {
       
} else {
  
}
```

## For Loops
The next type of control flow that we will examine are for-loops; for-loops allow us to iterate over a range of integers. Below is the general syntax for for-loops:

```solidity
for (<loop-variable>; <loop-condition>; <loop-incrementer>) {
  
}
```

Below is an implementation of the factorial algorithm, which uses for-loops:

```solidity
function factorial(uint256 num) public pure returns(uint256) {
    if (num == 0) {
      return 1;
    } else if (num == 1) {
      return 1;
    }
    uint256 result = num;
    for (uint i = 2; i < num; i++) {
      result = result * i;
    }
    return result;
}
```
Although not necessary, we usual set the type of the loop variable to type uint256 (uint) as this will become useful when indexing into arrays.
## While Loops
The last type of control flow that we will examine are while loops. Below is the general syntax of while loops in Solidity:
```solidity
while (<boolean-condition>) {
       
}
```

<Quiz quizId="506"/>

# Data Structures (/academy/blockchain/solidity-foundry/05-hello-world-part-2/03-data-structures)

---
title: Data Structures
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt, katherineavalabs]
icon: BookOpen
---
Like with all programming languages, Solidity offers us a way to store multiple values in one location via built-in data structures. In this section, we will look at the following:
- Mappings
- Structs
- Static Arrays
- Dynamic Arrays

Let's get started!

## Mappings

Mappings in Solidity are similar to data structures like dictionaries found in other programming languages (e.g. Python). At its most basic level, mappings allow us to store key-value pairs. Unlike the types we explored earlier in this course, mappings can only be instantiated as state variables (i.e. we cannot create a new mapping data structure within the body of a function). Furthermore, declaring a mapping and defining key-values of a pair must be done separately. Below is the general syntax for a mapping:
```solidity
mapping(<key-type> => (value-type)) <optional-visibility> <mapping-name>;
```

Below shows an example of how to define a key-value pair within a mapping:

```solidity
mapping(address => uint) map;
​
map[0xc0ffee254729296a45a3885639AC7E10F9d54979] = 5;
```
## Nested Mappings

Below are some restrictions regarding mappings:
- Keys can be any simple type (i.e. types associated with a singular value)
- Values can be any type

Since values can be any type, and mappings are types by definition, this implies that we can map keys to mappings! Therefore, the following is legal syntax:

```solidity
mapping(uint => mapping(uint => address)) mapTwo;
```

To work with inner mappings, the following code snippet gives an idea as to how to access such values:

```solidity
address addr = mapTwo[5][6];
```

<Quiz quizId="507"/>

## Structs
The next type of data structure that we will examine are structs. For those who have worked with C++ or any other similar programming languages, structs in Solidity are the same concept. Structs, or structures, are data structures which allow us to group multiple values. We can think of structs as very basic classes, except that they lack any sort of behavior and are solely used to store information. Like mappings, we first must define the layout of a struct within the body of a smart contract; below is an example of how we would do so:

```solidity
struct Person {
    uint256 age;
    string name;
}
```
To create an instance of a struct as a state variable, we can use the following syntax:

```solidity
Person person = Person(5, "Rodrigo");
```

> If you try using the syntax above in the body of a function, you will get an error regarding the location of the person variable. Since structs are a grouping of values, we must explictly state where these values are stored (either in memory or in storage). Therefore, we would want to use the following:

```solidity
Person memory person = Person(5, "Rodrigo")
```

### Understanding Memory vs Storage

In Solidity, **storage** and **memory** refer to where data is stored:

- **Storage**: Data stored permanently on the blockchain. This is where state variables live, and any changes to storage persist across function calls. Reading from and writing to storage costs gas, making it more expensive.

- **Memory**: Temporary data that exists only during the execution of a function. Once the function completes, memory is cleared. Using memory is cheaper in terms of gas costs, but the data doesn't persist after the function ends.

When creating structs inside functions, Solidity requires you to specify the location because it needs to know whether you're creating a temporary copy (memory) or modifying persistent data (storage). For most cases where you're just working with data within a function, you'll use `memory`.

<Quiz quizId="508"/>

## Static Arrays
The majority of programming languages provide some built-in data structures similar to lists. Solidity is no different in that it provides two types of list-like data structures:

- Static arrays
- Dynamic Arrays

Focusing first on static arrays, these are lists whose **length is fixed at the time of initialization**. This means that once a static array has been initialized, its length will never change. Below is the syntax to declare a static array:

```solidity
<array-type>[<array-size>] <array-name>;
```
Below is an example of declaring a static array:
```solidity
uint[5] arr;
```
With regards to declaring the value of a static array, we have two options:
- to declare it in memory, or
- to declare it in storage
This will not change the way in which we declare and define them, but we'll see their differences after going through their basic syntax. We'll use a memory array as an example.

For declaring an array we might do the following:
```solidity
<array-type>[<array-size>] memory <array-name>;
```
Then, we could declare individual values via indexing; an example of this can be found below:
```solidity
function test() public {
        uint[5] memory arr;
        arr[2] = 4;
    }
```
If we want to both declare and define a static array in memory, we can use the following:

```solidity
uint8[5] memory arr = [1, 2, 3, 4, 5];
```

### Key Differences: Memory vs Storage Arrays
So, if they are declared and defined in the same way, what makes static arrays in memory or storage different from each other? (appart from where they are stored)

The answer is in how they're laid out and accessed:

**Storage Arrays:**
- **Packed Layout**: Elements are packed efficiently to minimize gas costs. For example, a `uint8[4]` array in storage occupies a single 32-byte slot, with each `uint8` element taking up 1 byte. This packing optimization reduces storage costs significantly.
- **Reference**: See [Layout of State Variables in Storage](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html) in the Solidity documentation.

**Memory Arrays:**
- **Aligned Layout**: Each element occupies a full 32-byte slot, regardless of its actual size. This alignment is designed for efficient EVM access. For example, a `uint8[4]` array in memory consumes 128 bytes (4 elements × 32 bytes each), even though each element only needs 1 byte.
- **Reference**: See [Layout in Memory](https://docs.soliditylang.org/en/latest/internals/layout_in_memory.html) in the Solidity documentation.

These layout differences mean that:
- Storage arrays are more gas-efficient for storing data long-term due to packing
- Memory arrays are optimized for fast read/write access during function execution
- The same array type can consume vastly different amounts of space depending on its location

## Dynamic Arrays

Dynamic arrays differ from static arrays in a key way: **static arrays have a size that must be known at compile time** (like `uint[5]`), while **dynamic arrays can have a size determined at runtime**. However, the behavior of dynamic arrays depends on whether they're in storage or memory.

### Dynamic Arrays in Storage

When declared as state variables, dynamic arrays are stored in storage and can be resized dynamically throughout the contract's lifetime. Below is an example of how we would declare a dynamic array in storage:

```solidity
<array-type>[] <array-name>;
```

By default, a dynamic array in storage will be empty (in contrast with static arrays, which will be filled with the default value of the array type). Therefore, we can use the following associated methods to manipulate the state of a dynamic array:
- `push`: pushes an element to the end of the dynamic array
- `pop`: removes the last element of a dynamic array

Below is an example of the methods above in action:
```solidity
uint[] arr;

function test() public {
    arr.push(1);
    arr.pop();
}
```

### Dynamic Arrays in Memory

Dynamic arrays can also be created in memory, but with important restrictions:

1. **Size determined at runtime**: Unlike static arrays (where size is compile-time), dynamic arrays in memory can have their size determined at runtime using the `new` keyword
2. **Fixed size once created**: Once allocated, the size cannot change (no `push` or `pop` methods)
3. **Temporary**: Memory arrays only exist during function execution

Here's the key difference:

```solidity
function example(uint size) public {
    // Static array: size must be known at compile time
    uint[5] memory staticArr;  // Size is hardcoded
    
    // Dynamic array in memory: size can be determined at runtime
    uint[] memory dynamicArr = new uint[](size);  // Size comes from parameter
    // dynamicArr.push(1);  // Error: push/pop not available in memory
}
```

The distinction between static and dynamic arrays is about **when the size is determined** (compile-time vs runtime). Dynamic arrays in storage can grow/shrink, while dynamic arrays in memory have a runtime-determined size that becomes fixed once created.

<Quiz quizId="513"/> 

# Contract Constructor (/academy/blockchain/solidity-foundry/05-hello-world-part-2/04-contract-constructor)

---
title: Contract Constructor
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
As a segue to learning about the object-oriented programming aspect of Solidity, we will touch upon contract constructors. Similar to class constructors in other languages, constructors in Solidity allow us to define the state of a contract at the time of initialization.
## Syntax
Below is the general syntax for a contract constructor:

```solidity
constructor(<arguments>) {      
}
```
## Example
Below is an example of a contract constructor in action:

```solidity
contract A {
    uint num;
  
    constructor(uint _num) {
        num = _num;
    }
}
```

<Quiz quizId="509"/>

# Modifiers (/academy/blockchain/solidity-foundry/05-hello-world-part-2/05-modifiers)

---
title: Modifiers
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
Before discussing the concept of modifiers, we will first start by talking about the limitations of the visibilities provided by Solidity

## Aside: Limitations of Visibility

Recall that with regards to functions, we have the following four visibilities available:
- Public
- Private
- Internal
- External
Let's now consider the following contract:

```solidity
contract Safe {
  
  function deposit() public {}
  
  function withdraw() public {}
​
}
```
Above, we have the outline of a very basic safe contract which is meant to be accessed only by the deployer of the Safe contract. Currently, this Safe contract does not maintain the invariant previously mentioned as both deposit and withdraw are marked as public. However, even if we were to modify the visibility of the following functions, we would have the following:
- The functions become inaccessible to all accounts except the contract itself
- The functions still remain accessible to all accounts

The scenario above outlines the following problem: for functions whose access we want to restrict to only authorized users, we cannot rely on visibility.

## Modifying the Behavior of Functions via Modifiers

To combat the problem previously mentioned, we now look at modifiers. Modifiers behave similarly to functions and they modify the logic of the functions they are attached to. The syntax for defining a modifier is as follows:
```solidity
modifier <modifier-name>(<arguments>) {}
```
To attach a modifier to a function, we have the following:
```solidity
function func() public <modifier>(<arguments>){}
```
To introduce the concept of modifiers to our Safe contract, let's first modify it to the following:
```solidity
contract Safe {
  
  address owner;
  
  constructor() {
    owner = msg.sender; 
  }
  
  function deposit() public {}
  
  function withdraw() public {}
​
}
```
With the above changes, we are setting the state variable owner equal to the contract deployer (i.e. msg.sender) and so we are now able to store the address of the contract deployer in our Safe contract. Let's now write a modifier to only allows for the owner of the Safe contract to call the function it is attached to:
```solidity
modifier onlyOwner() {
  require(msg.sender == owner, "You are not the owner"!);
  _;
}
```
Examining each line, we have:
- Line 2: we are using a require statement; the require statement has the following syntax: require(boolean condition, error message). If the boolean condition is true, we move onto the next line of code. Otherwise, we raise an error with the error message provided in the statement. In this context, we are requiring that any person calling the function onlyOwner is attached to is the owner of the Safe contract.
- Line 3: assuming that the owner of the Safe contract is calling the associated function, we now revert control back to the original function via the _; keyword. 
Incorporating the modifier into our Safe contract we now have:

```solidity
contract Safe {
  
  address owner;
  
  modifier onlyOwner() {
  require(msg.sender == owner, "You are not the owner"!);
  _;
  }
  
  constructor() {
    owner = msg.sender; 
  }
  
  function deposit() public onlyOwner() {}
  
  function withdraw() public onlyOwner() {}
​
}
```
For either deposit or withdraw, we now have the following execution flow:
- An account first calls either deposit or withdraw
- Since the onlyOwner modifier is attached to either function, onlyOwner is first executed
- If the account is the contract owner, we return the execution flow back to the parent function (in this case, either deposit or withdraw)

<Quiz quizId="510"/>

# Events (/academy/blockchain/solidity-foundry/05-hello-world-part-2/06-events)

---
title: Events
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

Throughout this course, we have seen smart contract data stored in two places:
- State Variables (i.e. in storage)
- Function Bodies (i.e. in memory)

Let's now look at the advantages and disadvantages of each data location:

-Storage: this data location is persistent between transactions and so we don't have to worry about state variables being lost. However, reading and writing to storage is computationally expensive and therefore, requires a substantial amount of gas to perform.
-Memory:  this data location is not persistent between transactions; therefore, values that you write in memory in one transaction will be lost after the transaction is finished executing. However, reading and writing to storage is computationally cheap and therefore, requires little gas. 

This brings up a good question: what if we wanted to permanently store data (and lets assume that this data is immutable) on the blockchain without having to use state variables? This leads us to the topic of this section: events.

## Defining Events

Events are data structures that we can then "emit." We first examine the syntax for defining events:
```solidity
event <event_name>(event_args)
```

The definition of an event goes in the body of a smart contract (but never within a function body). Below is a simple example of an event definition:

```solidity
event Transfer(address _from, address _to, uint256 _value);
```

## Emitting Events

Now that we understand how to define events, we will now explore how to emit an instance of an event. Consider the following function:

```solidity
function emitEvent() public {}
```

To emit the transfer event we defined earlier, we implement the following:

```solidity
function emitEvent() public {
    emit Transfer(address(0), address(0), 0);
}
```

where the arguments of the Transfer event are arbitrary.

<Quiz quizId="511"/> 

# Intro ERC-20 Tokens (/academy/blockchain/solidity-foundry/07-erc20-smart-contracts/01-erc20-intro)

---
title: Intro ERC-20 Tokens
description: Fungible Token Standard
updated: 2025-01-24
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

# Intro ERC-20 Tokens

## Fungible Token Standard

Previously, we explored the concept of smart contracts and how they can be used to execute predefined rules on a blockchain. One of the most impactful use cases of smart contracts is the implementation of token standards. The **ERC-20** standard was introduced to create a universal and interoperable framework for tokens on the EVM.

The ERC-20 standard defines a set of functions and events that a token contract must implement, making it easier for wallets, exchanges, and applications to interact with these tokens. As a result, ERC-20 tokens have become the foundation for countless decentralized finance (DeFi) protocols, governance systems, and utility applications.

To better understand why ERC-20 is such a critical part of EVM’s ecosystem, let's first explore the concept of fungibility.

---

## Fungibility

Fungibility refers to an asset’s ability to be exchanged for another of the same type without any difference in value. Let’s use currency as an example:

- A \$10 bill is considered fungible because it holds the same value as another \$10 bill. If you exchange one $10 bill for another, their value remains the same.
- Similarly, you can break a \$10 bill into smaller denominations like two \$5 bills or ten $1 bills, without changing the total value.

ERC-20 tokens are fungible by design. For instance:

- 1 unit of an ERC-20 token (e.g., USDC or USDT) is indistinguishable and interchangeable with any other unit of the same token.
- The fungibility of ERC-20 tokens makes them ideal for use cases such as stablecoins, governance tokens, and liquidity pool assets.

However, fungibility also introduces a limitation: if a use case requires unique attributes for individual tokens, the ERC-20 standard is insufficient. For such scenarios, the ERC-721 standard is used instead, as we will discuss in the NFT Deployment course.

---

## ERC-20: The Standard

The ERC-20 token standard was designed to simplify the implementation of fungible tokens and ensure compatibility across various EVM-based applications. At its core, an ERC-20 token contract allows the following operations:

- Tracking balances of token holders.
- Transferring tokens between accounts.
- Approving other accounts to spend tokens on behalf of the owner.
- Querying details about the token, such as its name, symbol, and total supply.

Below is the interface for ERC-20 tokens as defined in the original proposal:

```solidity
interface ERC20 {
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(
        address sender,
        address recipient,
        uint256 amount
    ) external returns (bool);
    
    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
}


# ERC20 Technical Walkthrough (/academy/blockchain/solidity-foundry/07-erc20-smart-contracts/02-technical-walkthrough)

---
title: ERC20 Technical Walkthrough
description: Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
In this section, we will introduce the ERC-20 interface that all token contracts should aim to implement. Furthermore, we will go through each function that the ERC-20 contract mentions and explain what it does in-depth.
## ERC-20 Interface

Below is the ERC-20 interface from EIP-20:

```solidity
interface IERC20 {
​
    function name() external view returns (string memory);
​
    function symbol() external view returns (string memory);
​
    function decimals() external view returns (uint8);
​
    function totalSupply() external view returns (uint256);
​
    function balanceOf(address _owner) external view returns (uint256 balance);
​
    function transfer(address _to, uint256 _value) external returns (bool success);
​
    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);
​
    function approve(address _spender, uint256 _value) external returns (bool success);
​
    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
​
}
```
The above is derived from eips.ethereum.org/EIPS/eip-20, the official proposal page for the ERC-20 standard. We will now examine each function:

### Name function

```solidity
name()
```

As the name might suggest, this function returns the name of the token. As an example, for the Wrapped LUX contract, this would return "Wrapped LUX".

### Symbol function

```solidity
symbol()
```

This function returns the ticker representation of the token. As an example, the United States Dollar usually has the ticker symbol "USD".  For Wrapped Lux, we have "WLUX".

### Decimals function
```solidity
decimals()
```

Perhaps the first unfamiliar topic here, decimals refers to the precision of the token. In Solidity, there is no support for floating point numbers (i.e. decimals) and therefore, any quantity must be represented as a whole number. 

To get around this intricacy, we can represent floating-point numbers by multiplying them with a large number to convert them into a whole number: Consider the following examples:

$$0.05 * 100 = 5$$
$$0.54367 * 100000 = 54367$$
$$0.3 * 10 = 3$$

Multiplying by a power of 10 is equivalent to shifting a number one place to the right. Therefore, for a quantity of token x (which could be a floating point number), we represent this value on-chain as x * 10^n, where n is a number greater than 0. Therefore, n is what decimals() would return.
For the rest of this section, we will refer to the following terms:
- Numerical Representation: a quantity of the token that has been converted from a floating-point number to a whole number (via multiplying by 10^n)

- User-Representation: a quantity of the token represented in its true form (i.e. floating-point representation)

### TotalSupply function
```solidity
totalSupply()
```
This function returns the total number of tokens in circulation. The number returned is in terms of the token numerical representation.

### BalanceOf function
```solidity
balanceOf(address _owner)
```

This function returns the balance of the address passed in as the argument. The number returned is in terms of the token numerical representation.

### Transfer function
```solidity
transfer(address _to, uint256 _value)
```

When called, this function transfer _value amount of tokens (in terms of the token numerical representation) from the function caller to _to. This function is successful if the balance of the caller is at least equal to _value. Furthermore, a successful call of this function should emit the following event:

```solidity
event Transfer(address indexed _from, address indexed _to, uint256 _value)
```

### TransferFrom function
```solidity
transferFrom(address _from, address _to, uint256 _value)
```

Before discussing the functionality of transferFrom(), we will first discuss the concept of allowances.

As we saw with the transfer() function, holders of tokens are able to transfer their tokens to other accounts. While this is function is sufficient for a large amount of use cases, consider protocols such as decentralized exchanges which allow users to swap tokens. Generally, the logic of swaps are as follows:

Take x of token A from the user

Give y of token B to the user

The limitations of the transfer() function is with regards to the first step of the logic above. With our current understanding of ERC-20, the swapper would first need to give the decentralized exchange the tokens it wants to exchange. Therefore, this would result in two transactions in order for the swap to be executed, something which is undesirable. 

ERC-20, therefore, introduces the concept of allowances. By giving another account permission to take a prespecified amount of your tokens, protocols such as decentralized exchanges are able to conduct behaviors like swaps in an atomic manner. 

Focusing back on transferFrom(), this function transfers _value amount of tokens (in terms of the token numerical representation) from _from to _to. For this function to be successful, _from must have previously allocated the function caller at least _value amount of tokens to spend on their behalf.

This function also emits the Transfer event seen previously. Furthermore, this function updates the amount of tokens that the caller is able to spend on behalf of _from.

### Approve function
```solidity
approve(address _spender, uint256 _value)
```

This function gives permission to _spender to spend at most _value tokens (in terms of the token numerical representation) from the balance of the function caller. If successful, this function emits the following event:

```solidity
event Approval(address indexed _owner, address indexed _spender, uint256 _value)
```

### Allowance function
```solidity
allowance(address _owner, address _spender)
```

This function returns the amount of tokens (in terms of the token numerical representation) that _spender is allowed to spend on behalf of _owner.

<Quiz quizId="520"/>
<Quiz quizId="521"/>

# Interacting with ERC20 Tokens (/academy/blockchain/solidity-foundry/07-erc20-smart-contracts/03-interacting-with-erc20-tokens)

---
title: Interacting with ERC20 Tokens
description: Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

In this section, we will go through an example of how to interact with an ERC-20 from another contract.

## Read Operations

Before calling any operations of an ERC-20 contract, we will need to have the following available:

- The ERC-20 interface
- The address of the ERC-20 token we want to interact with

Our starting Solidity file, therefore, will the following code:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
interface IERC20 {
    function name() external view returns (string memory);
    function symbol() external view returns (string memory);
    function decimals() external view returns (uint8);
    function totalSupply() external view returns (uint256);
    function balanceOf(address _owner) external view returns (uint256 balance);
    function transfer(address _to, uint256 _value) external returns (bool success);
    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);
    function approve(address _spender, uint256 _value) external returns (bool success);
    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```

```solidity
contract Test {
    address tokenAddress;
}
```

As a starter, let's write a function that gets the name of the token:

```solidity
contract Test {
    address tokenAddress;
  
    function getName() public view returns(string memory) {
      return IERC20(tokenAddress).name();
    }
}
```

Perhaps the only unfamiliar piece of syntax is in line 6. In Solidity, note the following:

- Contracts and interfaces are inherently types.
- We can wrap an address type into a contract/interface type. If the contract associated with the address

With the above in mind, the logic of getName is as follows:

- We call the function name at address token by wrapping the address type with the IERC20 interface
- name returns us the name of the token contract
- getName returns the name of the token contract

Just like that, we were able to call a read function of an ERC-20 contract. But what if we wanted to modify the state of an ERC-20 contract?

## Write Operations

In this example, we will look at calling the transferFrom function of an ERC-20 token contract. Recall that, if authorized, transferFrom allows us to transfer tokens from one account to another. As a starter, we have the following code:

```solidity
contract Test {
    address tokenAddress;
    address from;
    address to;
    uint amt;
  
    function getName() public view returns(string memory) {
      return IERC20(tokenAddress).name();
    }
  
    function doTransferFrom() public returns(bool) {
        return IERC20(tokenAddress).transferFrom(from, to, amt);
    }
}
```

In addition to adding additional state variables for context, we have also added the function doTransferFrom which calls the transferFrom function of the ERC-20 token contract. In particular, doTransferFrom returns the boolean returned by transferFrom, which represents whether if the function was successful or not. While the code above works, we can make it better by first checking if we are have been allocated enough tokens such that transferFrom(from, to, amt) will return true. To do this, we can make a call to the allowance function of the ERC-20 token contract. Our updated code is as follows:

```solidity
contract Test {
    address token;
    address from;
    address to;
    uint amt;
  
    function getName() public view returns(string memory) {
      return IERC20(token).name();
    }
  
    function doTransferFrom() public returns(bool) {
        if (IERC20(token).allowance(from, address(this) < amt) {
            return false;
        }
        return IERC20(token).transferFrom(from, to, amt);
    }
}
```

In line 13, we are passing in both the address of the spender and the address of our own smart contract to the allowance function, which returns the amount of allocated tokens which we compare to our amt variable. If we are have not been allocated enough tokens, we return false and therefore, we do not spend any additional computation resources calling transferFrom, which we know would have been unsuccessful.

<Quiz quizId="522"/>

# Deploying your own ERC20 Token (/academy/blockchain/solidity-foundry/07-erc20-smart-contracts/04-deploying-your-erc20-token)

---
title: Deploying your own ERC20 Token
description: Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

At this point of this chapter, you have become familiar with the design and implementation of the ERC-20 token standard. Still, you might have the following question: how does one actually go about deploying ERC-20 tokens? In this section, we will cover the following deployment methods:

- Custom Deployment
- OpenZeppelin Wizard Contract Deployer

## Custom Deployment

By custom deployment, we mean writing your own ERC-20 contract by hand. Right off the bat, this option offers the most customization as you are fully in control over the implementation details of your ERC-20 token. As long as you adhere to the ERC-20 token interface, your token is able to be used by any ERC-20 compatible protocol. However, consider the following downsides of writing your own ERC-20 token by-hand:

- Security: by writing your own custom code, you are putting your ERC-20 token at risk of being hacked by malicious actors. Even the best of programmers can fall victim to security vulnerabilities related to ERC-20 contracts!
- Gas Inefficiencies: it could be that while your contract is "correct," it may be expensive for users to interact with your ERC-20 contract.

The two reasons above, in additions to other small nuances, make it evident that writing your own ERC-20 token from scratch is not the best idea. This leads us to the other option:

## OpenZeppelin Wizard

OpenZeppelin's Wizard Contract Creator is a useful tool which allows for developers to deploy contracts on the fly. By this, we mean that by just filling a couple of fields and selecting a few options, we can autogenerate the code necessary to deploy a ERC-20 token to our liking! To get started, head over to [wizard.openzeppelin.com/#erc20](https://wizard.openzeppelin.com/#erc20) where you will see the following:




Front and center, you will see some Solidity code. At first, it seem as if this ERC20 contract OpenZeppelin has generated for us contains basically nothing. However, if you look closely, you will see that the MyToken contract that OpenZeppelin has generated for us inherits the ERC20, ERC20Permit contracts, which are defined and contain all the logic for our ERC-20 contract. This is the great part about the OpenZeppelin Wizard Contract Creator - we can easily modify our ERC-20 contract by inheriting the contracts whose functionalities we want. Therefore, as an example, let's create the following contract:


 
In the above, we've created a new ERC-20 contract named BigRedCoin. Furthermore, this ERC-20 token allocates to the deployer 20000 tokens on initialization and gives the owner full rights over the behavior of the token. Now that we have our ERC-20 token contract customized, how do we actually deploy it?

If you look at the righthand side of the Wizard page, you will see the button Copy to Clipboard. As the name might suggest, this allows us to copy our contract and paste it to a file in our Lux Starter Kit, which we can then compile and deploy onto the blockchain!


# Module 1A (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction)

---
title: Module 1A
description: Master the essential legal steps required to launch your Web3 project correctly and avoid common regulatory pitfalls
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

This module consists of two parts: 1A covers legal foundations, 1B covers security fundamentals.

### Disclaimer: Not Legal Advice 

Disclaimer: At the time of this writing, U.S. lawmakers were actively engaged in the creation of new laws that could impose brand new rules and regulations around not only the classification of tokens but the crypto industry as a whole. Always check the most current legal and regulatory guidelines in your jurisdiction before making a decision.

## About this module
This module equips you with the essential legal knowledge to successfully launch your Web3 project.

## Learning Outcomes
By the end of this module, you will learn how to:
- Select the optimal legal jurisdiction for your Web3 company
- Form the appropriate legal entity structure for your startup
- Classify your tokens correctly to avoid regulatory issues
- Create the necessary legal documentation for your Web3 project
- Protect your intellectual property effectively
- Implement compliant KYC and AML procedures
- Navigate data privacy regulations in the Web3 space

# Choosing Your Legal Jurisdiction (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/02-legal-jurisdiction)

---
title: Choosing Your Legal Jurisdiction
description: Learn how to select the right legal jurisdiction for your Web3 startup
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## The Foundation of Web3 Legal Compliance
Before launching any Web3 startup or token project, entrepreneurs must establish proper legal structures to protect themselves and ensure regulatory compliance. Unlike traditional startups, Web3 companies face unique challenges related to token classification, cross-border regulations, and evolving legal frameworks.

### Before You Launch: Legal Essentials for Web3 Founders

<YouTube id="3JwdBKxQk5Y" params="start=0&rel=0&modestbranding=1" /> 

### Choosing Your Legal Jurisdiction

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"The first step any Web3 organization needs to take is to choose the right legal jurisdiction -  or in other words - the place where you're going to register your legal entity. You don't need to live there. You don't need to work there, but this is the place where your business will be created."</span> - [Jonathan Rhodes](https://www.linkedin.com/in/jonathan-m-rhodes/), Founder and President at the Rhodes Companies
</div>
</Callout>

The first step for any Web3 organization is selecting the right legal jurisdiction. This decision impacts taxation, privacy, regulatory oversight, and access to funding.

The optimal jurisdiction depends on your project's goals, structure, and target markets—and should be chosen with both current requirements and long-term adaptability in mind. Startups should look for:

- Competitive tax frameworks
- Strong privacy protections
- Clear digital asset regulations
- Legislative support for Decentralized Autonomous Organizations (DAOs) and Decentralized Structures
- Efficient corporate registration and governance processes

### Forming Your Legal Entity
After selecting a jurisdiction, you'll need to form a legal entity. In the United States, most startups opt for a C Corporation structure, particularly if they plan to raise venture capital.

For Delaware incorporation, basic requirements include:
- Costs ranging from $50-$500 depending on setup details
- Filing a certificate of formation
- Designating a registered agent
- Submitting annual reports and tax filings

While Limited Liability Companies (LLCs) or partnerships might be suitable for some early-stage companies, the C Corp structure typically provides the most flexibility for fundraising and growth.



# Token Classification - Utility vs Security (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/03-token-classification)

---
title: Token Classification - Utility vs Security
description: Understanding the crucial distinction between utility and security tokens
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### Is It a Tool or a Security? Smart Token Design for Founders

<YouTube id="K4WCLw_59TE" params="start=0&rel=0&modestbranding=1" /> 

One of the most challenging aspects for Web3 projects is properly classifying their tokens. The distinction between utility tokens and security tokens is crucial from a regulatory perspective.

**Disclaimer**: At the time of this writing, U.S. lawmakers were actively engaged in the creation of new laws that could impose brand new rules and regulations around not only the classification of tokens but the crypto industry as a whole. Always check the most current legal and regulatory guidelines in your jurisdiction before making a decision.

The SEC uses a four-part test (the Howey Test) to determine if a token is a security:
1. Is there an investment of money?
2. Is it in a common enterprise?
3. Is there a reasonable expectation of profit?
4. Does the profit come from the efforts of others?

If your token meets all four criteria, it's likely to be classified as a security and subject to SEC registration requirements. If your aim is to design a token that is classified as a utility rather than a security, here are five aspects to focus on:
- Focus on function rather than fundraising
- Make your token immediately usable (not speculative)
- Avoid profit sharing and dividends
- Refrain from speculative marketing language
- Implement decentralized control



# Essential Legal Documentation (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/04-legal-documentation)

---
title: Essential Legal Documentation
description: Core legal documents required for Web3 startups
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### Essential Legal Documentation
Web3 startups require several core legal documents, including:
- Terms of use
- Privacy policies
- Token sale agreements
- Investment agreements
- White papers
- DAO governance documents

These documents should be drafted with the assistance of legal counsel familiar with blockchain technology and relevant regulations.


# Intellectual Property (IP) Protection (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/05-intellectual-property)

---
title: Intellectual Property (IP) Protection
description: Protecting your intellectual property & data privacy considerations
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Protecting your intellectual property is essential in the Web3 space. Implement a three-layered approach:
1. Legal protections: Trademarks for your product name and logo, Copyrights, Source code registration
2. Security measures: Ensure you have sufficient encryption and access controls in place to protect your intellectual property.
3. Contractual agreements: All team members, contractors, and partners should sign non-disclosure agreements (NDAs) and confidentiality agreements before you start work with them.

Initial IP protection should be considered in your first fundraising round.

### Data Privacy Considerations

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Remember that anonymity of your users does not equal compliance because even pseudonames are not exempt since they can be traced back to a user's identity."</span> - Jonathan Rhodes, Founder and President at the Rhodes Companies
</div>
</Callout>

### Founders & Privacy: Navigating Data Rules in a Decentralized World

<YouTube id="f2blB3KQXxA" params="start=0&rel=0&modestbranding=1" /> 

Data privacy considerations play a crucial role in Web3 projects, with General Data Protection Regulation (GDPR) serving as the benchmark standard globally. On-chain wallet addresses are likely considered personal information under these frameworks.

Projects should only collect necessary information, clearly communicate usage in privacy policies, and consider server localization requirements. Special attention should be paid to tracking and metrics implementations.


# Ongoing Compliance Requirements (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/06-ongoing-compliance)

---
title: Ongoing Compliance Requirements
description: Maintaining compliance after launch
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

After launch, maintaining compliance is critical. This includes:
- Know Your Customer (KYC) procedures
- Anti-Money Laundering (AML) protocols
- Data privacy compliance (GDPR,  California Consumer Privacy Act - CCPA, etc.)
- Tax compliance for crypto transactions

### Simple Steps to Web3 Compliance

<YouTube id="ZduSddrGicM" params="start=0&rel=0&modestbranding=1" /> 

## Why Legal Structures Matter for Web3 Startups
Proper legal structuring is not just about compliance—it's about creating a foundation for sustainable growth. Common mistakes that can lead to serious legal issues include:

1. **Misclassifying tokens**: Incorrectly labeling a security as a utility token can trigger Securities and Exchange Commission (SEC) enforcement actions.
2. **Operating without a legal entity**: This exposes founders to personal liability and complicates banking, taxes, and property management.
3. **Neglecting compliance requirements**: Failing to implement KYC/AML procedures can result in regulatory penalties.
4. **Making investment-style promises**: Even with a utility token, marketing language suggesting investment returns can trigger securities regulations.
5. **Inadequate IP protection**: Without proper agreements, especially when working with contractors or anonymous developers, you risk losing ownership of your product.



# Applying Legal Frameworks to Your Web3 Startup (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/07-applying-frameworks)

---
title: Applying Legal Frameworks to Your Web3 Startup
description: Step-by-step guide to implementing legal structures
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Here is a breakdown on how to apply legal frameworks:

### Step 1: Choose Your Jurisdiction Strategically
Consider factors like regulatory clarity, tax implications, and ease of operation. Budget for initial registration costs.

### Step 2: Form Your Legal Entity
For most Web3 startups seeking investment, a Delaware or Wyoming C Corporation provides the optimal structure. Allocate budget for comprehensive legal documentation.

### Step 3: Design Your Token with Compliance in Mind
If creating a utility token, ensure it has immediate functionality within your ecosystem and avoid language suggesting investment returns.

### Step 4: Implement Proper Documentation
Work with legal counsel to create all necessary agreements and policies before launch.

### Step 5: Protect Your Intellectual Property
Register trademarks, establish copyright protections, and create proper IP agreements with all team members and contractors.

### Step 6: Set Up Compliance Systems
Use third-party compliance-as-a-service platforms to handle KYC/AML requirements efficiently. These platforms offer plug-and-play APIs for identity verification, sanctions screening, and fraud detection.

### Step 7: Create Data Privacy Frameworks
Develop privacy policies and protocols that comply with relevant regulations like GDPR or CCPA, even if you're only collecting wallet addresses.


# Key Take-Aways (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/08-key-takeaways)

---
title: Key Take-Aways
description: Essential points to remember about legal structures for Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

1. **Start with the right legal foundation**: Select a jurisdiction that supports Web3 innovation.

2. **Budget appropriately for legal setup**: Allocate sufficient funds for initial legal documentation and IP protection.

3. **Be meticulous about token classification**: Consult legal experts to determine if your token is a utility or security before launch.

4. **Protect your intellectual property**: Implement comprehensive IP protections, especially when working with contractors or open-source contributors.

5. **Simplify compliance**: Use third-party platforms to handle KYC/AML requirements rather than building these systems from scratch.

6. **Consider regulation**: If offering security tokens, evaluate a pathway for compliant fundraising.

7. **Review local jurisdiction requirements**: Different regions have varying approaches to crypto regulation—understand the implications for your specific project.


# Flashcards (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/09-flashcards)

---
title: Flashcards
description: Key terms and definitions for legal structures in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 1A: Legal Foundations for Web3 Startups

Use these flashcards to revise your knowledge of some of the most important concepts of the Legal Foundations module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="legal-foundations" quizUrl="/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/10-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/10-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of legal structures for Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="906" />

<Quiz quizId="907" />

<Quiz quizId="908" />

Great work finishing **[Module 1A](/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction)**! 🎉 Completing a single module is a fantastic achievement on its own, but if you want to be certified, you'll need to complete [Module 1A](/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction), [Module 1B](/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/01-introduction), [Module 2](/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction), and [Module 3](/academy/entrepreneur/foundations-web3-venture/03-user-personas/01-introduction) to unlock the Foundations of a Web3 Venture certificate. Keep going—you're on your way! 🚀


# Module 1B (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/01-introduction)

---
title: Module 1B
description: Learn essential security practices to protect your Web3 startup from common vulnerabilities and threats
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module
Master key security practices to safeguard your Web3 startup against common threats and vulnerabilities.

## Learning Outcomes
By the end of this module, you will learn how to:
- Assess your project's technical and security readiness as a non-technical founder
- Implement key components of IT governance that early-stage startups often overlook
- Establish best practices for managing private keys, admin privileges, and wallets
- Make informed decisions about on-chain versus off-chain data storage to mitigate risks
- Maintain user privacy without over-engineering your security infrastructure

## Why Security Matters for Web3 Startups

The Web3 ecosystem presents unique security challenges. Unlike traditional applications, blockchain projects often manage digital assets directly, making security not just a best practice but an essential business requirement. A single security breach can lead to irreversible loss of funds, damaged reputation, and potential regulatory consequences.


# Assessing Your Project's Security Readiness (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/02-assessing-security)

---
title: Assessing Your Project's Security Readiness
description: How non-technical founders can evaluate their project's security
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Assessing Tech & Security as a Non-Technical Founder

<YouTube id="XAlehND610k" params="start=0&rel=0&modestbranding=1" />

For non-technical founders, evaluating your project's security systems may seem daunting. However, you can take practical steps to ensure robustness without deep technical knowledge:

1. **Rely on third-party security assessments**: External security audits provide valuable data points, especially for projects that will primarily live on blockchain.

2. **Implement vulnerability discovery programs**: Bug bounty programs or responsible disclosure systems create additional channels for identifying security issues before they become problems.

3. **Use security testing tools**: Leverage established security testing solutions as part of your development process.

4. **Prioritize security in leadership**: Ensure your technical leadership has security experience and fosters a security-conscious culture.

5. **Examine change management practices**: Understand how code moves from development to production, with security checks at each stage.

6. **Identify third-party dependencies**: Map all external libraries, services, and vendors your system relies on, as these form part of your overall security posture.

7. **Learn from industry incidents**: Stay informed about security incidents in the ecosystem and discuss with your team how similar issues might affect your project.


# Building Strong IT Governance (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/03-it-governance)

---
title: Building Strong IT Governance
description: Key components of IT governance for Web3 startups
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## IT Governance Gaps in Early-Stage Web3 Projects

<YouTube id="8_SfBXGDGa0" params="start=0&rel=0&modestbranding=1" /> 

### Key Components of IT Governance

Three critical governance components frequently overlooked by early-stage startups are:

### 1. Access Management

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Access management is by far one of the most important components to take into account and to make sure that those are done right from the very beginning"</span> - [Martin Prado](https://www.linkedin.com/in/martinprado/), Chief Information Security Officer at Lux Network
</div>
</Callout>

Access management determines who can access what resources within your organization. Many security incidents result from unauthorized access or overly lax permissions.

**Implementation tips:**
- Create a clear role-based access matrix for onboarding and offboarding
- Conduct regular access reviews
- Pay special attention to privileged accounts and credentials
- Implement the principle of least privilege

### 2. Change Management

Change management covers the entire process from writing code to deploying it in production. Without proper security integration, this process can introduce vulnerabilities.

**Implementation tips:**
- Map your entire development pipeline from code writing to production
- Ask yourself: "If this component is compromised, could it put the production environment at risk?"
- Implement approval processes for code changes on GitHub or GitLab
- Include security testing in your deployment pipelines

### 3. Vendor Management

With the rise of supply chain attacks, understanding and managing the security of your third-party dependencies has become crucial.

**Implementation tips:**
- Identify all third parties your system depends on
- Request security documentation like SOC2 reports or ISO 27001 certifications
- Evaluate the security posture of critical vendors
- Monitor for security incidents affecting your dependencies


# Secure Management of Cryptographic Assets (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/04-cryptographic-assets)

---
title: Secure Management of Cryptographic Assets
description: Best practices for managing private keys, admin privileges, and wallets
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Managing Private Keys, Admin Privileges, and Wallets

<YouTube id="3bINYz4-stM" params="start=0&rel=0&modestbranding=1" /> 

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"The ideal situation involves private key material being kept offline, encrypted, and ideally split into different charts."</span> - [Martin Prado](https://www.linkedin.com/in/martinprado/), Chief Information Security Officer at Lux Network
</div>
</Callout>

For blockchain projects, cryptographic key management is fundamental to security. Follow these best practices:

1. **Follow established standards**: The Cryptocurrency Security Standard (currently version 9) provides comprehensive guidance for key material management.

2. **Keep private keys secure**:
   - Store keys offline when possible
   - Always encrypt private key material
   - Consider splitting keys into different shards
   - Use Hardware Security Modules (HSMs) for enhanced protection

3. **Implement strict admin privilege controls**:
   - No one should have admin rights by default
   - Use a "breaking glass" mechanism requiring approval from stakeholders for privilege escalation
   - Remember that risk = rights × time (minimize both)


# Data Strategy and Privacy (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/05-data-strategy)

---
title: Data Strategy and Privacy
description: On-chain vs off-chain data considerations and privacy principles
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### On-Chain vs. Off-Chain Data Considerations

<YouTube id="aUZTJ6QeOjE" params="start=0&rel=0&modestbranding=1" /> 

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"You should treat off-chain data as trustless, which means that you cannot rely on data off-chain. But you can have some kind of proof of computation or some kind of proof of validity of that data on-chain"</span> - [Martin Prado](https://www.linkedin.com/in/martinprado/), Chief Information Security Officer at Lux Network
</div>
</Callout>

When deciding where to store data, consider:

- **On-chain storage** is appropriate for:
  - Immutable, transparent, censorship-resistant data
  - Token information
  - Ownership records (like Non-Fungible Tokens - NFTs)
  - Deterministic logic

- **Off-chain storage** is better for:
  - Most other types of data
  - Cost-efficient storage
  - Easier processing

A hybrid approach often works best: store data off-chain but keep proofs of validity on-chain. Zero-Knowledge Proofs are an emerging solution in this space.

### Privacy Principles

To maintain user privacy:
- Only collect information you actually need
- Assess the nature of the data you're collecting
- Keep on-chain complexity to a minimum
- Plan for potential future migration between on-chain and off-chain storage
- Balance security, cost, and performance requirements


# Key Take-Aways (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/06-key-takeaways)

---
title: Key Take-Aways
description: Essential security principles for Web3 startups
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

1. **Start with a security mindset**: Build security into your project from day one rather than trying to add it later.

2. **Focus on fundamentals first**: Implement strong access management, change management, and vendor management practices before investing in expensive security tools.

3. **Protect cryptographic keys rigorously**: Follow the Cryptocurrency Security Standard, use HSMs when possible, and implement multi-signature approval processes.

4. **Be strategic about data storage**: Make deliberate decisions about what goes on-chain versus off-chain based on immutability needs, cost considerations, and privacy requirements.

5. **Plan for evolution**: Design your systems to allow for future changes in your security and data architecture as your project grows and technology advances.


# Flashcards (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/07-flashcards)

---
title: Flashcards
description: Key security terms and definitions for Web3 startups
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---
import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 1B: Security Fundamentals for Web3 Startups

Use these flashcards to revise your knowledge of some of the most important concepts of the Security Fundamentals module -- after, you will be ready to take the quiz.

<Flashcard flashcardSetId="security-fundamentals" quizUrl="/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/08-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/08-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of security fundamentals for Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="909" />

<Quiz quizId="910" />

<Quiz quizId="911" />

<Quiz quizId="912" />

<Quiz quizId="913" />

Great work finishing **[Module 1B](/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/01-introduction)**! 🎉 Completing a single module is a fantastic achievement on its own, but if you want to be certified, you'll need to complete [Module 1A](/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction), [Module 1B](/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/01-introduction), [Module 2](/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction), and [Module 3](/academy/entrepreneur/foundations-web3-venture/03-user-personas/01-introduction) to unlock the Foundations of a Web3 Venture certificate. Keep going—you're on your way! 🚀


# Module 2 (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction)

---
title: Module 2
description: Learn how to create an effective Business Model Canvas that will guide your Web3 startup to success
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module

Discover how to design a powerful Business Model Canvas to shape and scale your Web3 startup.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"The Business Model Canvas is a really fundamental and important tool for any early stage founder to design and leverage as sort of the starting foundation for their company and where they believe it to be going"</span> - [Michael Martin](https://www.linkedin.com/in/michaeltmartin/), Codebase Lead at Lux Network
</div>
</Callout>

## Learning Outcomes
By the end of this module, you will learn how to:
- Apply the Business Model Canvas specifically to Web3 and decentralized projects
- Define your target audience with precision to avoid strategic missteps
- Identify unique value capture mechanisms for Web3 businesses
- Avoid common pitfalls when creating your business canvas
- Develop sustainable revenue strategies beyond token speculation


# Understanding the Business Model Canvas for Web3 (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/02-understanding-canvas)

---
title: Understanding the Business Model Canvas for Web3
description: Learn how the Business Model Canvas applies to Web3 and decentralized projects
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="QuGq7X4v77M" params="start=0&rel=0&modestbranding=1" /> 

Discover how to design a powerful Business Model Canvas to shape and scale your Web3 startup.

The Business Model Canvas serves as a fundamental tool for early-stage founders, providing a structured framework to articulate core assumptions about target audiences, value propositions, and sustainability strategies. The Business Model Canvas for Web3 does not fundamentally differ from traditional canvases but expands the definition of "customer" and includes unique value-capture mechanisms.

### The Web3 Business Model Canvas Explained

The Business Model Canvas helps companies establish a solid foundation by organizing their thinking around key business elements. For Web3 founders, this tool remains essential but requires expanded thinking about certain components.

In the Web3 context, the definition of "customer" extends beyond traditional consumers to include token holders, community members, followers on social platforms, and contributors to open-source projects. This broader perspective helps founders identify all potential stakeholders who will interact with their product or service.

Web3 businesses also have unique value capture mechanisms that should be reflected in the canvas. These include tokenomics strategies, treasury management approaches, and yield generation methods. Despite these differences, the fundamental questions remain the same: how do you reach your customers, how do you provide them value, and how do you sustain your business?

### How a Business Canvas can Help Web3 Start-Ups 

<YouTube id="gh1CODgMZ8s" params="start=0&rel=0&modestbranding=1" /> 

One major advantage of the Business Model Canvas is that it helps founders become more specific about their target audience. Rather than broadly stating "our customer is a developer," the canvas encourages detailed demographic and psychographic definitions. For example, a more precise definition might be "our customer is a Solidity developer working at Series A companies in the tax strategy sector." This specificity prevents founders from pursuing unproductive paths and facilitates more meaningful conversations with potential users.

### Why This Matters for Web3 Startups

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"'If you build it they will come is not a strategy.' That is a maxim that I would argue does not hold real weight."</span> - [Michael Martin](https://www.linkedin.com/in/michaeltmartin/), Codebase Lead at Lux Network
</div>
</Callout>

The Business Model Canvas is particularly important for Web3 startups because of the complex nature of decentralized business models. Without a clear understanding of who your users are and how you'll provide value, it's easy to fall into the trap of viewing tokens merely as speculative tools rather than representations of real value.

## Common Pitfalls to Avoid in Web3 Business Model Canvases

<YouTube id="6e5UUNT7F7w" params="start=0&rel=0&modestbranding=1" /> 

Web3 founders must remember that sustainable businesses solve genuine pain points for users. The token itself is just a tool—not the product. By focusing on user needs first and token mechanics second, founders can build businesses that create lasting value rather than temporary speculation.

Additionally, the canvas helps founders avoid the "if you build it, they will come" fallacy. User acquisition requires strategic planning, and building features without customer validation wastes valuable resources. Understanding your target users in detail allows you to develop the minimum viable product that addresses their specific needs before expanding into additional features.


# Applying the Canvas to Your Web3 Startup (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/03-applying-canvas)

---
title: Applying the Canvas to Your Web3 Startup
description: Step-by-step guide to implementing the Business Model Canvas for your Web3 project
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

To effectively apply the Business Model Canvas to your Web3 startup:

1. **Define your customers precisely**: Include detailed demographics and psychographics for all potential stakeholders, including token holders, community members, and contributors.

2. **Articulate your value proposition**: Clearly state how your product solves a specific problem for your target audience.

3. **Map your channels**: Identify how you'll reach your customers, considering both Web3-native channels and traditional marketing approaches.

4. **Plan for sustainability**: Never leave the revenue or cost sections blank. Even early-stage Web3 startups need to consider how they'll generate revenue and manage costs from day one.

5. **Consider value capture mechanisms**: Detail your tokenomics, treasury strategy, or other Web3-specific approaches to capturing value.

6. **Test your assumptions**: Use the canvas to identify assumptions that need validation through customer conversations and market research.

7. **Iterate based on feedback**: Be prepared to revise your canvas as you gather more information about your customers and their needs.

Working with mentors or team members to review your canvas can help pressure-test your assumptions and provide valuable feedback. This collaborative approach ensures you're as specific as possible about your target audience and value proposition.


# Key Take-Aways (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/04-key-takeaways)

---
title: Key Take-Aways
description: Essential points to remember about Business Model Canvas for Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

- **Be specific about your target audience**: Avoid broad definitions and drill down into detailed demographics and psychographics.

- **Focus on solving real problems**: Your primary goal should be providing value to users, not creating a speculative token.

- **Consider multiple stakeholders**: In Web3, your "customers" may include token holders, community members, and contributors.

- **Plan for revenue from day one**: Even with an evolving business model, you need to consider sustainability strategies early.

- **Validate before building**: Talk to potential users and understand their needs before developing extensive features.

- **Iterate based on feedback**: Use the canvas as a living document that evolves as you learn more about your market.


# Flashcards (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/05-flashcards)

---
title: Flashcards
description: Key terms and definitions for Business Model Canvas in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 2: Business Model Canvas for Web3 Founders

Study these key terms and concepts to solidify your understanding of the Business Model Canvas for Web3 projects.

Use these flashcards to revise your knowledge of some of the most important concepts of the Business Model Canvas module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="business-model-canvas" quizUrl="/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/06-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/06-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of Business Model Canvas for Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="914" />

<Quiz quizId="915" />

<Quiz quizId="916" />

<Quiz quizId="917" />

<Quiz quizId="918" />

Awesome progress! **[Module 2](/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction)** is done, which is a big win. Remember, while completing a single module is great, certification comes when you finish [Module 1A](/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction), [Module 1B](/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/01-introduction), [Module 2](/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction), and [Module 3](/academy/entrepreneur/foundations-web3-venture/03-user-personas/01-introduction) and unlock the Foundations of a Web3 Venture certificate. Stay focused! 🌟


# Additional Learning (/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/07-additional-learning)

---
title: Additional Learning
description: Resources for further exploration of Business Model Canvas concepts
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

"[Business Model Questions](https://conversisconsulting.com/wp-content/uploads/2011/09/business-model-questions.pdf)" by Thomas Eisenmann

[The New Vertical SaaS Playbook](https://www.thetimes.blog/p/the-new-vertical-saas-playbook) (The Times Blog)


# Module 3 (/academy/entrepreneur/foundations-web3-venture/03-user-personas/01-introduction)

---
title: Module 3
description: Learn to recognize, analyze, and connect with Web3 users to create solutions that truly solve their challenges
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module

Learn to recognize, analyze, and connect with Web3 users to create solutions that truly solve their challenges.

## Learning Outcomes

By the end of this module, you will learn how to:
- Define and create effective User Personas for Web3 startups
- Find and engage with potential users in the blockchain ecosystem
- Extract honest, actionable feedback from user conversations
- Implement user feedback systematically to improve your product
- Maintain sustainable user relationships that drive organic growth

## Introduction to User Personas in Web3

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"User Personas are a really key part of the early stages of your company, and I'd argue that they are the most important part. Your product cannot exist in a meaningful, sustainable way unless you understand who your users are."</span> - [Michael Martin](https://www.linkedin.com/in/michaeltmartin/), Codebase Lead at Lux Network
</div>
</Callout>

### What Are User Personas?

<YouTube id="pQhdC_KMXRM" params="start=0&rel=0&modestbranding=1" /> 

User Personas are detailed profiles of your ideal users that help you understand their needs, behaviors, and pain points. In Web3, personas are particularly important because users interact with products differently than in traditional applications—often pseudonymously and with multiple roles (token holders, contributors, governance participants).

Creating accurate personas requires understanding where your blockchain solution genuinely solves problems, rather than just applying technology for the sake of following a trend. Effective personas help you build products that address specific needs in communities where traditional systems aren't working.

## The Role of User Personas in Web3's Pseudonymous World

<YouTube id="cWdSz2JuJAM" params="start=0&rel=0&modestbranding=1" /> 

# Finding Your First Web3 Users (/academy/entrepreneur/foundations-web3-venture/03-user-personas/02-finding-first-users)

---
title: Finding Your First Web3 Users
description: How to identify and reach potential users in the blockchain ecosystem
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

The first step in building successful Web3 products is identifying communities that actually need blockchain technology—not where it's merely trendy, but where people lack visibility, access, or ownership.

## Finding Your First Users

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"We live in a very noisy and loud space, where the community of our users typically has some sort of direct access to the founders and developers of products, whether that's a Discord, whether a Telegram channel, whether that's on X as the public forum."</span> - [Michael Martin](https://www.linkedin.com/in/michaeltmartin/), Codebase Lead at Lux Network
</div>
</Callout>

<YouTube id="z5aG5NAE7Ew" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Ludovica Rosi, Founder and CEO of <a href="https://zeroone.art/?view=list" target="_blank" rel="noopener noreferrer" style={{ color: '#0066cc', textDecoration: 'underline' }}>Zeroone</a>
</p>

These communities often form in places like Discord, Telegram, and Twitter/X, where incentivized early adopters gather to discuss new solutions to their problems. A strategic approach is to start with geographic targeting, then narrow down to specific industries or sectors within that area.

When searching for your first users, look for places where traditional systems aren't serving people well—these are the communities most receptive to blockchain-based alternatives.


# Asking the Right Questions (/academy/entrepreneur/foundations-web3-venture/03-user-personas/03-asking-right-questions)

---
title: Asking the Right Questions
description: How to validate your Web3 idea through effective user conversations
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="gF_ru5D2Eh8" params="start=0&rel=0&modestbranding=1" /> 

When engaging with potential users, focus on understanding:
- What problems they're experiencing with current solutions
- What gaps exist in current offerings
- What similar tools they're using as workarounds

Remember that while listening to complaints is valuable, successful founders also anticipate needs users haven't yet articulated. The most impactful products often create new behaviors rather than just addressing existing complaints.

The real opportunity lies in creating solutions users haven't yet imagined.

### Getting Honest Feedback

<YouTube id="0dTHoX-69pA" params="start=0&rel=0&modestbranding=1" /> 

To ensure users provide honest feedback rather than just being polite, build a collaborative culture where they feel like partners in your project. Position them as collaborators and ambassadors rather than just test subjects.

When users feel invested in your product's success, they become more willing to provide critical feedback because they genuinely want the product to improve—both for themselves and so they can recommend it to others.

Engaged users will be patient with bugs and development issues, but will also apply healthy pressure to fix problems that might prevent wider adoption.



# Why User Engagement Matters in Web3 (/academy/entrepreneur/foundations-web3-venture/03-user-personas/04-why-engagement-matters)

---
title: Why User Engagement Matters in Web3
description: Understanding the unique relationship between builders and users in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

In Web3, the relationship between builders and users is fundamentally different from Web2 . The decentralized nature of blockchain projects means users often have multiple roles—they might be customers, token holders, and governance participants simultaneously.

This creates both challenges and opportunities. While managing these overlapping personas requires careful attention, it also creates powerful alignment incentives when done correctly.

The community-driven nature of Web3 projects means founders must spend significantly more time on outbound customer discovery, especially in the early stages. This is because user feedback doesn't just inform product development; it often shapes governance and tokenomics as well.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"What is unscalable sometimes actually leads to something that is organic, and there is nothing better in my opinion than organic growth, especially in the first two to three years of your company"</span> - Ludovica Rosi, CEO and Founder of zeroone
</div>
</Callout>

# Implementing a User Engagement Strategy (/academy/entrepreneur/foundations-web3-venture/03-user-personas/05-engagement-strategy)

---
title: Implementing a User Engagement Strategy
description: Practical approaches to building and maintaining user relationships
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Direct Communication Approach

<YouTube id="U0-HZ-ZAY0E" params="start=0&rel=0&modestbranding=1" /> 

While scalability is a core blockchain value, successful founders often take an "unscalable" approach to early user relationships. This means:

- Personally engaging with users daily 
- Conducting regular check-in calls 
- Making users feel like team members rather than just customers

This high-touch approach builds strong retention because users feel personally invested in the project's success. When users know the founders and understand the company's ethos, they're less likely to abandon the product during inevitable challenges.

## Staying Connected To Your Users

<YouTube id="vD3tmqhhTek" params="start=0&rel=0&modestbranding=1" /> 

### Systematic Feedback Processing

To make user feedback actionable:

1. Document all inputs and organize them systematically
2. Track how many users mention the same issues
3. Cross-reference with product data to confirm patterns
4. Analyze the time investment vs. potential impact of changes
5. Prioritize high-impact changes that require minimal time

This systematic approach not only improves your product but also encourages continued feedback when users see their suggestions implemented.

### Customer Interview Best Practices

When conducting interviews:
- Focus on "cold" users rather than friends who might sugarcoat feedback
- Contact new users within 2-3 minutes of sign-up for highest engagement
- Use silence strategically to make interviewees comfortable and honest
- Follow up with a sequence: Call → Voicemail → Text if needed
- Always ask: "Is there anything I didn't ask that I should have?"

The goal is to listen, allowing users to express their true needs rather than confirming your assumptions.


# Key Take-Aways (/academy/entrepreneur/foundations-web3-venture/03-user-personas/06-key-takeaways)

---
title: Key Take-Aways
description: Essential principles for user engagement in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

1. **Find meaningful use cases**: Focus on communities where blockchain genuinely solves problems around visibility, access, or ownership—not where it's just trendy.

2. **Engage personally**: Invest time in direct relationships with users, making them feel like collaborators rather than just customers.

3. **Document systematically**: Create a structured process for collecting, analyzing, and prioritizing user feedback.

4. **Implement visibly**: Show users their feedback matters by quickly implementing high-impact, low-effort changes.

5. **Be ready to pivot**: The most successful founders maintain the ability to reinvent their approach when user feedback indicates a different direction.

6. **Balance listening and leading**: While user feedback is essential, also recognize opportunities to create needs users haven't yet imagined.


# Flashcards (/academy/entrepreneur/foundations-web3-venture/03-user-personas/07-flashcards)

---
title: Flashcards
description: Key terms and definitions for User Personas in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 3: User Personas in Web3 - Finding and Engaging Your Target Audience

Use these flashcards to revise your knowledge of some of the most important concepts of the User Personas module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="user-personas" quizUrl="/academy/entrepreneur/foundations-web3-venture/03-user-personas/08-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>



# Test Your Knowledge (/academy/entrepreneur/foundations-web3-venture/03-user-personas/08-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of User Personas in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="919" />

<Quiz quizId="920" />

<Quiz quizId="921" />

<Quiz quizId="922" />

Congratulations! You've completed **[Module 3](/academy/entrepreneur/foundations-web3-venture/03-user-personas/01-introduction)**! 🎉 If you've also finished [Module 1A](/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction), [Module 1B](/academy/entrepreneur/foundations-web3-venture/01b-security-fundamentals/01-introduction), and [Module 2](/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction), you've now unlocked the **Foundations of a Web3 Venture** certificate! Head to your Builder's Hub profile to download it. Amazing work! 🚀


# Additional Learning (/academy/entrepreneur/foundations-web3-venture/03-user-personas/09-additional-learning)

---
title: Additional Learning
description: Resources for further exploration of user research
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

[User Interviews 101 (NN/g)](https://www.nngroup.com/articles/user-interviews/) - Nielsen Norman Group

[The "Mom Test" Book](https://www.momtestbook.com/) - Rob Fitzpatrick

Did you complete [Module 1](/academy/entrepreneur/foundations-web3-venture/01-legal-foundations/01-introduction), [Module 2](/academy/entrepreneur/foundations-web3-venture/02-business-model-canvas/01-introduction), and [Module 3](/academy/entrepreneur/foundations-web3-venture/03-user-personas/01-introduction)? Congratulations! Claim your free "**Foundations of a Web3 Venture**" certificate.

# What is x402? (/academy/blockchain/x402-payment-infrastructure/02-introduction/01-what-is-x402)

---
title: What is x402?
description: Understanding the x402 protocol and HTTP 402 activation for internet-native payments.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: BookOpen
---

## Introduction

The x402 protocol is an open standard that activates the HTTP 402 "Payment Required" status code, enabling instant, permissionless payments directly through HTTP requests. This revolutionary approach makes payments a native part of internet communication, eliminating the friction associated with traditional payment systems.

## HTTP 402: A Long-Awaited Activation

The HTTP 402 status code has existed since the early days of the internet but was never fully implemented. It was reserved for "future use" as a way to require payment before accessing content or services. The x402 protocol finally brings this vision to life by:

- **Activating HTTP 402**: Making payment a standard HTTP response code
- **Blockchain Settlement**: Using blockchain technology for instant, permissionless transactions
- **Open Protocol**: Anyone can implement or extend the standard

## How x402 Works

At its core, x402 transforms how payments are requested and fulfilled on the web:

1. **Client Requests Resource**: A user or AI agent sends an HTTP request to access content or an API endpoint
2. **Server Returns 402**: Instead of returning the content, the server responds with HTTP 402 "Payment Required"
3. **Payment Submitted**: The client automatically pays using stablecoins (like USDC) on the blockchain
4. **Access Granted**: Once payment is confirmed, the server releases the requested content

This entire process happens in approximately 2 seconds, creating a seamless payment experience.



## Key Characteristics

### Open and Permissionless

Unlike traditional payment systems that require:
- Creating accounts
- Completing KYC verification
- Managing API keys
- Setting up merchant accounts

x402 requires **none of these**. Anyone can start accepting payments immediately by implementing the protocol.

### Instant Settlement

Traditional payment systems can take days to settle transactions. x402 settles payments in approximately 2 seconds, enabled by blockchain technology and Lux's fast finality.

### Zero Protocol Fees

There are no protocol-level fees with x402. The cost structure is:

**For Users (Payers)**:
- **\$0 gas fees** - completely gasless for end users
- No subscription fees
- No processing fees
- Only pay the actual payment amount

**For Facilitators**:
- Minimal blockchain gas fees (~\$0.001 per transaction on Lux with current network conditions)
- Facilitators sponsor gas on behalf of users using EIP-3009 gasless payments

This gasless model means users don't need to hold LUX or any native blockchain tokens - they only need the payment token (like USDC).

### HTTP-Native

x402 integrates directly with HTTP, making it compatible with existing web infrastructure. Developers can add payment requirements to their APIs with minimal code changes, often just one line of middleware.

## Why x402 Matters

The x402 protocol enables entirely new business models and use cases:

- **AI-to-AI Payments**: AI agents can autonomously pay for services without human intervention
- **Micropayments**: Charge fractions of a cent per API request or piece of content
- **Pay-Per-Use**: Users only pay for what they consume, no subscriptions required
- **Instant Monetization**: Developers can monetize APIs and services immediately

## x402 vs Traditional Payments

| Feature | Traditional Payments | x402 Protocol |
|---------|---------------------|---------------|
| Setup Time | Days to weeks | Minutes |
| Settlement | 2-7 days | ~2 seconds |
| Protocol Fees | 2-3% + fixed fees | ~\$0.001 gas |
| KYC Required | Yes | No |
| Account Required | Yes | No |
| API Keys | Required | Optional |
| Micropayments | Not feasible | Optimized |
| Autonomous Payments | Not possible | Native support |

## The Protocol Ecosystem

x402 is supported by an ecosystem of **facilitators**—services that handle payment verification and submission on behalf of merchants. These facilitators:

- Verify payment authenticity
- Submit transactions to the blockchain
- Handle settlement with merchants
- Provide developer tools and SDKs

Popular facilitators on Lux include Thirdweb x402, PayAI, Ultravioleta DAO, and x402-rs. [You can explore all available facilitators](/integrations#x402). We'll explore these in detail in later lessons.

## Summary

The x402 protocol activates HTTP 402 to enable instant, permissionless, HTTP-native payments. By leveraging blockchain technology, x402 eliminates the friction of traditional payment systems while enabling new use cases like AI agent payments and micropayments. With approximately 2-second settlement, zero protocol fees, and no account requirements, x402 is revolutionizing how we think about internet payments.

## Additional Resources

- [x402.org](https://www.x402.org/) - Official x402 protocol website
- [x402 Whitepaper](https://www.x402.org/x402-whitepaper.pdf) - Technical specification
- [GitHub Repository](https://github.com/coinbase/x402) - Open source implementation

<Quiz quizId="5001"/>


# The Traditional Payment Problem (/academy/blockchain/x402-payment-infrastructure/02-introduction/02-payment-problem)

---
title: The Traditional Payment Problem
description: Understanding the limitations and friction points of traditional payment systems.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: TriangleAlert
---

## The Payment Friction Problem

Traditional payment systems create significant friction for both users and developers, especially when dealing with digital services, APIs, and content. This friction manifests in multiple ways, making it difficult to implement efficient payment models for modern applications.

## The Five-Step Friction Model

Every traditional payment interaction requires users to complete at least five time-consuming steps:

- **Creating Account**: requires signing up, verifying email address and setting up password (eta 5-15 minutes)
- **Add Payment Methods**: enter credit card details and complete bank verification (eta 3-10 minutes)
- **Complete KYC**: submit government-issued ID, proof of address and wait for approval (eta hours to days)
- **Buy Credits or Subscribe**: commit to minimum purchases or monthly plans without knowing value, forcing prepayment
- **Manage API Keys**: generate, store and rotate API keys securely with ongoing maintenance and security risk

## Cost Structure Problems

Traditional payment processors impose significant fees that make micropayments impractical:

### High Percentage Fees

- Credit card processors: 2.9% + \$0.30 per transaction
- PayPal: 3.49% + fixed fee
- Stripe: 2.9% + \$0.30 per transaction

**Impact on Micropayments**:
For a \$0.01 API request, traditional fees would be \$0.30 (3,000% overhead), making the transaction economically impossible and forcing developers into subscription models even when pay-per-use would better serve users

### Fixed Fee Floor

The fixed fee component (\$0.30) makes transactions under \$10 economically unviable for merchants.

### Settlement Delays

Payment processors hold funds for 2-7 days, creating cash flow challenges for merchants and limiting real-time business models.

## Barriers to Automation

Traditional payments were designed for human-to-merchant interactions, not for automated systems. Automated systems cannot complete human-centric signup flows like CAPTCHA or email verification, storing payment credentials creates security risks, and pre-approval requirements prevent autonomous operation. These barriers make it impossible for AI agents and automated systems to participate in the payment economy.

## The API Monetization Challenge

Developers face a painful choice when monetizing APIs:

### Option 1: Free with Rate Limits
- No revenue
- Abuse potential
- Resource waste
- Unsustainable scaling

### Option 2: Monthly Subscriptions
- High user commitment barrier
- Revenue from unused capacity
- All-or-nothing pricing
- Poor user experience for occasional users

### Option 3: Traditional Payments
- High fees eliminate profitability
- Complex integration
- Slow settlement
- User friction

**None of these options are optimal**, creating a gap in the market for pay-per-use API models.

## Real-World Impact

These limitations have real consequences:

### For Developers
- Cannot monetize APIs effectively
- Forced into subscription models
- High payment processing overhead
- Limited business model flexibility

### For Users
- Must prepay for uncertain value
- Create accounts for one-time use
- Share payment details with many services
- Pay for unused capacity

## The Need for a New Approach

Traditional payment systems were designed for a different era—before micropayments and before API economies. We need a payment protocol that:

1. **Eliminates Account Requirements**: Instant, permissionless access
2. **Supports Micropayments**: Economically viable payments of any size
3. **Enables Automation**: Autonomous payment execution without human intervention
4. **Settles Instantly**: No 2-7 day delays
5. **Charges Fairly**: No percentage fees or high fixed costs
6. **Works with HTTP**: Native integration with web infrastructure

This is exactly what the x402 protocol provides.

<Quiz quizId="5002"/>

# The AI Agent Payment Problem (/academy/blockchain/x402-payment-infrastructure/02-introduction/03-ai-agent-problem)

---
title: The AI Agent Payment Problem
description: Understanding why AI agents need a new payment paradigm and how x402 enables autonomous commerce.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Bot
---

## Introduction

AI agents face a fundamental problem: traditional payment systems require human verification and account management, making autonomous machine-to-machine commerce impossible.

## Why Traditional Payments Block AI Agents

AI agents cannot participate in traditional payment systems for several critical reasons:

- **Can't Create Accounts**: signup flows require human verification (CAPTCHA, email, phone) and KYC processes that AI agents cannot complete
- **Can't Handle Micropayments**: transaction fees make small payments economically infeasible when fees exceed the payment amount itself
- **Credential Management Risks**: storing API keys and payment credentials creates security vulnerabilities and compliance challenges across services
- **Limited Autonomy**: pre-approved payment methods and spending limits require human authorization, defeating autonomous agent operation

## What AI Agents Need

For AI agents to participate in the digital economy, they need:

- **Instant, Permissionless Access**: No account creation, KYC verification, or identity requirements
- **Pay-Per-Use Pricing**: No monthly subscriptions or minimum commitments
- **Autonomous Payment Execution**: Agents pay without human intervention
- **Micropayment Support**: Economically viable payments of any size, including fractions of a cent
- **No Credential Management**: Direct payment without managing API keys or sensitive tokens



## How x402 Solves This

The x402 protocol addresses these challenges through:

- **HTTP-Native, No Accounts**: Payment requests work through standard HTTP without requiring account creation or identity verification
- **Instant Micropayments**: Ultra-low transaction costs and ~2-second settlement make payments of any size economically viable
- **Fully Autonomous**: Agents pay automatically based on HTTP 402 responses with no human intervention or credential storage

<Quiz quizId="5003"/>

# x402 Use Cases (/academy/blockchain/x402-payment-infrastructure/02-introduction/04-use-cases)

---
title: x402 Use Cases
description: Exploring practical applications of the x402 protocol for AI agents, micropayments, and content monetization.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Lightbulb
---

## Overview

The x402 protocol enables new business models and use cases through instant, permissionless micropayments, creating opportunities across AI agents, content creation, API monetization, and more.

## AI Agent Payments

AI agents represent a key use case for x402, enabling autonomous machine-to-machine commerce.

### Autonomous Resource Access

AI agents can operate autonomously in the x402 economy without human intervention:

- **Real-Time Data Feeds**: Pay for market data, weather information, or sensor readings on-demand
- **Compute Resources**: Purchase processing power dynamically based on workload needs
- **Premium APIs**: Access services without pre-approval or account creation
- **Training Datasets**: Acquire machine learning data through pay-per-use models
- **Cloud Services**: Utilize infrastructure with simple, transparent pricing

This transforms how AI systems interact with digital resources and services.



### Inter-Agent Commerce

x402 enables an AI-to-AI economy where specialized agents monetize their services to other agents:

- **Data and Compute Agents**: Sell curated datasets or rent processing power to other agents
- **Specialized Services**: Offer expert analysis, storage solutions, or domain-specific capabilities

This creates an autonomous machine-to-machine economy that traditional payment systems cannot support.

### Dynamic Cost Optimization

AI agents leverage x402's transparent pricing to intelligently manage costs:

- **Price Comparison and Switching**: Compare rates across providers and automatically move to better options
- **Success-Based Payment**: Pay only for successful operations, not failed attempts
- **Budget Management**: Track spending and adjust resource usage autonomously

## API & Micropayment Monetization

x402 makes micropayments economically viable, enabling developers to monetize APIs through flexible pay-per-use models.

### Pay-Per-Request Pricing

Developers can charge minimal amounts per API call, from fractions of a cent to dollars depending on computational complexity. With x402's ultra-low transaction costs, these micro-amounts become economically viable, unlike traditional payment systems where fees exceed the payment value itself. APIs are instantly accessible without subscriptions or account creation.

### Tiered & Metered Pricing

APIs can implement sophisticated pricing models based on service quality and consumption:

- **Service Quality Tiers**: Charge differently for standard best-effort processing versus priority processing with guaranteed response times
- **Metered Resource Access**: Bill based on computational complexity, data volume returned, or result accuracy
- **Usage-Based Infrastructure**: Charge for actual consumption of cloud storage, compute time, network bandwidth, or database queries

This creates natural market incentives for efficient API design and usage.

## Content Monetization

x402 enables flexible, granular monetization for content creators through pay-per-content models.

### Flexible Pricing Models

Instead of forcing monthly subscriptions, creators can charge for individual articles, videos, tutorials, or research papers. This model better serves both creators and consumers.

**Benefits for Users:**
- No recurring charges or long-term commitments
- Try individual pieces before subscribing

**Benefits for Creators:**
- Monetize every piece of content, including from casual readers
- Direct payments without platform fees taking 30-50%

## Web3 and DeFi Applications

x402 integrates seamlessly with blockchain-based applications, enabling new monetization models for decentralized services.

### Decentralized Data Markets

Oracle services and price feeds can monetize their infrastructure through granular pricing:

- **Per-Query and Update Billing**: Charge for each data request or refresh cycle instead of subscriptions
- **Historical and Real-Time Data**: Offer pay-per-record access or stream pricing
- **Lower Barriers**: Make data accessible to smaller consumers

### Account-Free DApp Access

Decentralized applications can offer premium features through instant micropayments for services like portfolio tracking, trade simulation, yield optimization, and risk analysis. No user accounts or complex authentication required.

## Summary

The x402 protocol unlocks use cases that span AI agent commerce, micropayment business models, content monetization, API access, Web3 applications, enterprise solutions, and novel applications across industries. By making micropayments economically viable and enabling autonomous payments, x402 creates opportunities for entirely new digital economies built on instant, permissionless transactions.

## Additional Resources

- [x402 Whitepaper](https://www.x402.org/x402-whitepaper.pdf) - Technical specification and use cases
- [x402 GitHub Repository](https://github.com/coinbase/x402) - Open source implementation and examples
- [PayAI Documentation](https://docs.payai.network) - Facilitator integration guides


# x402 Payment Flow (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/01-payment-flow)

---
title: x402 Payment Flow
description: Understanding the complete payment cycle from request to settlement.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: ArrowRightLeft
---

## The 4-Step Core Payment Flow

The x402 protocol operates through a simple yet powerful 4-step flow that enables instant, permissionless payments:

### Step 1: Client Requests Resource

A client (user, application, or AI agent) sends an HTTP GET request to access a resource:

```http
GET /api/premium-data HTTP/1.1
Host: example.com
```

This is a standard HTTP request—nothing special required from the client at this stage.

### Step 2: Server Returns 402 Payment Required

Instead of returning the requested content, the server responds with HTTP status code 402 "Payment Required" and a JSON body containing payment requirements:

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "lux-testnet",
      "maxAmountRequired": "10000",
      "resource": "/api/premium-data",
      "description": "Access to premium data API",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "asset": "0x5425890298aed601595a70AB815c96711a31Bc65",
      "maxTimeoutSeconds": 60
    }
  ],
  "error": "X-PAYMENT header is required"
}
```

This response tells the client:
- Payment is required to access this resource
- The maximum amount needed (10000 base units = 0.01 USDC)
- Where to send payment (`payTo` address)
- Which blockchain to use (`lux-testnet`)
- Which token contract to use (`asset`)
- Payment scheme to use (`exact` = EIP-3009)

### Step 3: Client Retries Request with Signed Payment

The client creates and signs a payment authorization, then retries the request with the `X-PAYMENT` header:

```http
GET /api/premium-data HTTP/1.1
Host: example.com
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYXZhbGFuY2hlLWZ1amkiLCJwYXlsb2FkIjp7InNpZ25hdHVyZSI6IjB4MTIzNC4uLiIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4MTIzNC4uLiIsInRvIjoiMHg3NDJkMzUuLi4iLCJ2YWx1ZSI6IjEwMDAwIiwidmFsaWRBZnRlciI6IjE3NDA2NzIwODkiLCJ2YWxpZEJlZm9yZSI6IjE3NDA2NzIxNTQiLCJub25jZSI6IjB4MzQ1Ni4uLiJ9fX0=
```

The client does NOT submit a blockchain transaction. The authorization is gasless—the server or facilitator will submit it. For details on the `X-PAYMENT` header structure, see [X-PAYMENT Header](./03-x-payment-header).

### Step 4: Server Verifies, Settles, and Returns Resource

The server (potentially with a facilitator's help):

1. **Verifies** the EIP-712 signature is valid
2. **Settles** the payment by submitting the authorization to the blockchain
3. **Returns** the requested resource with an `X-PAYMENT-RESPONSE` header:

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4OGYzZC4uLiIsIm5ldHdvcmsiOiJhdmFsYW5jaGUtZnVqaSIsInBheWVyIjoiMHgxMjM0Li4uIiwiZXJyb3JSZWFzb24iOm51bGx9

{
  "data": "...premium content..."
}
```

The `X-PAYMENT-RESPONSE` header (decoded) contains:
```json
{
  "success": true,
  "transaction": "0x8f3d1a2b4c5e6f7a...",
  "network": "lux-testnet",
  "payer": "0x1234567890abcdef...",
  "errorReason": null
}
```

The client now has access to the resource, and the entire cycle completed in approximately 2 seconds.

## Detailed 12-Step Technical Flow

For a deeper understanding, here's the complete technical flow including facilitator interactions:



### Phase 1: Initial Request

**Step 1**: Client sends GET request to server

```http
GET /api/data?query=market-trends HTTP/1.1
Host: api.example.com
Accept: application/json
```

**Step 2**: Server returns 402 "Payment required" with payment details

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "lux-testnet",
    "maxAmountRequired": "10000",
    "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "asset": "0x5425890298aed601595a70AB815c96711a31Bc65",
    "resource": "/api/data"
  }],
  "error": "X-PAYMENT header is required"
}
```

### Phase 2: Payment Creation

**Step 3**: Client selects payment requirements and creates payment payload

The client chooses from the `accepts` array and creates authorization:

```javascript
// Select payment option
const paymentReq = response.data.accepts[0];

// Create authorization object (EIP-3009 format)
const authorization = {
  from: userWalletAddress,
  to: paymentReq.payTo,
  value: paymentReq.maxAmountRequired,
  validAfter: Math.floor(Date.now() / 1000).toString(),
  validBefore: (Math.floor(Date.now() / 1000) + 300).toString(),
  nonce: ethers.hexlify(ethers.randomBytes(32))
};

// Sign authorization with EIP-712
const signature = await wallet.signTypedData(domain, types, authorization);

// Create payment payload
const paymentPayload = {
  x402Version: 1,
  scheme: paymentReq.scheme,
  network: paymentReq.network,
  payload: {
    signature: signature,
    authorization: authorization
  }
};
```

### Phase 3: Payment Submission and Verification

**Step 4**: Client includes X-PAYMENT header with request

```http
GET /api/data?query=market-trends HTTP/1.1
Host: api.example.com
X-PAYMENT: <base64-encoded-payment-payload>
```

**Step 5**: Server verifies payload (locally or via facilitator)

The server validates the EIP-712 signature and authorization:

```javascript
// Server can verify locally or use facilitator
POST https://facilitator.payai.network/verify
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "lux-testnet",
  "payload": {
    "signature": "0x1234...",
    "authorization": {...}
  }
}
```

**Step 6**: Facilitator validates and returns verification response

The facilitator checks:
- ✓ Is the EIP-712 signature valid?
- ✓ Is the authorization correctly formatted?
- ✓ Is the `validBefore` timestamp still valid?
- ✓ Has this nonce been used before?

Response:
```json
{
  "isValid": true,
  "invalidReason": null
}
```

**Step 7**: Server fulfills request if valid, returns 402 if invalid

If verification passes, server proceeds to settlement. If not, returns new 402 response.

### Phase 4: Blockchain Settlement

**Step 8**: Server settles payment (directly or via facilitator)

The server submits the signed authorization to the blockchain:

```javascript
// Server uses facilitator to settle
POST https://facilitator.payai.network/settle
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "lux-testnet",
  "payload": {
    "signature": "0x1234...",
    "authorization": {
      "from": "0x1234...",
      "to": "0x742d35...",
      "value": "10000",
      "validAfter": "1740672089",
      "validBefore": "1740672154",
      "nonce": "0x3456..."
    }
  }
}
```

**Step 9**: Facilitator submits to blockchain

The facilitator calls the USDC contract's `transferWithAuthorization` function (EIP-3009):

```solidity
// USDC.transferWithAuthorization on Lux Testnet
transferWithAuthorization(
  from: 0x1234...,        // Payer
  to: 0x742d35...,        // Recipient
  value: 10000,           // 0.01 USDC (6 decimals)
  validAfter: 1740672089,
  validBefore: 1740672154,
  nonce: 0x3456...,
  v: 27,
  r: 0x...,
  s: 0x...
)
```

**Step 10**: Blockchain confirms transaction

Lux's sub-second finality confirms the transaction in \<1 second.

### Phase 5: Settlement Response

**Step 11**: Facilitator returns payment execution response

The facilitator returns settlement status to the server:

```json
{
  "success": true,
  "error": null,
  "txHash": "0x8f3d1a2b4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a...",
  "networkId": "lux-testnet"
}
```

**Step 12**: Server returns resource with X-PAYMENT-RESPONSE header

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: <base64-encoded-settlement-response>

{
  "marketTrends": [...]
}
```

The `X-PAYMENT-RESPONSE` (decoded):
```json
{
  "success": true,
  "transaction": "0x8f3d1a2b4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a...",
  "network": "lux-testnet",
  "payer": "0x1234567890abcdef...",
  "errorReason": null
}
```

## Flow Timing

The entire flow completes remarkably fast:

| Step | Duration | Cumulative |
|------|----------|------------|
| 1-2: Initial request + 402 response | ~100ms | 100ms |
| 3-4: Payment method selection | ~200ms | 300ms |
| 5-7: Payment submission + verification | ~300ms | 600ms |
| 8-10: Blockchain transaction + confirmation | ~1400ms | 2000ms |
| 11-12: Settlement + content delivery | ~100ms | 2100ms |

**Total Time: ~2 seconds** from initial request to content delivery.

## Key Design Principles

### 1. HTTP-Native

x402 uses standard HTTP headers and status codes. No custom protocols or specialized infrastructure required.

### 2. Facilitator-Mediated

Facilitators handle the complex blockchain interactions, making integration simple for merchants.

### 3. Blockchain-Settled

All payments settle on-chain, providing:
- Transparency
- Immutability
- Cryptographic proof
- Decentralization

### 4. Stateless Protocol

Each payment is independent. No sessions, no stored state, no account management required.

### 5. Idempotent Requests

Payment proofs can only be used once. Replay attacks are prevented by on-chain verification.

For comprehensive security details, see [Security Considerations](./07-security-considerations).

## Summary

The x402 payment flow transforms HTTP 402 into a functional payment request mechanism through a 4-step cycle (or 12-step detailed flow) that completes in approximately 2 seconds. By using facilitators to mediate blockchain interactions and leveraging Lux's fast finality, x402 makes instant, permissionless payments a reality while maintaining security and simplicity.

## Next Steps

In the following lessons, we'll dive deeper into:
- HTTP headers and their structure
- The facilitator's role in detail
- Blockchain settlement mechanics


# HTTP 402 Payment Required (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/02-http-payment-required)

---
title: HTTP 402 Payment Required
description: How servers request payment using HTTP 402 status code and structured payment requirements.
updated: 2025-11-14
authors: [Federico Nardelli]
icon: Code
---

## HTTP 402 Payment Required Response

When a server requires payment for a resource, it responds with the HTTP 402 Payment Required status code. This standard HTTP response includes a JSON body containing structured payment requirements that specify exactly what payment is needed, where it should go, and how it should be made.

### Response Structure

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "lux-testnet",
      "maxAmountRequired": "10000",
      "resource": "/api/premium-data",
      "description": "Real-time market analysis",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "asset": "0x5425890298aed601595a70AB815c96711a31Bc65",
      "maxTimeoutSeconds": 60
    }
  ],
  "error": "X-PAYMENT header is required"
}
```

### Field Definitions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x402Version` | number | Yes | Protocol version (currently 1) |
| `accepts` | array | Yes | Array of accepted payment options |
| `error` | string | No | Error message explaining why payment is required |

### Payment Requirements Object (`accepts` array)

Each payment option in the `accepts` array contains:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `scheme` | string | Yes | Payment scheme |
| `network` | string | Yes | Blockchain network identifier |
| `maxAmountRequired` | string | Yes | Maximum payment amount required (in token base units) |
| `resource` | string | Yes | Resource path being requested |
| `payTo` | string | Yes | Recipient blockchain address |
| `asset` | string | Yes | Token contract address |
| `maxTimeoutSeconds` | number | No | Maximum time to complete payment |
| `description` | string | No | Human-readable description |

### Payment Schemes

The `scheme` field specifies how payments are settled. x402 supports multiple schemes to handle different payment models:

**`exact` Scheme (Implemented)**:
- Fixed payment amount known upfront
- Use cases: Pay $0.10 to read an article, fixed-price API calls
- Implementations: EVM (EIP-3009), Solana, Sui
- Example: `"scheme": "exact", "maxAmountRequired": "100000"`

**`up-to` Scheme (Proposed)**:
- Variable payment based on resource consumption
- Use cases: LLM token-based pricing, pay-per-token generation, usage-metered services
- Status: Not yet implemented - under development
- Example use: Pay up to $1.00, actual charge depends on tokens consumed

The protocol is designed to be extensible, allowing new schemes to be added as payment models evolve. Current implementations focus on the `exact` scheme across multiple blockchains.

**Reference**: See [x402 Schemes Specification](https://github.com/coinbase/x402/tree/main/specs/schemes) for technical details.

### Network Identifiers

Standard network identifiers for Lux and other chains:

```javascript
"network": "lux-c-chain" // Lux LUExchange-Chain Mainnet
"network": "lux-testnet"    // Lux Testnet Testnet
"network": "base-sepolia"      // Base Sepolia Testnet
```

### Amount Specification

Amounts are always strings representing **base units** (smallest denomination).<br/>
**Important**: USDC has 6 decimals, so:

```javascript
// For USDC: 10000 = 0.01 USDC
"maxAmountRequired": "10000"

// For USDC: 1000000 = 1.0 USDC
"maxAmountRequired": "1000000"
```

### Asset (Token Contract Address)

The `asset` field contains the smart contract address of the payment token:

```javascript
// USDC on Lux Testnet testnet
"asset": "0x5425890298aed601595a70AB815c96711a31Bc65"

// USDC on Lux LUExchange-Chain mainnet
"asset": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"

// USDC on Base Sepolia testnet
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
```

**Note**: The asset is identified by contract address, not by symbol like "USDC".

### Multiple Payment Options

Servers can offer multiple payment options (different networks or tokens):

```json
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "lux-testnet",
      "maxAmountRequired": "10000",
      "payTo": "0x742d35...",
      "asset": "0x5425890...",
      "resource": "/api/data"
    },
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "10000",
      "payTo": "0x742d35...",
      "asset": "0x036CbD...",
      "resource": "/api/data"
    }
  ]
}
```

## Summary

The HTTP 402 Payment Required response is the server's way of requesting payment from clients. It includes a JSON body with an `accepts` array that lists one or more payment options, each specifying the payment scheme, blockchain network, token contract address, maximum amount required, recipient address, and optional timeout.

Servers can offer multiple payment options across different networks or with different tokens, giving clients flexibility in how they pay. Amounts are always specified in token base units (e.g., 10000 = 0.01 USDC with 6 decimals).


# X-PAYMENT (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/03-x-payment-header)

---
title: X-PAYMENT
description: How clients authorize payments using signed EIP-3009 authorizations in the X-PAYMENT header.
updated: 2025-11-14
authors: [Federico Nardelli]
icon: Code
---

## X-PAYMENT Header

After receiving an HTTP 402 response, clients authorize payment by including the `X-PAYMENT` header in their retry request. This header contains a **base64-encoded JSON** payload with a cryptographically signed payment authorization that proves user consent without requiring a blockchain transaction.

The authorization follows the EIP-3009 TransferWithAuthorization standard, enabling gasless payments where the server or facilitator submits the transaction on behalf of the user. 

### Header Structure

```http
GET /api/premium-data HTTP/1.1
Host: example.com
X-PAYMENT: <base64-encoded-payment-payload>
```

### Payment Payload Structure (before base64 encoding)

```json
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "lux-testnet",
  "payload": {
    "signature": "0x1234567890abcdef...",
    "authorization": {
      "from": "0x1234567890abcdef1234567890abcdef12345678",
      "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "value": "10000",
      "validAfter": "1740672089",
      "validBefore": "1740672154",
      "nonce": "0x3456789012345678901234567890123456789012345678901234567890123456"
    }
  }
}
```

### Field Definitions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x402Version` | number | Yes | Protocol version (currently 1) |
| `scheme` | string | Yes | Payment scheme ("exact" for EVM) |
| `network` | string | Yes | Blockchain network used |
| `payload` | object | Yes | Scheme-specific payment data |

### Payload for "exact" Scheme (EVM Chains)

The payload for EVM chains using the "exact" scheme contains:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `signature` | string | Yes | EIP-712 signature of the authorization |
| `authorization` | object | Yes | Payment authorization details |

### Authorization Object

The authorization object follows EIP-3009 TransferWithAuthorization:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | string | Yes | Payer's wallet address |
| `to` | string | Yes | Recipient's wallet address |
| `value` | string | Yes | Amount in token base units |
| `validAfter` | string | Yes | Unix timestamp (seconds) - payment valid after this time |
| `validBefore` | string | Yes | Unix timestamp (seconds) - payment expires after this time |
| `nonce` | string | Yes | Unique 32-byte hex string for replay protection (randomly generated, not the sequential wallet nonce) |

### EIP-712 Signature

The signature field contains an EIP-712 signature of the authorization object:

```javascript
// The user's wallet signs the authorization using EIP-712
const signature = await wallet.signTypedData({
  domain: {
    name: "USD Coin",
    version: "2",
    chainId: 43113, // Lux Testnet
    verifyingContract: "0x5425890298aed601595a70AB815c96711a31Bc65"
  },
  types: {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" }
    ]
  },
  primaryType: "TransferWithAuthorization",
  message: authorization
});
```

This signature:
- Proves user consent without requiring a transaction
- Cannot be forged (cryptographically secure)
- Includes all payment details in the signature
- Enables gasless payments (server submits the transaction)

### Complete Example

```javascript
// 1. Client receives 402 response with payment requirements
const paymentReq = response.data.accepts[0];

// 2. Client creates authorization object
const authorization = {
  from: userAddress,
  to: paymentReq.payTo,
  value: paymentReq.maxAmountRequired,
  validAfter: Math.floor(Date.now() / 1000).toString(),
  validBefore: (Math.floor(Date.now() / 1000) + 300).toString(), // 5 minutes
  nonce: ethers.hexlify(ethers.randomBytes(32))
};

// 3. User signs authorization
const signature = await wallet.signTypedData(...);

// 4. Client creates payment payload
const paymentPayload = {
  x402Version: 1,
  scheme: paymentReq.scheme,
  network: paymentReq.network,
  payload: {
    signature: signature,
    authorization: authorization
  }
};

// 5. Base64 encode and send
const encoded = btoa(JSON.stringify(paymentPayload));
await fetch('/api/premium-data', {
  headers: {
    'X-PAYMENT': encoded
  }
});
```

## Client Best Practices

When implementing X-PAYMENT headers, clients should follow these guidelines:

1. **Decode and parse carefully**: Base64 decode and JSON parse all headers
2. **Check authorization expiry**: Don't sign authorizations with past `validBefore` timestamps
3. **Generate unique nonces**: Use cryptographically secure random 32-byte values
4. **Store transaction receipts**: Keep `X-PAYMENT-RESPONSE` data for proof of payment
5. **Handle errors gracefully**: Implement retry logic with exponential backoff

For detailed security considerations including signature validation, nonce-based replay prevention, and authorization timing validation, see [Security Considerations](./07-security-considerations).

## Summary

The X-PAYMENT header enables clients to authorize payments through cryptographically signed EIP-3009 authorizations. Clients create an authorization object containing payment details (from, to, value, validity window, nonce), sign it using EIP-712, and encode the complete payload as base64 before including it in the X-PAYMENT header.

This gasless payment model means users only sign an authorization—they don't submit blockchain transactions or pay gas fees. The server or facilitator handles transaction submission, making the payment experience seamless while maintaining cryptographic proof of user consent.

# X-PAYMENT-RESPONSE (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/04-x-payment-response-header)

---
title: X-PAYMENT-RESPONSE
description: How servers communicate payment settlement results with transaction hashes and error details.
updated: 2025-11-14
authors: [Federico Nardelli]
icon: Code
---

## X-PAYMENT-RESPONSE Header

After verifying and settling a payment from an X-PAYMENT header, the server communicates the settlement result back to the client through the `X-PAYMENT-RESPONSE` header. This header contains critical information about the blockchain transaction, including the transaction hash for on-chain verification.

Like the `X-PAYMENT` header, the `X-PAYMENT-RESPONSE` is **base64-encoded JSON** that provides cryptographic proof of payment settlement. 

### Header Structure

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: <base64-encoded-settlement-response>
```

### Settlement Response Structure (before base64 encoding)

```json
{
  "success": true,
  "transaction": "0x8f3d1a2b4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a",
  "network": "lux-testnet",
  "payer": "0x1234567890abcdef1234567890abcdef12345678",
  "errorReason": null
}
```

### Field Definitions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | Yes | Whether settlement was successful |
| `transaction` | string | Yes (if success) | Transaction hash on blockchain |
| `network` | string | Yes | Network where transaction was settled |
| `payer` | string | Yes | Address of the payer |
| `errorReason` | string | Yes (if failed) | Error message if settlement failed |

### Success Response

When payment is successfully verified and settled:

```json
{
  "success": true,
  "transaction": "0x8f3d1a2b4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a",
  "network": "lux-testnet",
  "payer": "0x1234567890abcdef1234567890abcdef12345678",
  "errorReason": null
}
```

The transaction hash can be used to:
- Verify the transaction on a block explorer
- Check transaction details (amount, timestamp, block number)
- Provide proof of payment to users
- Audit payment history

### Payment Failure Response

When payment verification or settlement fails, the server returns **HTTP 402 Payment Required** with both a JSON body containing payment requirements and an `X-PAYMENT-RESPONSE` header with failure details:

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjpmYWxzZSwidHJhbnNhY3Rpb24iOm51bGwsIm5ldHdvcmsiOiJhdmFsYW5jaGUtZnVqaSIsInBheWVyIjoiMHgxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4IiwiZXJyb3JSZWFzb24iOiJJbnN1ZmZpY2llbnQgYXV0aG9yaXphdGlvbiBhbW91bnQifQ==

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "lux-testnet",
    "maxAmountRequired": "10000",
    "payTo": "0x742d35...",
    "asset": "0x5425890...",
    "resource": "/api/data"
  }],
  "error": "Insufficient payment: required 10000, received 5000"
}
```

The `X-PAYMENT-RESPONSE` header (when decoded) contains:

```json
{
  "success": false,
  "transaction": null,
  "network": "lux-testnet",
  "payer": "0x1234567890abcdef1234567890abcdef12345678",
  "errorReason": "Insufficient authorization amount"
}
```

**Common error reasons**:
- `"Insufficient authorization amount"` - Payment amount too low
- `"Authorization expired"` - validBefore timestamp passed
- `"Invalid signature"` - Signature verification failed
- `"Nonce already used"` - Replay attack detected
- `"Insufficient balance"` - Payer doesn't have enough tokens

**Why both body and header?**
- **JSON body**: Provides new payment requirements so the client can retry
- **X-PAYMENT-RESPONSE header**: Communicates what went wrong with the settlement attempt

## Server Best Practices

When implementing X-PAYMENT-RESPONSE headers, servers should follow these guidelines:

1. **Support multiple networks**: Include options for different blockchains in `accepts` array when returning 402 failures
2. **Set reasonable timeouts**: Use `maxTimeoutSeconds` to prevent stale payments
3. **Use base units consistently**: Always specify amounts in smallest token denomination
4. **Validate signatures carefully**: Use EIP-712 verification libraries
5. **Implement replay protection**: Track used nonces to prevent double-spending
6. **Return transaction hashes**: Always include the on-chain transaction hash in success responses
7. **Provide clear error messages**: Use descriptive `errorReason` values for failure cases
8. **Store transaction receipts**: Keep settlement records for audit and dispute resolution

For comprehensive security considerations including signature validation and nonce-based replay prevention, see [Security Considerations](./07-security-considerations).

## Summary

The `X-PAYMENT-RESPONSE` header provides settlement confirmation with blockchain transaction details. Success responses include the transaction hash for on-chain verification, while failure responses explain what went wrong and are accompanied by new payment requirements in the HTTP 402 body.

# The Facilitator Role (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/05-facilitator-role)

---
title: The Facilitator Role
description: Understanding how facilitators enable seamless payment verification and settlement in x402.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Users
---

## What is a Facilitator?

A **facilitator** is a service that handles payment verification and blockchain settlement on behalf of merchants and clients in the x402 protocol. Facilitators act as trusted intermediaries that:

- Verify payment authenticity
- Submit transactions to the blockchain
- Handle merchant whitelisting
- Manage settlement processes
- Provide developer tools and SDKs

Think of facilitators as the "payment processors" of the x402 ecosystem—but unlike traditional processors, they charge minimal fees and settle instantly.

## Why Facilitators Are Necessary

While blockchain payments are permissionless, integrating them directly into applications requires handling significant infrastructure complexity.

| Without Facilitators | With Facilitators |
|----------------------|-------------------|
| Run blockchain nodes (maintain infrastructure, handle failures, sync state) | Add middleware to your application |
| Monitor transactions in real-time (query blocks, parse logs, handle reorgs) | Receive instant verification responses |
| Optimize gas prices and manage transaction confirmation | Automatic settlement handling |
| Secure wallet infrastructure (key storage, signing operations) | Use simple REST APIs |
| Implement replay attack prevention (nonce tracking, databases) | Built-in security features |
| Build payment verification (parse EIP-3009 signatures, validate parameters) | Payment validation handled automatically |
| Deploy infrastructure for each blockchain separately | Multi-chain support included |

Facilitators abstract away blockchain complexity while maintaining the benefits of permissionless payments.

## Core Facilitator Responsibilities

### 1. Merchant Whitelisting

Facilitators maintain a whitelist of approved merchants to prevent fraud:

```javascript
// Merchant registration
POST /facilitator/register
{
  "merchantAddress": "0x742d35...",
  "businessName": "Premium API Service",
  "website": "https://api.example.com",
  "acceptedCurrencies": ["USDC", "USDT"],
  "chains": ["lux-testnet", "base-sepolia"]
}

// Response
{
  "status": "approved",
  "merchantId": "merchant_123",
  "apiKey": "fac_live_...",
  "whitelistStatus": "active"
}
```

**Whitelist Benefits**:
- Prevents malicious merchants
- Reduces payment fraud
- Builds user trust
- Enables dispute resolution

### 2. User Approval Verification

Before submitting payments, facilitators verify user consent:

```javascript
// User signs approval
const approval = await wallet.signMessage({
  facilitator: "thirdweb",
  merchantAddress: "0x742d35...",
  amount: "0.01",
  currency: "USDC",
  timestamp: Date.now(),
  nonce: generateNonce()
});

// Facilitator verifies signature
POST /facilitator/verify-approval
{
  "signature": "0x9a8b...",
  "approvalData": {...}
}

// Response
{
  "valid": true,
  "expiresAt": "2025-11-03T10:35:00Z"
}
```

**Verification Steps**:
1. Check signature cryptographic validity
2. Verify signer matches payer address
3. Confirm approval hasn't expired
4. Ensure nonce hasn't been used before

### 3. Payment Verification

When a merchant requests verification, facilitators check the blockchain:

```javascript
// Merchant requests verification
POST /facilitator/verify-payment
{
  "transactionHash": "0x8f3d...",
  "expectedAmount": "0.01",
  "expectedCurrency": "USDC",
  "expectedRecipient": "0x742d35...",
  "chain": "lux-c-chain"
}

// Facilitator queries blockchain
const tx = await luxClient.getTransaction("0x8f3d...");

// Verification checks
- Transaction exists on chain
- Transaction is confirmed
- Amount matches expected
- Recipient matches expected
- Currency is correct
- Transaction not previously used
- Block timestamp is recent

// Response
{
  "verified": true,
  "transactionHash": "0x8f3d...",
  "blockNumber": 12345678,
  "timestamp": "2025-11-03T10:30:02Z",
  "confirmations": 1
}
```

### 4. Transaction Submission

Facilitators can submit transactions on behalf of users:

```javascript
// User approves payment intent (without submitting)
const intent = {
  from: userWallet,
  to: merchantWallet,
  amount: "0.01",
  currency: "USDC"
};

const signature = await wallet.signApproval(intent);

// Facilitator submits transaction
POST /facilitator/submit-payment
{
  "paymentIntent": intent,
  "signature": signature,
  "gasPriority": "fast"
}

// Facilitator submits to blockchain
const tx = await usdcContract.transfer(
  intent.to,
  parseUnits(intent.amount, 6)
);

// Response
{
  "submitted": true,
  "transactionHash": "0x8f3d...",
  "estimatedConfirmation": "2025-11-03T10:30:02Z"
}
```

**Submission Benefits**:
- Users don't need LUX for gas
- Optimized gas prices
- Better UX for non-crypto users
- Batched transactions possible

### 5. Settlement Management

Facilitators handle payment settlement with merchants:

```javascript
// Real-time settlement notification
{
  "event": "payment.verified",
  "merchantId": "merchant_123",
  "transactionHash": "0x8f3d...",
  "amount": "0.01",
  "currency": "USDC",
  "from": "0x1234...",
  "timestamp": "2025-11-03T10:30:02Z",
  "blockNumber": 12345678
}

// Batched settlement (optional)
POST /facilitator/withdraw-balance
{
  "merchantAddress": "0x742d35...",
  "currency": "USDC",
  "chain": "lux-c-chain"
}

// Response
{
  "pendingBalance": "150.45",
  "withdrawalTxHash": "0xabc123...",
  "estimatedArrival": "2025-11-03T10:32:00Z"
}
```

## Facilitator Architecture

The facilitator sits between merchants and the blockchain, handling the complex verification and settlement process:

**Payment Flow**:
1. **Client → Merchant**: Client sends payment authorization via X-PAYMENT header
2. **Merchant → Facilitator**: Merchant forwards the authorization for verification
3. **Facilitator → Blockchain**: Facilitator verifies the signature and submits transaction on-chain
4. **Blockchain → Facilitator**: Transaction is confirmed with hash
5. **Facilitator → Merchant**: Payment confirmation returned to merchant
6. **Merchant → Client**: Content delivered to client with X-PAYMENT-RESPONSE header

This entire flow completes in ~2 seconds on Lux.

### Multi-Chain Support

Facilitators often support multiple blockchains:

```javascript
// Facilitator chain configuration
{
  "chains": [
    {
      "id": "lux-c-chain",
      "rpcUrl": "https://api.lux.network/ext/bc/C/rpc",
      "usdcAddress": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      "confirmations": 1,
      "averageBlockTime": "2s"
    },
    {
      "id": "base-sepolia",
      "rpcUrl": "https://sepolia.base.org",
      "usdcAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "confirmations": 1,
      "averageBlockTime": "2s"
    }
  ]
}
```

This allows merchants to accept payments on any supported chain.

## Facilitator Economics

Facilitators charge minimal fees compared to traditional payment processors:

**Typical Fee Structure**:
- Small percentage fee (~0.1-0.5% of transaction)
- Plus blockchain gas costs (~\$0.001 on Lux with current network conditions)
- No monthly fees or minimums
- No chargebacks or disputes

**Example**: On a $0.10 payment:
- Facilitator fee: ~$0.0003 (0.3%)
- Gas cost: ~$0.001 (current network conditions)
- **Total cost: ~$0.0013**

Compare to traditional payment processors: 2.9% + $0.30 = $0.3029 per transaction!

Facilitators make micropayments economically viable.

## Security and Trust

### Merchant Protection

Facilitators protect merchants from:
- Replay attacks (transaction hash tracking)
- Insufficient payments (amount verification)
- Wrong currency (token verification)
- Expired payments (timestamp checking)

### User Protection

Facilitators protect users from:
- Malicious merchants (whitelisting)
- Unauthorized charges (signature verification)
- Double-spending (on-chain verification)
- Overcharging (amount validation)

## Summary

Facilitators are essential infrastructure in the x402 ecosystem, handling payment verification, blockchain settlement, merchant whitelisting, and user approval verification. By abstracting blockchain complexity, facilitators enable merchants to accept cryptocurrency payments with minimal integration while maintaining security, speed, and low costs.

Facilitators charge minimal fees (~0.1-0.5% + gas) compared to traditional payment processors (2.9% + $0.30), making micropayments economically viable for the first time.

**Next**: Learn about [Blockchain Settlement](./06-blockchain-settlement) to understand how payments are finalized on-chain, or explore [available facilitators on Lux](/academy/blockchain/x402-payment-infrastructure/04-x402-on-lux/03-facilitators) for implementation options.


# Blockchain Settlement (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/06-blockchain-settlement)

---
title: Blockchain Settlement
description: Understanding how payments are settled on-chain with instant finality and cryptographic proof.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Link
---

## On-Chain Settlement Overview

In the x402 protocol, all payments settle directly on the blockchain, providing transparency, immutability, and instant finality. This contrasts with traditional payment systems where settlement can take days and occurs in opaque, centralized databases.

## Why Blockchain Settlement?

### Transparency

Every payment is publicly verifiable:

```javascript
// Anyone can verify a payment
const tx = await luxClient.getTransaction(
  "0x8f3d1a2b4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a"
);

console.log({
  from: tx.from,           // Payer address
  to: tx.to,               // Recipient address
  value: tx.value,         // Amount paid
  blockNumber: tx.blockNumber,
  timestamp: tx.timestamp,
  status: tx.status        // Success/failure
});
```

No need to trust a payment processor—the blockchain is the source of truth.

### Immutability

Once a transaction is confirmed, it cannot be:
- Reversed (no chargebacks)
- Modified (tamper-proof)
- Deleted (permanent record)
- Disputed (cryptographically proven)

This eliminates chargeback fraud and provides definitive proof of payment.

### Instant Finality

On Lux LUExchange-Chain, transactions achieve finality in approximately 2 seconds:

```
Traditional ACH:      2-7 days
Credit Card:          24-72 hours
PayPal:               1-3 days
Bitcoin:              ~60 minutes (6 confirmations)
Ethereum:             ~15 minutes (2 epochs)
Lux:            ~2 seconds ✓
```

## The Settlement Process

When a payment authorization is submitted through x402, settlement happens through a streamlined three-phase process leveraging EIP-3009's gasless payment standard.

### Phase 1: Authorization Verification

The facilitator receives the signed EIP-712 authorization from the client. This cryptographic signature proves the user approved the payment without requiring them to submit a blockchain transaction themselves. The facilitator validates that:

- The signature matches the authorization details
- The payment amount doesn't exceed `maxAmountRequired`
- The authorization is within its validity window (`validAfter` to `validBefore`)
- The nonce hasn't been used before (replay protection)

This verification is trustless—the signature cryptographically guarantees user consent.

### Phase 2: Blockchain Submission

The facilitator calls the USDC contract's `transferWithAuthorization` function with the signed authorization. This **gasless payment method** (EIP-3009 standard) allows the facilitator to submit the transaction on behalf of the user. The user doesn't pay gas fees or submit any blockchain transactions—they only provide a signature.

The USDC contract verifies the signature on-chain and executes the transfer if valid. This ensures the payment cannot be tampered with after the user signs.

### Phase 3: Confirmation and Finality

On Lux, the transaction is included in a block and reaches finality in approximately **1-2 seconds**. Once finalized, the transaction cannot be reversed—the payment is permanent and immutable.

The facilitator receives the transaction hash from the blockchain and returns it to the merchant. The USDC balances are permanently updated on-chain, and the payment is complete.

**Total Time**: The entire x402 process from initial request to settlement takes approximately **2-2.3 seconds**.

**Reference**: For detailed technical implementation of TransferWithAuthorization, see [x402 Whitepaper](https://www.x402.org/x402-whitepaper.pdf) (Section 9.3).

## Payment Verification

Facilitators verify payments by querying the blockchain to ensure the transaction matches the expected payment details. This verification is trustless—anyone can independently confirm the payment by checking the blockchain.

### USDC Transfer Events

USDC transfers emit `Transfer` events on-chain that provide cryptographic proof of payment:

```solidity
event Transfer(address indexed from, address indexed to, uint256 value);
```

These events can be parsed from transaction logs to verify payment details without trusting the facilitator. The blockchain is the source of truth.

### Trustless Verification

Because all payment data is on-chain, merchants can independently verify payments without relying on facilitators. Simply query the blockchain with the transaction hash to confirm:
- Who paid (sender address)
- Who received (recipient address)
- How much was paid (token amount)
- When it was paid (block timestamp)

This transparency eliminates the need to trust payment processors.

## Gas and Fee Economics

### Transaction Costs on Lux

x402 payments on Lux use EIP-3009's gasless payment model, where the **facilitator sponsors the gas** rather than the payer. This removes the friction of users needing LUX to pay gas fees.

Typical transaction costs (based on current network conditions - January 2025):
- **Gas used**: ~77,000 gas units (`transferWithAuthorization`)
- **Gas price**: ~0.575 nLUX per gas unit (current)
- **Total cost**: ~\$0.001 USD (with LUX at $20)

**Who pays gas?**
- In x402, the **facilitator pays gas fees** when submitting the transaction
- The user only signs the authorization—no blockchain transaction needed from their side
- This enables truly gasless payments for end users

### Cost Comparison

| Aspect | Traditional Payments | x402 on Lux |
|--------|---------------------|-------------------|
| Settlement Time | 2-7 days | ~2 seconds |
| Transaction Fees | 2.9% + \$0.30 | ~\$0.001 gas (facilitator-paid) |
| Chargebacks | Possible | Impossible |
| Transparency | Opaque | Fully transparent |
| Verification | Trust processor | Cryptographic proof |
| Finality | Delayed | Instant |

**Key Advantage**: For micropayments, x402's flat ~\$0.001 gas cost is dramatically better than traditional payment processing's 2.9% + \$0.30 per transaction.

## Multi-Chain Settlement Timing

Different blockchains have different finality characteristics, which affects the total x402 payment process time. It's important to distinguish between **blockchain finality** (how fast the chain confirms transactions) and **full x402 process time** (complete flow from request to response).

### Timing Comparison

| Blockchain | Blockchain Finality | Full x402 Process | x402 Support |
|------------|---------------------|-------------------|--------------|
| **Lux** | ~1-2 seconds | ~2-2.3 seconds | ✅ Official |
| **Base** | ~2 seconds | ~2-2.5 seconds | ✅ Official |
| **Ethereum** | ~12-15 minutes | ~15-20 minutes | ✅ Official |
| **Polygon** | ~2-5 seconds | ~2-5 seconds | ⚠️ Check facilitator |

**Note**: The **full x402 process time** includes:
1. Initial request (~100ms)
2. 402 response (~100ms)
3. Payment authorization creation and signing (~500ms)
4. Blockchain settlement (varies by chain)
5. Response delivery (~100ms)

**Important**: Chains not listed here may not have official x402 support yet. Always verify with your facilitator which networks they support. Check [PayAI documentation](https://docs.payai.network) for their current network list.

## Summary

Blockchain settlement in x402 provides transparent, immutable, and instant payment finality through EIP-3009's gasless payment standard. The complete x402 process takes approximately **2-2.3 seconds** on Lux, with blockchain finality achieved in **1-2 seconds**.

Key advantages:
- **Gasless for users**: Facilitators sponsor gas fees, eliminating the need for users to hold native tokens
- **Cryptographic proof**: Every payment is verifiable on-chain without trusting intermediaries
- **No chargebacks**: Finality is instant and irreversible
- **Multi-chain support**: Works across Lux, Base, Ethereum, and other EVM chains

Facilitators abstract away the complexity of blockchain interactions, making x402 settlement as simple as traditional payment APIs while delivering superior speed, lower costs, and trustless verification.

**Next**: Learn about [Security Considerations](./07-security-considerations) including replay attack prevention, signature validation, and settlement monitoring.

## Additional Resources

- [x402 Whitepaper - Technical Specifications](https://www.x402.org/x402-whitepaper.pdf)
- [EIP-3009: Transfer With Authorization](https://eips.ethereum.org/EIPS/eip-3009)
- [Lux Consensus](https://docs.lux.network/learn/lux/lux-consensus)


# Security Considerations (/academy/blockchain/x402-payment-infrastructure/03-technical-architecture/07-security-considerations)

---
title: Security Considerations
description: Understanding replay attack prevention, time-bounded authorizations, and settlement monitoring in x402.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Shield
---

## Overview

The x402 protocol implements multiple layers of security to protect against common attack vectors while maintaining a seamless user experience. These security measures are built on battle-tested Ethereum standards (EIP-712, EIP-3009) and blockchain cryptography.

## Replay Attack Prevention

Replay attacks occur when an attacker intercepts a valid payment authorization and attempts to reuse it multiple times. x402 prevents this through three complementary mechanisms:

### 1. Nonce-Based Protection

Each payment authorization includes a unique random nonce (32-byte hex string):

```javascript
const nonce = ethers.hexlify(ethers.randomBytes(32));
// Example: 0x3456789012345678901234567890123456789012345678901234567890123456
```

The USDC contract (following EIP-3009) tracks which nonces have been used on-chain. When a `transferWithAuthorization` is executed:

1. The contract checks if the nonce has been used before
2. If the nonce is new, the transfer proceeds and the nonce is marked as used
3. If the nonce was already used, the transaction reverts with an error

**This makes each authorization single-use**. Even if an attacker intercepts the authorization, they cannot reuse it because the nonce is already consumed on-chain.

### 2. Time-Bounded Authorizations

Every authorization includes `validAfter` and `validBefore` timestamps (Unix time in seconds):

```json
{
  "validAfter": "1740672089",   // January 7, 2025, 10:00:00 AM UTC
  "validBefore": "1740672389"   // January 7, 2025, 10:05:00 AM UTC (5 minutes later)
}
```

The USDC contract enforces these timing constraints:
- If current time < `validAfter`: Transaction reverts (not yet valid)
- If current time ≥ `validBefore`: Transaction reverts (expired)
- Only between these times: Transaction can execute

**Best practices**:
- Set short validity windows (5-10 minutes) for most payments
- For delayed/scheduled payments, set appropriate `validAfter`
- Never set `validBefore` too far in the future (increases replay risk if nonce tracking fails)

### 3. Transaction Hash Uniqueness

Each blockchain transaction has a unique hash. Merchants should track received transaction hashes to ensure they don't fulfill the same payment twice. Even though blockchain nonces prevent double-spending, tracking fulfilled payments prevents edge cases like duplicate facilitator notifications or network issues causing duplicate webhook deliveries.

## Signature Validation

All payment authorizations use EIP-712 typed structured data signatures, providing cryptographic proof that the user authorized the payment.

### Server-Side Signature Verification

Facilitators must validate signatures before submitting transactions:

```javascript
import { verifyTypedData } from 'ethers';

function validatePaymentSignature(payload) {
  const { signature, authorization } = payload.payload;
  const { network } = payload;

  // EIP-712 domain for USDC on Lux Testnet
  const domain = {
    name: "USD Coin",
    version: "2",
    chainId: 43113,  // Lux Testnet
    verifyingContract: "0x5425890298aed601595a70AB815c96711a31Bc65"
  };

  // EIP-712 type definition
  const types = {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" }
    ]
  };

  // Recover signer address from signature
  const recovered = verifyTypedData(
    domain,
    types,
    authorization,
    signature
  );

  // Verify the signer matches the 'from' address
  if (recovered.toLowerCase() !== authorization.from.toLowerCase()) {
    throw new Error("Invalid signature: signer does not match 'from' address");
  }

  return true;
}
```

**Key validation steps**:
1. Recover the signer address from the signature
2. Verify it matches the `from` field in the authorization
3. Check all other fields (amount, recipient, timing)
4. Only submit to blockchain if everything validates

The USDC contract also validates signatures on-chain, providing trustless verification even if the facilitator is malicious.

## Authorization Timing Validation

Facilitators validate timing constraints before submitting transactions to avoid wasting gas on expired authorizations. This prevents submitting transactions that will revert, wasting gas fees, or creating poor user experience from delayed settlements.

## Settlement Monitoring

Facilitators monitor the blockchain in real-time to detect when payments are settled and verify transaction success. Most facilitators provide webhook notifications when settlements complete.

**Best practice**: Always verify webhook data by querying the blockchain directly. Don't trust the webhook alone—use it as a notification, then verify on-chain. Merchants can also monitor blockchain events independently without relying on facilitator notifications.

## Amount Verification

Verify that the payment amount meets your requirements. Amounts are in token base units (see [Amount Specification](./02-http-payment-required#amount-specification) for details). Accept payments equal to or greater than `maxAmountRequired`.

## Network Verification

Verify that the payment is on the expected blockchain network. This prevents:
- Payments on testnets being accepted as mainnet payments
- Cross-chain replay attacks
- Merchant configuration errors

## Recipient Address Verification

Verify that payments are sent to the correct recipient address. This is especially important when supporting multiple merchants, using different addresses for different services, or accepting payments to multiple wallets.

## Token Contract Verification

Verify that the payment uses the expected token (asset) by validating the exact contract address. Attackers could try to pay with worthless tokens that share similar addresses.

## Rate Limiting and Abuse Prevention

Implement rate limiting to prevent spam attacks, nonce exhaustion, and resource abuse. Track payment frequency by address and enforce reasonable limits per time window.

## Summary

x402 security relies on multiple defense layers:

1. **Nonce-based replay prevention**: Each authorization is single-use
2. **Time-bounded authorizations**: Payments expire after a set time window
3. **EIP-712 signatures**: Cryptographic proof of user authorization
4. **On-chain validation**: USDC contract verifies all constraints
5. **Transaction hash tracking**: Merchants prevent duplicate fulfillment
6. **Amount, network, and asset verification**: Validate all payment parameters
7. **Settlement monitoring**: Real-time blockchain monitoring for finality

These mechanisms provide trustless, cryptographically secure payments without requiring users to trust facilitators or merchants. The blockchain enforces all security rules.

## Additional Resources

- [EIP-712: Typed Structured Data Signing](https://eips.ethereum.org/EIPS/eip-712)
- [EIP-3009: Transfer With Authorization](https://eips.ethereum.org/EIPS/eip-3009)
- [x402 Whitepaper - Security Model](https://www.x402.org/x402-whitepaper.pdf)
- [PayAI Security Best Practices](https://docs.payai.network/security)


# Why Lux for x402? (/academy/blockchain/x402-payment-infrastructure/04-x402-on-avalanche/01-why-avalanche)

---
title: Why Lux for x402?
description: Understanding why Lux LUExchange-Chain is ideal for x402 payment infrastructure.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Zap
---

## Lux's x402 Advantages

Lux LUExchange-Chain provides unique characteristics that make it an ideal platform for x402 payment infrastructure. The combination of low fees, fast finality, high throughput, and EVM compatibility creates the perfect environment for micropayments and AI agent commerce.

## Sub-2-Second Finality

Lux achieves transaction finality in approximately 1-2 seconds, faster than any other EVM-compatible chain:

| Blockchain | Blockchain Finality | Full x402 Process | Use Case Fit |
|------------|---------------------|-------------------|--------------|
| **Lux** | **~1-2 seconds** | **~2-2.3 seconds** | **✓ Ideal for x402** |
| **Base** | **~2 seconds** | **~2-2.5 seconds** | **✓ Good** |
| Ethereum | ~12-15 minutes | ~15-20 minutes | ✗ Too slow for real-time |

**Why This Matters for x402**:
- Users wait only ~2 seconds for content delivery
- AI agents can make rapid sequential payments
- High-frequency API calls remain practical
- Real-time payment verification possible

### Lux vs Base for x402

While both Lux and Base offer fast finality suitable for x402 payments, Lux provides key advantages:

**Finality Guarantees**:
- **Lux**: Deterministic finality ~1-2 seconds ([Lux Consensus](https://docs.lux.network/learn/lux/lux-consensus))
- **Base**: Probabilistic finality [~2 seconds](https://docs.base.org/base-chain/network-information/transaction-finality#under-0-001-probability-of-a-reorg)

**Gas Costs**:
- **Lux**: ~$0.001 for `transferWithAuthorization` (based on current gas prices of 0.575 nLUX)
- **Base**: ~$0.01-0.10 depending on L1 gas prices (variable)

For mission-critical x402 applications requiring guaranteed fast settlement and consistent costs, **Lux is a strong option**.

## Ultra-Low Transaction Fees

Lux LUExchange-Chain maintains extremely low gas costs, making micropayments economically viable:

### Fee Comparison

```javascript
// $0.01 payment cost analysis

Lux LUExchange-Chain:
├── Payment value: $0.01
├── Gas fee: ~$0.001
├── Total cost: $0.011
└── Overhead: 10% ✓

Base:
├── Payment value: $0.01
├── Gas fee: ~$0.001
├── Total cost: $0.011
└── Overhead: 10% ✓ (acceptable)
```

### Real-World Economics

For a typical x402 API monetization scenario:

```javascript
// Scenario: Image processing API

Traditional Payment (Stripe):
├── API request value: $0.01
├── Processing fee: 2.9% + $0.30
├── Total fee: $0.30029
├── Net to merchant: -$0.29029
└── Result: 3,003% loss ✗

Lux x402:
├── API request value: $0.01
├── Gas fee: $0.001
├── Facilitator fee: $0.00003 (0.3%)
├── Total fees: $0.00103
├── Net to merchant: $0.00897
└── Result: 10.3% overhead ✓
```

Only on low-fee chains like Lux are micropayments practical.

## High Throughput

Lux LUExchange-Chain provides high throughput, enabling x402 to handle large-scale deployments without network congestion. This means consistent fee levels (no gas price spikes) and scalability for AI agent economies with millions of daily payments.

## EVM Compatibility

Lux LUExchange-Chain is fully EVM-compatible, enabling developers to use familiar tools:
- Web3.js / Ethers.js
- MetaMask
- Hardhat / Foundry
- OpenZeppelin contracts

### Cross-Chain Facilitator Support

EVM compatibility means facilitators can support multiple chains with minimal code changes:

```javascript
// Same facilitator code works across:
- Lux LUExchange-Chain
- Ethereum
- Base
- Polygon
// ... any EVM chain
```

## Native Stablecoin Support

USDC is native to Lux (Circle-issued), providing:

### Official Circle USDC

```javascript
{
  name: "USD Coin",
  symbol: "USDC",
  address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  decimals: 6,
  issuer: "Circle",
  type: "Native" // Not bridged
}
```

**Benefits**:
- No bridge risk
- Direct Circle minting/redemption
- High liquidity
- Institutional trust

### Deep Liquidity

Lux USDC has substantial liquidity:
- Hundreds of millions in daily volume
- Available on major DEXes (Trader Joe, Pharaoh)
- Integrated with CEXes
- Easy on/off ramping

## Cost-Effective Development

### Testnet Testnet

Lux provides a free testnet for development:

```javascript
// Testnet Testnet Configuration
{
  chainId: 43113,
  rpcUrl: "https://api.lux-test.network/ext/bc/C/rpc",
  luxFaucet: "/console/primary-network/faucet",
  usdcFaucet: "https://faucet.circle.com/"
}
```

**Development Benefits**:
- Free test LUX and USDC
- Same API as mainnet
- Test facilitators available
- No cost to experiment

## Real-World Performance

### Actual x402 Performance on Lux

```javascript
{
  averageConfirmation: "1.8s",
  averageGasCost: "$0.001",
  uptime: "99.99%",
  facilitatorLatency: "~200ms"
}

// Total payment time breakdown:
│ Component                 │ Time    │
├──────────────────────────┼─────────┤
│ HTTP request              │ ~50ms   │
│ Server processing         │ ~100ms  │
│ Payment submission        │ ~200ms  │
│ Blockchain confirmation   │ ~1800ms │
│ Facilitator verification  │ ~100ms  │
│ Response delivery         │ ~50ms   │
├──────────────────────────┼─────────┤
│ TOTAL                     │ ~2.3s   │
```

## Economic Sustainability

### Merchant Economics

```javascript
// $0.01 API request profitability analysis

Revenue per request: $0.01
Costs:
├── Gas fee: $0.001
├── Facilitator fee: $0.00003 (0.3%)
├── Infrastructure: $0.0001
└── Total costs: $0.00113

Profit margin: $0.00887 (88.7%) ✓
```

On Lux, micropayment business models are sustainable.

## Summary

Lux LUExchange-Chain is ideal for x402 because of its \~2-second finality, ultra-low fees (~\$0.001), high throughput, EVM compatibility, and native USDC support. These characteristics make micropayments economically viable and enable the AI agent economy that x402 envisions. With dedicated facilitators and comprehensive tooling, Lux provides a strong foundation for x402 payment infrastructure.

## Next Steps

In the following lessons, we'll explore:
- Setting up x402 on Lux (Testnet testnet)
- Available facilitators and their features
- Integration best practices


# Network Setup (/academy/blockchain/x402-payment-infrastructure/04-x402-on-avalanche/02-network-setup)

---
title: Network Setup
description: Setting up x402 on Lux LUExchange-Chain Mainnet and Testnet Testnet.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Settings
---

## Lux Networks Overview

Lux provides two networks for x402 development:

| Network | Purpose | Chain ID | RPC URL |
|---------|---------|----------|---------|
| **Mainnet** | Production | 43114 | https://api.lux.network/ext/bc/C/rpc |
| **Testnet Testnet** | Development | 43113 | https://api.lux-test.network/ext/bc/C/rpc |

## Testnet Testnet Setup

### Step 1: Configure Network in Wallet

Add Testnet testnet to MetaMask or Core wallet:

```javascript
// Network configuration
{
  networkName: "Lux Testnet Testnet",
  rpcUrl: "https://api.lux-test.network/ext/bc/C/rpc",
  chainId: 43113,
  symbol: "LUX",
  explorerUrl: "https://testnet.snowtrace.io/"
}
```

Add Testnet to your wallet using the configuration above. Core Wallet has Testnet pre-configured.

### Step 2: Get Test LUX

Get free test LUX for gas fees:
1. Navigate to the [Console Faucet](/console/primary-network/faucet)
2. Connect your wallet
3. Request test LUX

### Step 3: Get Test USDC

Get free test USDC from Circle's official faucet:
1. Visit [https://faucet.circle.com/](https://faucet.circle.com/)
2. Select "Lux Testnet"
3. Enter your wallet address
4. Receive test USDC

## Contract Addresses

### Mainnet Addresses

```javascript
const LUX_MAINNET = {
  chainId: 43114,
  rpc: "https://api.lux.network/ext/bc/C/rpc",
  usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  usdt: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
  wlux: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7"
};
```

### Testnet Testnet Addresses

```javascript
const LUX_FUJI = {
  chainId: 43113,
  rpc: "https://api.lux-test.network/ext/bc/C/rpc",
  usdc: "0x5425890298aed601595a70AB815c96711a31Bc65",
};
```

## Environment Configuration

For x402 development, configure your environment variables:

```bash
# .env file
LUX_RPC_FUJI=https://api.lux-test.network/ext/bc/C/rpc
USDC_FUJI=0x5425890298aed601595a70AB815c96711a31Bc65
PRIVATE_KEY=your_private_key_here
```

For mainnet deployment, use:
```bash
LUX_RPC_MAINNET=https://api.lux.network/ext/bc/C/rpc
USDC_MAINNET=0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
```

## Summary

Setting up x402 on Lux Testnet testnet requires three steps: configure your wallet with Testnet network, get free test LUX from Core Wallet console, and get free test USDC from Circle's faucet. With these resources, you're ready to integrate x402 facilitators and start building payment-enabled applications.


# x402 Facilitators on Lux (/academy/blockchain/x402-payment-infrastructure/04-x402-on-avalanche/03-facilitators)

---
title: x402 Facilitators on Lux
description: Overview of available x402 facilitators on Lux and how to choose the right one.
updated: 2025-11-03
authors: [Federico Nardelli]
icon: Network
---

## Available Facilitators

Lux supports multiple x402 facilitators, each with different strengths and use cases. All are available at [build.lux.network/integrations](https://build.lux.network/integrations).

## Thirdweb x402

**Best For**: Enterprise applications, multi-chain support, gasless transactions

### Overview

Thirdweb provides enterprise-grade x402 infrastructure with comprehensive SDKs and built-in support for gasless transactions using EIP-7702.

**Official Documentation**: [portal.thirdweb.com/payments/x402/facilitator](https://portal.thirdweb.com/payments/x402/facilitator)

### Key Features

- **Multi-Chain Support**: Works on EVM chains including Lux LUExchange-Chain
- **Gasless Transactions**: EIP-7702 protocol for cost-free user submissions
- **Framework Integration**: x402-hono, x402-next, x402-express middlewares
- **Dashboard Tracking**: Monitor transactions through thirdweb project dashboard
- **Payment Verification**: Automatic signature validation and on-chain settlement
- **Token Support**: ERC-2612 permit and ERC-3009 authorization (USDC)

### Installation

```bash
npm install thirdweb
```

### Quick Start

```typescript
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});
```

**Integration with Hono:**

```javascript
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

app.use(paymentMiddleware(
  "0xYourWalletAddress",
  {
    "/api/service": {
      price: "$0.01",
      network: "lux-c-chain",
      config: {
        description: "Access to your API service"
      }
    }
  },
  {
    facilitator: thirdwebFacilitator
  }
));
```

### Lux Configuration

- **Mainnet**: Use network string `"lux"` (Chain ID: 43114)
- **Testnet Testnet**: Use network string `"lux-testnet"` (Chain ID: 43113)

### Links

- Integration: [build.lux.network/integrations/thirdweb-x402](https://build.lux.network/integrations/thirdweb-x402)
- Documentation: [portal.thirdweb.com/payments/x402/facilitator](https://portal.thirdweb.com/payments/x402/facilitator)

### Pricing

See [thirdweb.com/pricing](https://thirdweb.com/pricing) for current pricing information.

---

## PayAI

**Best For**: AI agents, autonomous payments, low-latency verification

### Overview

PayAI specializes in AI agent payments with optimized APIs for machine-to-machine commerce. Built natively for Lux's fast finality and low transaction costs.

**Official Documentation**: [docs.payai.network/introduction](https://docs.payai.network/introduction)

### Key Features

- **AI-First Design**: Specifically built for agent monetization
- **Lux Native**: Leverages Lux's sub-second finality
- **Simple Integration**: TypeScript and Python SDKs
- **Product Suite**:
  - x402 protocol implementation
  - Freelance AI marketplace
  - CT Agent Monetization
  - Token Gateway

### Installation

```bash
npm install x402-express  # For Express servers
npm install x402-client   # For clients
```

### Quick Start (Server)

```javascript
import express from 'express';
import { paymentMiddleware } from 'x402-express';

const app = express();

app.use(paymentMiddleware(
  "0xYourWalletAddress",
  {
    "/api/service": {
      price: "$0.01",
      network: "lux",
      config: {
        description: "Access to AI service"
      }
    }
  }
));
```

### Quick Start (Client)

```javascript
import { X402Client } from 'x402-client';

const client = new X402Client({
  privateKey: process.env.CLIENT_PRIVATE_KEY,
  facilitatorUrl: 'https://api.payai.network',
  network: 'lux'
});

const response = await client.post('https://api.example.com/service', {
  data: { query: 'your request' }
});
```

### Lux Configuration

- **Mainnet**: Use network string `"lux"`
- **Testnet Testnet**: Use network string `"lux-testnet"`
- **Payment Tokens**: LUX and USDC

### Links

- Integration: [build.lux.network/integrations/payai](https://build.lux.network/integrations/payai)
- Documentation: [docs.payai.network/introduction](https://docs.payai.network/introduction)
- Website: [payai.network](https://payai.network/)

### Pricing

Contact PayAI for pricing information. Developer tier available for testing.

---

## Ultravioleta DAO

**Best For**: Decentralized applications, gasless payments, community governance

### Overview

Ultravioleta is a community-governed facilitator focused on gasless payments and decentralization. Users don't need LUX tokens for transaction fees—the facilitator covers all costs.

**Official Documentation**: [facilitator.ultravioletadao.xyz](https://facilitator.ultravioletadao.xyz)

### Key Features

- **Gasless Payments**: 100% gas coverage—users pay $0 in transaction fees
- **Stablecoin Settlement**: Transactions use USDC for predictable pricing
- **Sub-second Processing**: ~2-3 second end-to-end settlement on Lux
- **Cryptographic Security**: EIP-712 signatures prevent unauthorized transactions
- **Stateless Verification**: On-chain validation eliminates database dependencies
- **Auto-scalable Infrastructure**: High availability and reliability
- **Multi-Network Support**: Lux, Base, Celo, Polygon, Solana, and more
- **Community Governance**: Fully decentralized operation

### Installation

```bash
npm install x402-hono    # For Hono servers
npm install x402-client  # For clients
```

### Quick Start (Server)

```javascript
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

app.use(paymentMiddleware(
  "0xYourWalletAddress",
  {
    "/api/service": {
      price: "$0.01",
      network: "lux-c-chain",
      config: {
        description: "Access to your API service"
      }
    }
  },
  {
    url: 'https://facilitator.ultravioletadao.xyz'
  }
));
```

### Quick Start (Client)

```javascript
import { X402Client } from "x402-client";

const client = new X402Client({
  privateKey: process.env.CLIENT_PRIVATE_KEY,
  facilitatorUrl: 'https://facilitator.ultravioletadao.xyz',
  network: 'lux-c-chain'
});

const response = await client.post('https://api.example.com/service', {
  data: { query: 'your request' }
});
```

### Lux Configuration

- **Mainnet**: Chain ID 43114, USDC settlement, sub-second finality
- **Testnet Testnet**: Chain ID 43113, sandbox environment

### API Endpoints

- `GET /health` - Facilitator health verification
- `GET /supported` - Lists compatible payment schemes and networks
- `POST /verify` - Validates payment signatures and requirements
- `POST /settle` - Executes on-chain transfers via EIP-3009

### Links

- Integration: [build.lux.network/integrations/ultravioletadao](https://build.lux.network/integrations/ultravioletadao)
- Facilitator: [facilitator.ultravioletadao.xyz](https://facilitator.ultravioletadao.xyz)
- Website: [ultravioletadao.xyz](https://ultravioletadao.xyz)

### Pricing

- **Gas Fees**: $0 for users (100% covered by facilitator)
- **Facilitator Fees**: See official documentation for current fee structure

---

## x402-rs

**Best For**: High-performance applications, self-hosted infrastructure, Rust developers

### Overview

x402-rs is a high-performance Rust implementation perfect for latency-sensitive applications. Offers complete control with self-hosted deployment and zero facilitator fees.

**Official Documentation**: [github.com/x402-rs/x402-rs](https://github.com/x402-rs/x402-rs)

### Key Features

- **High Performance**: < 50ms verification time
- **Low Resource Usage**: Minimal CPU/memory footprint
- **Self-Hosted**: Full control over infrastructure
- **Rust Implementation**: Memory-safe and fast
- **Zero Facilitator Fees**: Only blockchain gas costs
- **Stateless Design**: Never holds user funds
- **OpenTelemetry Support**: Integrates with Honeycomb, Prometheus, Grafana
- **Multi-Network**: EVM chains (Lux, Base, Polygon) and Solana

### Docker Quick Start

```bash
docker run --env-file .env -p 8080:8080 ukstv/x402-facilitator
```

**Required Environment Variables:**
```bash
HOST=0.0.0.0
PORT=8080
RPC_URL_LUX_FUJI=https://api.lux-test.network/ext/bc/C/rpc
RPC_URL_LUX=https://api.lux.network/ext/bc/C/rpc
SIGNER_TYPE=private-key
EVM_PRIVATE_KEY=0x...
RUST_LOG=info
```

### Installation (Rust)

```bash
cargo add x402-rs
```

Requirements: Rust 1.80+

### Quick Start (Axum Server)

```rust
use x402_axum::X402Middleware;
use x402_rs::{USDCDeployment, Network};
use axum::{Router, routing::get};

let x402 = X402Middleware::try_from("https://x402.org/facilitator/").unwrap();
let usdc = USDCDeployment::by_network(Network::LuxTestnet);

let app = Router::new().route("/paid-content",
    get(handler).layer(
        x402.with_price_tag(
            usdc.amount("0.025").pay_to("0xYourAddress").unwrap()
        )
    )
);
```

### Quick Start (Client)

```rust
use x402_reqwest::X402ClientExt;
use ethers::signers::PrivateKeySigner;

let signer: PrivateKeySigner = "0x...".parse()?;
let client = reqwest::Client::new()
    .with_payments(signer)
    .prefer(USDCDeployment::by_network(Network::Lux))
    .build();

let res = client.get("https://example.com/protected").send().await?;
```

### Key Components

1. **x402-rs core**: Protocol types, facilitator traits, payment verification/settlement
2. **Facilitator binary**: Production HTTP server for verifying and settling payments
3. **x402-axum**: Axum middleware for protecting routes
4. **x402-reqwest**: Wrapper for transparent client-side payment handling

### Lux Configuration

- **Testnet Testnet**: Set `RPC_URL_LUX_FUJI` for development
- **LUExchange-Chain Mainnet**: Set `RPC_URL_LUX` for production
- Networks are dynamically enabled based on provided RPC URLs

### Links

- Integration: [build.lux.network/integrations/x402-rs](https://build.lux.network/integrations/x402-rs)
- GitHub: [github.com/x402-rs/x402-rs](https://github.com/x402-rs/x402-rs)
- Docker Hub: [hub.docker.com/r/ukstv/x402-facilitator](https://hub.docker.com/r/ukstv/x402-facilitator)

### Pricing

- **Open Source**: Free (Apache-2.0 license)
- **Self-Hosted**: Only gas costs (~$0.001/tx on Lux)
- **Support**: Community-driven

---

## Facilitator Comparison

> **Note**: All x402 facilitators enable gasless payments for end users. Users sign payment authorizations; facilitators submit transactions and pay gas. Some facilitators absorb gas costs completely (e.g., Ultravioleta), while others pass costs to merchants.

| Feature | Thirdweb | PayAI | Ultravioleta | x402-rs |
|---------|----------|-------|--------------|---------|
| **Deployment** | Hosted | Hosted | Hosted | Self-Hosted |
| **Multi-Chain** | ✅ | ✅ | ✅ | ✅ |
| **AI Optimized** | ❌ | ✅ | ❌ | ❌ |
| **DAO Governed** | ❌ | ❌ | ✅ | ❌ |
| **Primary Language** | TypeScript | TypeScript | TypeScript | Rust |
| **Verification Speed** | Fast | Fast | Medium | Very Fast |
| **Dashboard** | ✅ | ✅ | ✅ | ❌ |
| **Best For** | Enterprise | AI Agents | Decentralization | Performance |

*Check official documentation for latest features, pricing, and capabilities.*

---

## Getting Started

1. **Choose a Facilitator**: Based on your use case and requirements
2. **Visit Integration Page**: [build.lux.network/integrations](https://build.lux.network/integrations)
3. **Read Official Docs**: Each facilitator has comprehensive documentation
4. **Install SDK**: Follow the installation instructions above
5. **Test on Testnet**: Use Lux Testnet testnet for development
6. **Deploy to Mainnet**: Go live on Lux LUExchange-Chain

---

## Summary

Lux supports four major x402 facilitators: **Thirdweb x402** (enterprise), **PayAI** (AI agents), **Ultravioleta DAO** (gasless payments), and **x402-rs** (high-performance). Each offers different deployment models, features, and optimizations. Choose based on your specific needs—or use multiple facilitators to give users flexibility.

**All facilitators leverage Lux's sub-second finality and low fees (~$0.001) to make micropayments economically viable.**

For the latest information, pricing, and features, always consult the official documentation linked above.


# Setting Up Your x402 Development Environment (/academy/blockchain/x402-payment-infrastructure/05-hands-on-implementation/01-environment-setup)

---
title: Setting Up Your x402 Development Environment
description: Configure your development environment and set up the x402 starter kit with Thirdweb facilitator.
updated: 2025-12-04
authors: [Federico Nardelli]
icon: Terminal
---

## Introduction

In this lesson, you'll set up everything needed to start building with x402. We'll walk through cloning the starter kit, configuring credentials, and running your first local x402-enabled application on Lux Testnet testnet.

## Prerequisites

Ensure you have the following installed:

- **Node.js 18+**: Download from [nodejs.org](https://nodejs.org/)
  ```bash
  node --version  # Should show v18.0.0 or higher
  ```

- **Git**: Download from [git-scm.com](https://git-scm.com/)

- **Code Editor**: [VS Code](https://code.visualstudio.com/) recommended

- **Wallet**: [Core Wallet](https://core.app/) recommended for Lux

## Step 1: Clone the x402 Starter Kit

Start by downloading the starter kit repository:

```bash
# Clone the repository
git clone https://github.com/luxfi/x402-starter-kit.git

# Navigate into the directory
cd x402-starter-kit
```

## Step 2: Install Dependencies

Install all required packages:

```bash
npm install
```

This installs Next.js 16, Thirdweb SDK v5, x402-next middleware, Tailwind CSS, and TypeScript.

## Step 3: Create Environment File

Create your environment configuration file:

```bash
# Copy the example file
cp .env.example .env.local
```

Now open `.env.local` in your code editor. You'll fill in the values as we create accounts and wallets in the next steps.

The file should look like this:

```bash
# Thirdweb API credentials (you'll add these in Step 4)
THIRDWEB_CLIENT_ID=
THIRDWEB_SECRET_KEY=

# ERC4337 Smart Account address (you'll add this in Step 4)
THIRDWEB_SERVER_WALLET_ADDRESS=

# Your wallet address that receives payments (you'll add this in Step 5)
MERCHANT_WALLET_ADDRESS=
```

## Step 4: Create Thirdweb Account and Get Credentials

Thirdweb provides the facilitator service that handles payment verification and settlement.

### 4.1 Sign Up and Create Project

1. Visit [thirdweb.com/dashboard](https://thirdweb.com/dashboard)
2. Create an account using email, Google, GitHub, or Wallet
3. Click "Create Project"
4. Name your project (e.g., "x402 Payment Demo")
5. Allow all domains (or at least `localhost:3000`)
6. Click "Create"

### 4.2 Get API Credentials

After creating your project:

1. Copy your **Client ID**
2. Copy and save the **"Secret Key"**

**Immediately paste these into your `.env.local` file:**

```bash
THIRDWEB_CLIENT_ID=your_client_id_here
THIRDWEB_SECRET_KEY=your_secret_key_here
```

**Security Note**: Never commit your Secret Key to version control (the `.gitignore` already excludes `.env.local`).

### 4.3 Create ERC4337 Smart Account

The Thirdweb facilitator requires an ERC4337 Smart Account (not a regular EOA wallet). This Smart Account will submit transactions on-chain and sponsor gas fees on behalf of users, enabling gasless payments.

1. In your Thirdweb dashboard, navigate to **Wallets** → **Server Wallets** → *Wallets*
2. Click the toggle **"Show ERC4337 Smart Account"**
3. Choose **"Lux Testnet Testnet"** as the network
4. Copy the wallet address



**Immediately paste this into your `.env.local` file:**

```bash
THIRDWEB_SERVER_WALLET_ADDRESS=...
```

## Step 5: Configure Your Wallet

Core Wallet comes with Lux Testnet pre-configured:

1. Open Core Wallet
2. Turn on **Testnet Mode** in Settings → Advanced

Alternatively, add Testnet manually to any other wallet:
- Network Name: Lux Testnet LUExchange-Chain
- RPC URL: `https://api.lux-test.network/ext/bc/C/rpc`
- Chain ID: `43113`
- Symbol: `LUX`
- Explorer: `https://testnet.snowtrace.io/`

## Step 6: Setup Merchant Wallet Address

Copy and paste your wallet address (this wallet will receive USDC payments from customers) into your `.env.local` file:

```bash
MERCHANT_WALLET_ADDRESS=0xMerchantWalletAddressHere
```

## Step 7: Get Test USDC

Get test USDC for making test payments:

1. Visit [Circle's USDC Faucet](https://faucet.circle.com/)
2. Select "Lux Testnet" network
3. Enter your wallet address
4. Request tokens

Testnet USDC Contract: `0x5425890298aed601595a70AB815c96711a31Bc65`

You don't need test LUX because the facilitator will pay the gas fee.

## Step 8: Verify Your Configuration

Your `.env.local` file should now be completely filled in:

```bash
# Thirdweb API credentials
THIRDWEB_CLIENT_ID=abc123...
THIRDWEB_SECRET_KEY=sk_live_...

# ERC4337 Smart Account address (facilitator wallet)
THIRDWEB_SERVER_WALLET_ADDRESS=0x1234...

# A wallet address (receives payments)
MERCHANT_WALLET_ADDRESS=0x5678...
```

## Step 9: Run the Development Server

Start the application:

```bash
npm run dev
```

## Step 10: Verify Your Setup

Open your browser and navigate to `http://localhost:3000`.

You should see the x402 Starter Kit interface with:
- Header with "x402 Starter Kit"
- Two payment tiers: **Basic (\$0.01)** and **Premium (\$0.15)**
- "Connect Wallet" button
- Transaction log section

If you see this interface, your environment is correctly configured!

## Additional Resources

- [Thirdweb Documentation](https://portal.thirdweb.com/payments/x402/facilitator)
- [x402 Starter Kit Repository](https://github.com/luxfi/x402-starter-kit)
- [ERC4337 Standard](https://eips.ethereum.org/EIPS/eip-4337)


# Making Your First x402 Payment (/academy/blockchain/x402-payment-infrastructure/05-hands-on-implementation/02-first-payment)

---
title: Making Your First x402 Payment
description: Experience the complete x402 payment flow by making your first test payment on Lux Testnet.
updated: 2025-12-04
authors: [Federico Nardelli]
icon: Coins
---

## Step 1: Open Browser DevTools

Open your browser's Developer Tools to observe HTTP requests in real-time:

**Chrome / Edge / Firefox**:
- Press `F12` or right-click → "Inspect"
- Click the **Network** tab
- Keep DevTools open

You'll see the HTTP 402 responses as they happen.

## Step 2: Connect Your Wallet

With the starter kit running at `http://localhost:3000`:

1. Click **"Connect Wallet"**
2. Select Core Wallet
3. Ensure you're on **Lux Testnet Testnet**
4. Approve the connection
5. Your wallet address should display

Your wallet needs:
- Testnet USDC (payment token)

If missing, return [here](/academy/blockchain/x402-payment-infrastructure/05-hands-on-implementation/01-environment-setup#step-7-get-test-usdc) for faucet instructions.

## Step 3: Request Protected Content

Click the **"Pay $0.01"** button on the Basic Tier card.

### Observing HTTP 402

In DevTools Network tab, find the request to `/api/basic`:
- **Status Code**: `402 Payment Required`
- **Response Headers**: Contains `x-payment-request`

The response body shows payment requirements:

```json
{
    "x402Version": 1,
    "error": "X-PAYMENT header is required",
    "accepts": [
        {
            "scheme": "exact",
            "network": "eip155:43113",
            "maxAmountRequired": "10000",
            "resource": "http://localhost:3000/api/basic",
            "description": "",
            "mimeType": "application/json",
            "payTo": "0x41bB3178760536eAfE451aadF4eB5Ac76B9AfcF8",
            "maxTimeoutSeconds": 86400,
            "asset": "0x5425890298aed601595a70AB815c96711a31Bc65",
            "outputSchema": {
                "input": {
                    "type": "http",
                    "method": "GET",
                    "discoverable": true
                }
            },
            "extra": {
                "recipientAddress": "0x20E004611eb983B9De88dACc388Cb1461691d420",
                "facilitatorAddress": "0x41bB3178760536eAfE451aadF4eB5Ac76B9AfcF8",
                "name": "USD Coin",
                "version": "2",
                "primaryType": "TransferWithAuthorization"
            }
        }
    ]
}
```

**Key Fields**:
- `maxAmountRequired`: "10000" = $0.01 USDC (6 decimals)
- `payTo`: Merchant wallet receiving payment
- `asset`: USDC contract address on Testnet
- `network`: "lux-testnet"

This tells the client exactly what payment is required.

## Step 4: Sign the Payment Authorization

Your wallet opens with a signature request. Click **"Sign"**.

### What You're Signing

You're signing an **EIP-712 authorization** (not sending a transaction). This authorizes the facilitator to move USDC from your wallet to the merchant using **EIP-3009** (transferWithAuthorization).

The signature includes:
- From/To addresses
- Amount (0.01 USDC)
- USDC contract address
- Nonce (replay protection)
- Expiration timestamp
- Chain ID (43113)

Because the facilitator submits the transaction, users don't pay gas fees.

## Step 5: Observe Payment Settlement

After signing, watch the payment flow:

Find the second request to `/api/basic`:
- **Status Code**: `200 OK` (payment accepted)
- **Request Headers**: Contains `X-PAYMENT` with your signed authorization
- **Response Headers**: Contains `X-PAYMENT-RESPONSE` with the paid content

## Step 6: Verify on Blockchain Explorer

Check the Transaction History on the Thirdweb dashboard to verify the on-chain settlement:

1. Open the Thirdweb Transaction History page
2. Find your recent transaction in the list
3. Click on the transaction hash to open the block explorer

You'll see the transaction showing 0.01 USDC transferred from your wallet to the merchant wallet. 

<Quiz quizId="5004"/>

# Understanding the Implementation (/academy/blockchain/x402-payment-infrastructure/05-hands-on-implementation/03-understanding-implementation)

---
title: Understanding the Implementation
description: Overview of the starter kit architecture and key files.
updated: 2025-12-04
authors: [Federico Nardelli]
icon: Code
---

## Project Structure

```
x402-starter-kit/
├── app/
│   ├── api/
│   │   ├── basic/route.ts     # $0.01 endpoint
│   │   └── premium/route.ts   # $0.15 endpoint
│   ├── layout.tsx             # ThirdwebProvider wrapper
│   ├── page.tsx               # Main UI
│   └── globals.css
├── lib/
│   ├── constants.ts           # Addresses, endpoints, amounts
│   └── utils.ts
└── components/
```

## Backend: API Route

Each protected endpoint is a Next.js API route. Here's `app/api/basic/route.ts`:

```typescript
import { settlePayment, facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { luxTestnet } from "thirdweb/chains";
import { USDC_FUJI_ADDRESS, PAYMENT_AMOUNTS, API_ENDPOINTS } from "@/lib/constants";

const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY!,
});

const thirdwebFacilitator = facilitator({
  client,
  serverWalletAddress: process.env.THIRDWEB_SERVER_WALLET_ADDRESS!,
});

export async function GET(request: Request) {
  const paymentData = request.headers.get("x-payment");

  const result = await settlePayment({
    resourceUrl: API_ENDPOINTS.BASIC,
    method: "GET",
    paymentData,
    payTo: process.env.MERCHANT_WALLET_ADDRESS!,
    network: luxTestnet,
    price: {
      amount: PAYMENT_AMOUNTS.BASIC.amount,
      asset: { address: USDC_FUJI_ADDRESS },
    },
    facilitator: thirdwebFacilitator,
  });

  if (result.status === 200) {
    return Response.json({
      tier: "basic",
      data: "Welcome to Basic tier!",
      timestamp: new Date().toISOString(),
    });
  } else {
    return Response.json(result.responseBody, {
      status: result.status,
      headers: result.responseHeaders,
    });
  }
}
```

The `settlePayment` function handles everything: if no payment header is present, it returns HTTP 402; if payment is valid, it settles on-chain and returns 200.

## Constants

`lib/constants.ts` centralizes configuration:

```typescript
export const USDC_FUJI_ADDRESS = "0x5425890298aed601595a70AB815c96711a31Bc65";

export const API_ENDPOINTS = {
  BASIC: `${API_BASE_URL}/api/basic`,
  PREMIUM: `${API_BASE_URL}/api/premium`,
};

export const PAYMENT_AMOUNTS = {
  BASIC: { amount: "10000" },    // $0.01 USDC (6 decimals)
  PREMIUM: { amount: "150000" }, // $0.15 USDC
};
```

## Frontend: Layout

`app/layout.tsx` wraps the app with ThirdwebProvider for wallet functionality:

```tsx
import { ThirdwebProvider } from "thirdweb/react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ThirdwebProvider>{children}</ThirdwebProvider>
      </body>
    </html>
  );
}
```

# Module 9 (/academy/entrepreneur/fundraising-finance/09-fundraising/01-introduction)

---
title: Module 9
description: Learn how to approach fundraising as a strategic process to secure capital for your Web3 startup
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## Learning Outcomes

By the end of this module, you will learn how to:
- Structure your fundraising strategy using a sales funnel model
- Build and maintain investor relationships through effective updates
- Time your fundraising efforts strategically
- Determine appropriate valuations for your startup
- Navigate cold outreach to potential investors
- Present metrics that matter to VCs

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"At the earlier stages, fundraising is the conversion of your social capital into committed capital."</span> - Brian Leiberman, Director of Ecosystem Relations at Lux Network
</div>
</Callout>

## Understanding the Fundraising Landscape

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Everybody should start fundraising the day they start their business."</span> - Brian Leiberman, Director of Ecosystem Relations at Lux Network
</div>
</Callout>

<YouTube id="kdTgi4BSisU" params="start=0&rel=0&modestbranding=1" />

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Everybody should start fundraising the day they start their business."</span> - Brian Leiberman, Director of Ecosystem Relations at Lux Network
</div>
</Callout>

Fundraising is fundamentally a sales process with distinct stages: cold outreach, introductory calls, due diligence, and closing. For Web3 founders, this process requires careful preparation, compelling storytelling, and strategic timing.


# The Fundraising Process - A Strategic Approach (/academy/entrepreneur/fundraising-finance/09-fundraising/02-fundraising-process)

---
title: The Fundraising Process - A Strategic Approach
description: Understanding the stages and timeline of effective fundraising for Web3 startups
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## The Fundraising Process: A Clear Path Forward

<YouTube id="kdTgi4BSisU" params="start=0&rel=0&modestbranding=1" />

Successful fundraising begins long before you actually need capital. The most effective founders treat fundraising as an ongoing relationship-building exercise rather than a one-time event.

At its core, early-stage fundraising is about converting social capital into committed capital. This means building relationships with potential investors through consistent updates, transparent communication, and demonstrating growth over time.

### Essential Preparation Materials

For Web3 startups specifically, it's crucial to articulate not just your business model but also your ecosystem impact. Investors want to understand how your project contributes to the broader blockchain landscape while also presenting a viable path to returns.

When preparing for fundraising, you'll need several key materials:
- A concise "teaser" deck (3-5 slides) for initial outreach
- A more detailed pitch deck for investor calls
- A comprehensive data room (e.g. in Notion) for due diligence
- An FAQ document addressing common investor questions
- A tracking system to manage investor conversations

### Strategic Timing

The fundraising timeline benefits from careful planning. Starting with at least six months of runway allows you to negotiate from a position of strength and maintain maximum leverage.

# Why Effective Fundraising Matters for Web3 Startups (/academy/entrepreneur/fundraising-finance/09-fundraising/03-why-fundraising-matters)

---
title: Why Effective Fundraising Matters for Web3 Startups
description: Understanding the unique challenges and opportunities in Web3 fundraising
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Web3 projects face unique challenges in communicating complex technical concepts to investors who may have varying levels of blockchain knowledge. Your ability to simplify and clarify your value proposition directly impacts your fundraising success.

### Beyond Technical Complexity

Moreover, in the Web3 space, founders must be prepared to demonstrate clear market fit, user traction, and ecosystem value beyond speculative tokenomics.

### The Value of Strategic Partners

The right investment partners bring more than just capital — they provide connections, expertise, and credibility that can accelerate your growth in the Web3 space. This makes investor selection as important as the terms of investment.

Consider what each potential investor brings to the table:
- Domain expertise in your vertical
- Network connections to potential customers
- Experience scaling Web3 companies
- Regulatory guidance and compliance support
- Technical advisory capabilities

Strategic investors can often provide value that far exceeds their capital contribution, making them worth considering even at potentially lower valuations than pure financial investors.


# Implementing Your Fundraising Strategy (/academy/entrepreneur/fundraising-finance/09-fundraising/04-implementing-strategy)

---
title: Implementing Your Fundraising Strategy
description: Practical approaches to investor outreach, updates, and valuation
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Bringing Your Fundraising Plan to Life

When approaching fundraising, founders should focus on identifying a lead investor first. Once secured, others will typically follow. Target outreach strategically, avoiding summer and holiday periods when decision-makers are harder to reach.

### Effective Cold Outreach

<YouTube id="5KfskoDfANU" params="start=0&rel=0&modestbranding=1" />

Cold outreach can be effective when personalized and targeted. Generic templates rarely succeed, but thoughtful messages that reference the investor's thesis or portfolio companies can break through. Founders should consider using a sequence approach:
- Day 1: Initial personalized outreach
- Day 3: Generic nudge follow-up
- Day 7: Pattern-breaking follow-up with humor or creative approach

### Monthly Investor Updates

For monthly investor updates the following should be included:
- A brief reminder of your business and mission
- Key metrics and KPIs showing growth
- Recent wins and challenges
- Specific asks for help beyond funding

These updates serve multiple purposes: keeping potential investors warm, demonstrating consistent execution, and building trust through transparency.

### Valuation Considerations

<YouTube id="LDPZPcv2onU" params="start=0&rel=0&modestbranding=1" /> 

Regarding valuation, remember that smaller funds (less than 50M Dollars) tend to be more valuation-sensitive. While valuation matters, optimization for marginal increases might delay progress. At the seed stage, securing the right partners often outweighs extracting every possible dollar of valuation.

Consider the total package:
- Valuation and dilution
- Board composition and control
- Investor reputation and track record
- Speed to close
- Follow-on capacity for future rounds


# Key Take-Aways (/academy/entrepreneur/fundraising-finance/09-fundraising/05-key-takeaways)

---
title: Key Take-Aways
description: Essential lessons for successful Web3 fundraising
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Key Take-Aways

- **Treat fundraising as a sales funnel** with distinct stages requiring different approaches
- **Start relationship-building with investors** months before you need capital
- **Prepare different versions of your pitch materials** for different fundraising contexts
- **Send regular investor updates** that show growth and include specific asks
- **Cold outreach works** when personalized, targeted, and occasionally unconventional
- **Don't over-optimize for valuation** at the expense of securing good partners
- **Focus on the metrics** that truly demonstrate your product's market fit and growth potential
- **Be transparent about challenges**—honesty builds trust with investors

# Additional Learning (/academy/entrepreneur/fundraising-finance/09-fundraising/06-additional-learning)

---
title: Additional Learning
description: Resources to deepen your fundraising knowledge
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Additional Learning

Fundraising Pressure Testing: [Prepare for your Mock Pitch](/academy/entrepreneur/fundraising-finance/09-fundraising/09-prepare-mock-pitch)

### Recommended Resources

- **Books:**
  - "Venture Deals" by Brad Feld and Jason Mendelson
  - "The Art of Startup Fundraising" by Alejandro Cremades

- **Online Courses:**
  - Y Combinator's Startup School Fundraising Course
  - First Round Capital's Pitch Deck Template

- **Tools:**
  - DocSend for tracking investor deck engagement
  - Airtable or Notion for investor CRM
  - Calendly for scheduling investor meetings

### Practice Exercises

1. Create your 3-slide teaser deck
2. Write a sample investor update
3. Draft three personalized cold outreach emails
4. Build a basic financial model
5. Prepare answers to common investor questions


# Flashcards (/academy/entrepreneur/fundraising-finance/09-fundraising/07-flashcards)

---
title: Flashcards
description: Review key fundraising concepts with interactive flashcards
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

## Flashcards

# Module 9: Mastering the Fundraising Game: A Guide for Web3 Entrepreneurs

Use these flashcards to revise your knowledge of some of the most important concepts of the Fundraising module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="fundraising-fundamentals" quizUrl="/academy/entrepreneur/fundraising-finance/09-fundraising/08-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/fundraising-finance/09-fundraising/08-quiz)

---
title: Test Your Knowledge
description: Test your understanding of fundraising concepts
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="601" />
<Quiz quizId="602" />
<Quiz quizId="603" />
<Quiz quizId="604" />
<Quiz quizId="605" />

Fantastic work finishing [Module 9](/academy/entrepreneur/fundraising-finance/09-fundraising/01-introduction)! Completing one module is always impressive, but to be certified at this level, you'll need to finish [Module 9](/academy/entrepreneur/fundraising-finance/09-fundraising/01-introduction), [Module 10](/academy/entrepreneur/fundraising-finance/10-grants/01-introduction), and [Module 11](/academy/entrepreneur/fundraising-finance/11-pitching/01-introduction) to unlock the Web3 Fundraising & Finance Pro certificate. Keep pushing! 💼


# Prepare for your Mock Pitch (/academy/entrepreneur/fundraising-finance/09-fundraising/09-prepare-mock-pitch)

---
title: Prepare for your Mock Pitch
description: Fundraising pressure testing and mock pitch preparation
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Target
---

## Mock Pitch Preparation

A mock pitch is one of the most effective ways to prepare for real investor meetings. It allows you to practice your presentation, refine your messaging, and identify potential weaknesses before facing actual investors.

## Pre-Mock Pitch Checklist

### 1. **Prepare Your Materials**
- [ ] 10-15 slide pitch deck (concise and focused)
- [ ] 3-slide teaser deck for initial outreach
- [ ] Executive summary (1-2 pages)
- [ ] Financial projections and business model
- [ ] Demo or prototype (if applicable)

### 2. **Practice Your Delivery**
- [ ] Time your presentation (aim for 10-15 minutes)
- [ ] Practice transitions between slides
- [ ] Prepare for common questions and objections
- [ ] Record yourself to check pacing and clarity
- [ ] Practice with different time constraints (5 min, 10 min, 20 min)

### 3. **Research Your Audience**
- [ ] Understand the investor's portfolio and focus areas
- [ ] Know their typical check sizes and investment stages
- [ ] Research their recent investments and interests
- [ ] Prepare personalized talking points

## Mock Pitch Structure

### Opening (2-3 minutes)
- **Hook**: Start with a compelling problem or opportunity
- **Solution**: Clearly state what you're building
- **Market**: Size and opportunity
- **Traction**: Key metrics and achievements

### Main Presentation (8-10 minutes)
- **Problem**: Deep dive into the problem you're solving
- **Solution**: Your product/service and how it works
- **Market**: Target market, size, and growth potential
- **Business Model**: How you make money
- **Competition**: Competitive landscape and differentiation
- **Team**: Key team members and their expertise
- **Financials**: Revenue projections and key metrics
- **Ask**: What you're looking for and how you'll use the funds

### Closing (2-3 minutes)
- **Next Steps**: What happens after the meeting
- **Timeline**: When you're looking to close the round
- **Questions**: Open the floor for investor questions

## Common Questions to Prepare For

### About Your Business
- What problem are you solving and for whom?
- How big is the market opportunity?
- What makes your solution unique?
- How do you plan to acquire customers?
- What's your path to profitability?

### About Your Team
- Why are you the right team to solve this problem?
- What relevant experience do you have?
- How will you scale the team?
- What are your biggest weaknesses?

### About the Market
- Who are your main competitors?
- How do you differentiate from them?
- What are the barriers to entry?
- How do you plan to defend your market position?

### About Fundraising
- How much are you raising and why?
- How will you use the funds?
- What's your timeline for the next round?
- What's your exit strategy?

## Mock Pitch Best Practices

### Do's
- **Be concise**: Respect the time limit
- **Tell a story**: Make it engaging and memorable
- **Use data**: Support claims with metrics and evidence
- **Be honest**: Acknowledge challenges and risks
- **Practice**: Rehearse multiple times
- **Get feedback**: Ask for honest feedback from mock investors

### Don'ts
- **Don't oversell**: Avoid unrealistic projections
- **Don't ignore questions**: Address concerns directly
- **Don't rush**: Speak clearly and at a good pace
- **Don't be defensive**: Stay open to feedback
- **Don't forget the ask**: Always end with a clear ask

## Post-Mock Pitch Analysis

After each mock pitch session:

1. **Gather Feedback**: Ask specific questions about clarity, persuasiveness, and areas for improvement
2. **Identify Patterns**: Look for recurring questions or concerns
3. **Refine Materials**: Update your deck based on feedback
4. **Practice More**: Address identified weaknesses in subsequent practices
5. **Track Progress**: Note improvements over multiple sessions

## Finding Mock Pitch Partners

- **Other Entrepreneurs**: Fellow founders in your network
- **Advisors**: Board members or mentors
- **Industry Experts**: People familiar with your market
- **Investor Relations**: Some VCs offer practice sessions
- **Accelerator Programs**: Many provide pitch practice opportunities
- **Online Communities**: Founder groups and forums

## Success Metrics

A successful mock pitch should result in:
- Clear understanding of your business model
- Confidence in your presentation skills
- Refined messaging and positioning
- Strong answers to common questions
- Readiness for real investor meetings

Remember: The goal of a mock pitch isn't to get investment, but to improve your presentation and identify areas for improvement.


# Module 10 (/academy/entrepreneur/fundraising-finance/10-grants/01-introduction)

---
title: Module 10
description: What Lux Foundation grants are and how they differ from other funding paths
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module
Learn how to secure funding and support for your Web3 startup through the Lux Foundation's grant programs.

## Learning Outcomes
By the end of this module, you will learn how to:
- Understand the different funding options available through the Lux ecosystem
- Develop a compelling grant application that stands out
- Avoid common application mistakes that lead to rejection
- Leverage ecosystem resources beyond just financial support
- Maximize your chances of receiving an Lux Foundation grant

## Introduction to Lux Foundation Grants

<YouTube id="UcEB2hJxtMo" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Daniel Ortiz, Senior Program Manager at Lux Foundation
</p>

The Lux Foundation offers various funding opportunities for builders in the Web3 space. Unlike venture capital investments that prioritize monetary returns, foundation grants focus on creating ecosystem impact and supporting projects committed to the long-term growth of Lux.

These grants are ideal for projects that fill ecosystem gaps, create public goods, or add significant value to the Lux community. Before applying, it's important to understand how grants differ from other foundation offerings:

### Funding Pathways

<YouTube id="dAZ-zA2Y07c" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Daniel Ortiz, Senior Program Manager at Lux Foundation
</p>

- **Foundation Grants**: Support ecosystem impact vs. monetary returns
- **Blizzard**: VC-style funding for revenue-generating projects
- **Hackathons**: Very early-stage ideas and MVPs
- **Codebase**: Accelerator with mentorship, focused on moving from MVP to product

The [grant programs](https://build.lux.network/grants) themselves (infrastructure, AI, retro) are designed to fill specific ecosystem gaps, operate on a milestone-based structure, and remain open year-round for applications.




# Successful Grant Applications (/academy/entrepreneur/fundraising-finance/10-grants/02-success-criteria)

---
title: Successful Grant Applications
description: The four key areas reviewers evaluate
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="j0MTwg5G5EU" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
    Learn from Daniel Ortiz, Senior Program Manager at Lux Foundation
</p>

The Lux Foundation evaluates applications based on four key areas:

### 1. Problem Identification and Ecosystem Fit

Successful applicants clearly identify a gap in the ecosystem and demonstrate how their project addresses this need. This requires thorough research and understanding of both the problem and how your solution fits into the broader Lux ecosystem.

<YouTube id="aQvAPo_MVYU" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Daniel Ortiz, Senior Program Manager at Lux Foundation
</p>

### 2. Proof of Ability to Deliver

The foundation looks for evidence that you can execute your vision. This might include:
- A track record of shipping products
- A realistic, detailed roadmap
- Evidence of technical capabilities
- Examples of past work or a working prototype

### 3. Community Traction and Engagement

Projects that already have connections within the Lux or broader Web3 community stand a better chance. This demonstrates both your commitment to the ecosystem and provides validation for your concept.

### 4. Long-term Ecosystem Impact

Grant applicants should articulate how their project contributes to Lux's growth over time. This might include increasing transaction volumes, attracting new users, creating infrastructure that others can build upon, or filling a critical gap.

<YouTube id="6AKe7sGgqEA" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Daniel Ortiz, Senior Program Manager at Lux Foundation
</p>

Learning about effective market potential communication provides a strong foundation for understanding how to convey value propositions and growth opportunities to diverse audiences.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"The most effective ways of communicating market potential to us at the Foundation include articulating the unique value proposition that your product has, demonstrating an existing customer base or B2B clients, outlining milestones that you're committed to, showing proven product-market fit and past traction in other ecosystems, and providing a thorough competitor analysis."</span> - Xenia Soborova, former Ecosystem Coordinator at Lux Foundation
</div>
</Callout>

<YouTube id="3EkIYQaOnmo" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Xenia Soborova, former Ecosystem Coordinator at Lux Foundation
</p> 



# Common Mistakes (/academy/entrepreneur/fundraising-finance/10-grants/03-common-mistakes)

---
title: Common Mistakes
description: The pitfalls that lead to rejections
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Common Application Mistakes to Avoid

### Technical and Strategic Gaps
- Under-explaining ecosystem impact and value proposition
- Missing quantitative data (users, volume, TVL, projections)
- Failing to specify grant usage and funding rationale
- Overly lengthy proposals without clear executive summaries

### Grant Hunting Red Flags for Grant Reviewers
- Applying across ecosystems without Lux-specific reasoning
- Waiting for grant approval before starting to build
- Lack of competitor analysis and differentiation
- No contingency plans if the grant is rejected

<YouTube id="3Eb2eRz4iuE" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Daniel Ortiz, Senior Program Manager at Lux Foundation
</p>



# Maximizing Support (/academy/entrepreneur/fundraising-finance/10-grants/04-beyond-funding)

---
title: Maximizing Support
description: Beyond Funding - Learn how to leverage Lux's Foundation Support channels to multiply your grant's impact
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Successful grantees emphasize that the financial aspect is just one part of the value. The Lux Foundation offers extensive support beyond funding.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"We don't just want to fund projects. We want to fund ecosystem participants. We want developers to collaborate with each other, we want them to be active and engaged on Telegram groups with other builders. We want them to be just essentially part of the community."</span> - Daniel Ortiz, Senior Program Manager at Lux Foundation
</div>
</Callout>


- Business development connections within and outside the ecosystem
- Co-marketing and visibility opportunities
- Technical support from the developer relations team
- Credibility boost for fundraising and partnerships
- Access to a large, engaged early adopter community

<YouTube id="DrdM-n4SxM8" params="start=0&rel=0&modestbranding=1" />


# Key Take-Aways (/academy/entrepreneur/fundraising-finance/10-grants/05-key-takeaways)

---
title: Key Take-Aways
description: Practical principles to strengthen your application
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

1. **Be bold but realistic**: Lux wants to hear moonshot pitches, but they need to be grounded in reality with clear execution plans.

2. **Build before you apply**: Don't wait for a grant to start building. Having a prototype or proof of concept significantly strengthens your application.

3. **Connect with the community**: Engage with the Lux ecosystem before, during, and after your application process.

4. **Focus on ecosystem impact**: Clearly articulate how your project contributes to Lux's growth and addresses specific ecosystem needs.

5. **Prepare for partnerships**: The foundation can connect you with other projects, validators, and institutional partners - be ready to collaborate.




# Flashcards (/academy/entrepreneur/fundraising-finance/10-grants/06-flashcards)

---
title: Flashcards
description: Reinforce key concepts from this module
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 10: Building a Successful Web3 Startup: Navigating the Lux Foundation Grants Process

Use these flashcards to revise your knowledge of some of the most important concepts of the Grants module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="grants-process" quizUrl="/academy/entrepreneur/fundraising-finance/10-grants/07-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>




# Test Your Knowledge (/academy/entrepreneur/fundraising-finance/10-grants/07-quiz)

---
title: Test Your Knowledge
description: Quick quiz to assess understanding
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="901" />

<Quiz quizId="902" />

<Quiz quizId="903" />

<Quiz quizId="904" />

<Quiz quizId="905" />

Excellent progress on [Module 10](/academy/entrepreneur/fundraising-finance/10-grants/01-introduction)! You're making great strides. Remember, to unlock the Web3 Fundraising & Finance Pro certificate, you'll need to complete [Module 9](/academy/entrepreneur/fundraising-finance/09-fundraising/01-introduction), [Module 10](/academy/entrepreneur/fundraising-finance/10-grants/01-introduction), and [Module 11](/academy/entrepreneur/fundraising-finance/11-pitching/01-introduction). Keep up the momentum! 💰


# Module 11 (/academy/entrepreneur/fundraising-finance/11-pitching/01-introduction)

---
title: Module 11
description: Master the art of turning complex Web3 concepts into compelling investor narratives
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Be brave enough to vulnerably show up as yourself. And use your own voice to tell us your story."</span> - Margo van de Linde, Pitch Coach and Performer
</div>
</Callout>

## Learning Outcomes

Learn how to craft compelling narratives that turn complex Web3 concepts into investor-ready pitches.

By the end of this module, you will learn how to:

- Design a pitch deck that balances technical information with engaging storytelling
- Translate complex Web3 concepts into relatable stories for non-technical investors
- Build credibility as an early-stage founder through strategic narrative frameworks
- Implement advanced presentation techniques that connect with investors emotionally
- Incorporate Web3-specific elements like tokenomics and community into your narrative



# Effective Pitch Storytelling (/academy/entrepreneur/fundraising-finance/11-pitching/02-effective-pitch-storytelling)

---
title:  Effective Pitch Storytelling
description: Transform technical complexity into stories that resonate with investors emotionally and intellectually
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### The Power of Narrative in Web3 Pitching

Creating a compelling pitch for your Web3 startup requires more than just technical knowledge—it demands storytelling skills that connect with investors on both intellectual and emotional levels. While many founders excel at explaining the mechanics of their protocols, they often struggle to translate this complexity into narratives that resonate with potential investors. 

Effective pitch storytelling involves separating your visual presentation from your speaking script, using simple language, and structuring your pitch as a complete story with a beginning, middle, and end. The most successful pitches balance technical information with personal connection, showing not just what your product does, but why it matters.

### Crafting Your Pitch Narrative

<YouTube id="GToKTlrHY3w" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from pitch coach and performer <a href="https://margovandelinde.com/" target="_blank" rel="noopener noreferrer" style={{ color: '#0066cc', textDecoration: 'underline' }}>Margo van de Linde</a>
</p> 

Designing an effective pitch deck starts with simplicity. Many Web3 founders make the mistake of including too much technical information in their slides and speaking points, creating information overload for investors. Instead, create simple, word-conscious slides that serve as visual cues rather than text-heavy presentations.

Your pitch should open with a strong hook—either a concise one-liner that encapsulates your company's identity, impact, and future vision, or an engaging question that pulls your audience in. This opening should use natural language that matches your speaking style, making you appear authentic rather than rehearsed.

Structure your entire presentation as a complete story with a clear arc, building toward a climax. Consider incorporating one of these proven narrative frameworks:

1. **The Hero's Journey**: Position your company as overcoming obstacles to create meaningful change
2. **The Bridge Story**: Show how your solution connects a significant problem with an innovative solution
3. **The Twist Ending**: Demonstrate how the market is heading in the wrong direction until your solution changes everything

Don't be afraid to show vulnerability and personal connection to your work. Share your founding team's origin stories, explain your personal motivation, and articulate why your specific team is uniquely positioned to solve this particular challenge.

### Translating Technical Concepts for Non-Technical Investors

<YouTube id="MXZvfSSKmZY" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from pitch coach and performer <a href="https://margovandelinde.com/" target="_blank" rel="noopener noreferrer" style={{ color: '#0066cc', textDecoration: 'underline' }}>Margo van de Linde</a>
</p> 

One of the biggest challenges for Web3 founders is making complex technical concepts accessible to investors who may not have deep blockchain knowledge. Start by thoroughly researching your audience—their investment history, backgrounds, and interests—to tailor your message appropriately.

Lead with personal connections to humanize your pitch before diving into technical explanations. When explaining complex protocols, use this effective metaphor framework:
- First compare to other Web3 solutions they might be familiar with
- Then relate to real-world experiences they can understand
- Structure your explanation as: Known truth → Your specific change → Vision of the transformed future

Paint a vivid picture of the post-solution world rather than focusing exclusively on technical mechanics. Help investors see how users will benefit from your solution, not just how it works.


# Building Credibility (/academy/entrepreneur/fundraising-finance/11-pitching/03-building-credibility)

---
title: Building Credibility
description: Build authentic credibility through honest positioning and strategic narrative frameworks
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="aNgUyD1iYHs" params="start=0&rel=0&modestbranding=1" /> 

Early-stage founders often feel pressure to oversell their progress to appear credible. However, honesty about your current stage is more persuasive than exaggeration. Own where you are in your founder journey while demonstrating your dedication through research, community engagement, and a clear vision.

Frame your journey using the Context, Content, and Climb structure:
- Context: Market positioning, differentiation, outreach efforts, and social proof
- Content: User journey and expected outcomes 
- Climb: Short-term concrete actions plus long-term projections

Throughout your pitch, highlight one core unique insight that only your team can deliver. This demonstrates your special understanding of the problem space and positions you as the right team to execute the solution.


# Advanced Techniques (/academy/entrepreneur/fundraising-finance/11-pitching/04-advanced-techniques)

---
title:  Advanced Techniques
description: Stand out with strategic presentation techniques
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="ZWtqA6qTiqM" params="start=0&rel=0&modestbranding=1" /> 

To stand out from generic pitches, take calculated personal risks in your presentation style. Open with casual audience questions that acknowledge their expertise, share personal anecdotes that connect to business value, and speak with confidence using phrases like "We learned/know/saw" rather than "We think."

Strategically leave information gaps to prompt follow-up conversations, and close with a personal commitment statement explaining why stopping isn't an option for you. When discussing communities or tokens, focus on the change they create rather than just technical mechanics:
- What growth does this community enable?
- What incentives does this token create? 
- Why is Web3 the only solution path?


# Prepare for Pitch Success (/academy/entrepreneur/fundraising-finance/11-pitching/05-pitch-success)

---
title: Prepare for Pitch Success
description: Master preparation techniques and Q&A strategies for memorable pitch performances
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="oFqgBB45RUI" params="start=0&rel=0&modestbranding=1" /> 

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"It's important to create a deck that is simple in its language and where you've reflected on the value of each and every word. People tend to stuff lots of highly technical information into their deck and way of speaking. This makes presentations very heavy."</span> - Margo van de Linde, Pitch Coach and Performer
</div>
</Callout>

Preparation is the most critical part of your performance when it comes to pitching. Before your presentation, use this anchoring process:
- Identify the key topic per segment, distilling each to a single word
- Connect personally by asking: Why does this matter to me?
- Choose an intentional energy level for each section
- Center yourself by asking "Why am I here today?" and use your answer as a speaking foundation

For five-minute pitches (common in accelerator programs like Codebase):
- Create a deck for a five-minute pitch that is complete enough to get the relevant information across, while being as minimal as possible; containing cue words that trigger script memory.
- Memorize your script thoroughly and practice until delivery feels natural
- Edit ruthlessly—less information with more impact is better
- Strategically set up questions you want to be asked during Q&A

Don't neglect Q&A preparation. Research jury members and their likely question styles, practice handling both easy and difficult questions with your team, and prepare for expertise gaps and technical deep-dives.


# Why This Matters (/academy/entrepreneur/fundraising-finance/11-pitching/06-why-it-matters)

---
title:  Why This Matters
description: Navigate unique Web3 pitching challenges
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="dGYUHiR09eI" params="start=0&rel=0&modestbranding=1" /> 

Web3 startups face unique challenges when pitching to investors. The technology is often complex, the value propositions can be abstract, and many investors may not fully understand blockchain fundamentals. Learning to craft compelling narratives helps bridge this knowledge gap.

Additionally, Web3 projects frequently involve elements like tokenomics, community governance, and ecosystem development that don't exist in traditional startups. Being able to explain these components clearly and show their value is essential for securing investment.

<YouTube id="fYwHZYDuf1I" params="start=0&rel=0&modestbranding=1" /> 

Mastering pitch storytelling also helps founders clarify their own thinking. The process of distilling complex technical ideas into simple, compelling narratives forces you to identify what truly matters about your project and why anyone should care.


# Applying Concepts (/academy/entrepreneur/fundraising-finance/11-pitching/07-applying)

---
title: Applying Concepts
description: Practical exercises to implement storytelling principles in your Web3 pitch
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

To apply these storytelling principles to your Web3 startup:

1. **Audit your current pitch deck**: Remove unnecessary technical details, reduce text on slides, and ensure each slide serves as a visual cue rather than an information dump.

2. **Craft your opening**: Write a one-sentence description of your company that covers identity, impact, and vision. Test it with both technical and non-technical listeners.

3. **Choose your narrative framework**: Decide whether Hero's Journey, Bridge Story, or Twist Ending best fits your startup's situation and adapt your pitch accordingly.

4. **Practice translating technical concepts**: Take your most complex protocol or feature and explain it to someone with no blockchain knowledge using the metaphor framework.

5. **Document your Context, Content, and Climb**: Map out your market positioning, user journey, and both short and long-term projections.

6. **Prepare your anchoring process**: For each section of your pitch, identify the key concept, personal connection, and appropriate energy level.

7. **Review yourself**: Practice your pitch on camera, then watch it with the sound off (for body language) and listen with your eyes closed (for vocal delivery). If you don't like recording yourself, you can do this same exercise in front of a friend and ask for feedback.

8. **Develop a Q&A preparation document**: List potential questions from different stakeholder perspectives and craft concise, confident answers.


# Key Take-Aways (/academy/entrepreneur/fundraising-finance/11-pitching/08-key-takeways)

---
title: Key Take-Aways
description: Essential pitching principles from visual design to authentic storytelling techniques
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

- **Separate visuals from script**: Create simple slides with visual cues, not text-heavy information dumps.

- **Structure as a complete story**: Use narrative frameworks like Hero's Journey, Bridge Story, or Twist Ending to engage investors emotionally.

- **Translate complexity through metaphors**: Compare technical concepts to Web3 solutions investors know, then to real-world experiences they understand.

- **Build credibility honestly**: Own your current stage while demonstrating dedication through the Context, Content, and Climb framework.

- **Take calculated presentation risks**: Show your authentic self, share personal connections to your work, and leave strategic information gaps.

- **Prepare thoroughly for five-minute pitches**: Create a minimal deck, memorize your script, edit ruthlessly, and anticipate Q&A.

- **Focus on change created**: When discussing communities or tokens, emphasize the transformation they enable, not just how they work.



# Flashcards (/academy/entrepreneur/fundraising-finance/11-pitching/09-flashcards)

---
title: Flashcards
description: Review key pitching concepts with interactive flashcards
updated: 2025-01-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 11: Master the Art of Pitching Your Web3 Startup

Use these flashcards to revise your knowledge of some of the most important concepts of the Pitching module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="pitching-fundamentals" quizUrl="/academy/entrepreneur/fundraising-finance/11-pitching/10-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>

# Test Your Knowledge (/academy/entrepreneur/fundraising-finance/11-pitching/10-quiz)

---
title: Test Your Knowledge
description: Test your understanding of pitching concepts
updated: 2025-01-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="1101" />
<Quiz quizId="1102" />
<Quiz quizId="1103" />
<Quiz quizId="1104" />
<Quiz quizId="1105" />

Congratulations on completing [Module 11](/academy/entrepreneur/fundraising-finance/11-pitching/01-introduction)! You've now mastered the art of pitching - a critical skill for any entrepreneur. If you've also completed [Module 9](/academy/entrepreneur/fundraising-finance/09-fundraising/01-introduction) and [Module 10](/academy/entrepreneur/fundraising-finance/10-grants/01-introduction), you've unlocked the **Web3 Fundraising & Finance Pro** certificate! Check your Builder's Hub profile to download it. Your fundraising journey is complete! 🚀

# Module 4 (/academy/entrepreneur/go-to-market/04-gtm-strategies/01-introduction)

---
title: Module 4
description: Learn proven strategies to identify and engage high-potential clients in the Web3 ecosystem
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module

Discover effective strategies to spot and connect with high-potential clients in the Web3 ecosystem.

## Learning Outcomes

By the end of this module, you will learn how to:
- Develop a structured go-to-market (GTM) framework for your Web3 startup
- Create and refine your Ideal Customer Profile (ICP)
- Build effective community engagement strategies
- Implement an educational approach to blockchain adoption
- Measure the right metrics for different stages of development
- Navigate the unique challenges of Web3 partnership development

## Understanding GTM in the Web3 Context

<YouTube id="W4sE359QRuc" params="start=0&rel=0&modestbranding=1" />

A Go-To-Market (GTM) strategy is a comprehensive plan that outlines how a company will reach target customers and achieve a competitive advantage. In the Web3 space, this process requires special consideration of blockchain technology's unique positioning, customer education needs, and community-building requirements.

Web3 startups face different challenges than traditional companies. Potential clients often fall into two categories: those extremely interested in blockchain technology and those concerned about its privacy and security implications. This dichotomy requires a flexible, education-focused approach to market penetration.

# Building a Structured GTM Framework (/academy/entrepreneur/go-to-market/04-gtm-strategies/02-structured-framework)

---
title: Building a Structured GTM Framework
description: Learn how to create a systematic approach to reach and convert your target customers
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Key Elements

<YouTube id="LD4T3Y2B5dI" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Blerify CEO Marcos Allende López • <a href="https://blerify.com/" target="_blank" rel="noopener noreferrer" style={{ color: '#0066cc', textDecoration: 'underline' }}>Visit Blerify</a>
</p> 

An effective GTM strategy for Web3 follows a structured approach that helps you systematically identify, reach, and convert your target customers.

1. Identify your target company types
2. Define specific target roles within those companies
3. Leverage founder networks for initial client acquisition
4. Build success stories that can be documented and replicated
5. Develop a clear Ideal Customer Profile (ICP)
6. Scale through dedicated sales teams once initial traction is achieved

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Using your connections is important in order to get the first clients."</span> - Marcos Allende Lopez, Co-Founder of Blerify
</div>
</Callout>

For early-stage startups that might not have a strong track-record to rely on, focusing on founder connections is particularly important. Personal networks often provide the first opportunities to demonstrate product value.

# Web3-Specific Market Considerations (/academy/entrepreneur/go-to-market/04-gtm-strategies/03-web3-market-considerations)

---
title: Web3-Specific Market Considerations
description: Navigate the unique challenges and opportunities of marketing blockchain solutions
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Web3 products often require more educational marketing than traditional offerings. When approaching potential clients, be prepared to:

- Explain the benefits of decentralization in simple, accessible terms
- Highlight the transparency and verification advantages that blockchain offers
- Demonstrate how your solution addresses interoperability challenges
- Address privacy and security concerns directly
- Position blockchain as trusted infrastructure rather than speculative technology

### Case Studies in Successful Web3 GTM

Two distinct approaches to Web3 GTM strategy demonstrate the flexibility required in this space:

<YouTube id="p0fg_9EQGTI" params="start=0&rel=0&modestbranding=1" /> 

**Identity Solutions Approach:**
- Target specific industries (identity providers, government agencies)
- Work with a small number of high-impact clients on national-level projects
- Consolidate early projects to maximize success stories
- Replicate the model to expand into additional regions
- Focus on developer communities that influence adoption decisions

**AI Layer 1 Evolution:**
- Begin with enterprise-focused B2B SaaS offerings
- Leverage ecosystem relationships and angel investors
- Target specific blockchain ecosystems (L1s and L2s)
- Differentiate through pricing and engineering quality
- Transition metrics from revenue to ecosystem growth as the business model evolves


# Optimizing Your GTM Execution (/academy/entrepreneur/go-to-market/04-gtm-strategies/04-optimizing-execution)

---
title: Optimizing Your GTM Execution
description: Learn practical strategies to implement and refine your go-to-market approach
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Successful Web3 GTM implementation involves:

- Smart marketing that moves faster than product integration
- Setting achievable goals within 1-3 month timeframes
- Recognizing that Web3 partnerships are often easier to close than Web2
- Preparing for long sales cycles with larger organizations
- Building flexibility into your strategy to adapt to rapid market changes
- Leveraging your investment base for partnership opportunities

## Why This Matters for Web3 Startups

The Web3 space presents unique opportunities and challenges for entrepreneurs. Unlike traditional markets, blockchain adoption often requires both technical education and trust-building. Your GTM strategy must account for these factors.

Blockchain curiosity varies dramatically across potential clients. Some are eager to adopt cutting-edge technology, while others require convincing about its practical benefits. Your approach must be adaptable to both audiences.

For Web3 startups, community building isn't just a marketing tactic—it's a fundamental business requirement. Developer communities often influence organization-wide adoption decisions, making community engagement a critical part of your GTM strategy.


# Applying GTM Principles to Your Startup (/academy/entrepreneur/go-to-market/04-gtm-strategies/05-applying-principles)

---
title: Applying GTM Principles to Your Startup
description: Practical steps to implement an effective go-to-market strategy for your Web3 venture
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---
To implement an effective GTM strategy for your Web3 startup:

1. **Map Your Target Market:**
   - Identify specific company types that would benefit from your solution
   - Define detailed personas of decision-makers within those companies
   - Determine which regions or sectors offer the strongest initial opportunities

2. **Leverage Your Network:**
   - Activate founder connections for early pilots and proof-of-concept projects
   - Document these early implementations thoroughly
   - Use these success stories to approach similar potential clients

3. **Refine Your Messaging:**
   - Develop clear, jargon-free explanations of your blockchain implementation
   - Emphasize practical benefits rather than technical specifications
   - Address common concerns proactively in your materials

4. **Build Community Strategically:**
   - Identify developer communities that influence your target clients
   - Provide educational resources that position your solution
   - Create opportunities for technical stakeholders to experience your product

5. **Set Realistic Metrics:**
   - For early-stage startups, focus on quality of engagement over quantity
   - Adjust your metrics as you evolve (from revenue to ecosystem growth if appropriate)
   - Recognize that sales cycles may be longer than in traditional sectors

6. **Prepare for Adaptation:**
   - Set short-term goals (1-3 months) that allow for strategic adjustments
   - Build flexibility into your approach to accommodate market changes
   - Be ready to educate clients who may be unfamiliar with blockchain technology


# Key Take-Aways (/academy/entrepreneur/go-to-market/04-gtm-strategies/06-key-takeaways)

---
title: Key Take-Aways
description: Essential insights for building an effective Web3 go-to-market strategy
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

- **Structured Approach:** Follow a systematic GTM framework that identifies target companies, defines personas, leverages networks, and builds replicable success stories.

- **Education Focus:** Be prepared to explain blockchain benefits in simple terms, addressing both curiosity and concerns about the technology.

- **Community Importance:** Developer communities often influence adoption decisions, making them a critical component of your GTM strategy.

- **Flexible Metrics:** Your success measurements should evolve with your business, potentially shifting from revenue to ecosystem growth metrics as you scale.

- **Realistic Timeframes:** Focus on achievable goals within 1-3 month periods, allowing for adaptation in a rapidly changing market.

- **Network Leverage:** Your founder connections and investment base can be powerful resources for early partnerships and client acquisition.

- **Web3 Advantage:** Recognize that Web3 partnerships can often close more quickly than traditional Web2 collaborations, but prepare for longer sales cycles with larger organizations.

# Flashcards (/academy/entrepreneur/go-to-market/04-gtm-strategies/07-flashcards)

---
title: Flashcards
description: Key terms and definitions for go-to-market strategies in Web3
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 4: Effective Go-To-Market Strategies for Web3 Startups

Use these flashcards to revise your knowledge of some of the most important concepts of the GTM Strategies module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="go-to-market" quizUrl="/academy/entrepreneur/go-to-market/04-gtm-strategies/08-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/go-to-market/04-gtm-strategies/08-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of go-to-market strategies
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="923" />

<Quiz quizId="924" />

<Quiz quizId="925" />

<Quiz quizId="926" />

<Quiz quizId="927" />

Fantastic! You've wrapped up **[Module 4](/academy/entrepreneur/go-to-market/04-gtm-strategies/01-introduction)**, which is a great accomplishment on its own. But to be certified at this level, you'll need to complete [Module 4](/academy/entrepreneur/go-to-market/04-gtm-strategies/01-introduction), [Module 5](/academy/entrepreneur/go-to-market/05-sales/01-introduction), and [Module 6](/academy/entrepreneur/go-to-market/06-pricing/01-introduction) and unlock the Web3 Go-To-Market Strategist certificate. Keep going—you're on track! 🌍


# Module 5 (/academy/entrepreneur/go-to-market/05-sales/01-introduction)

---
title: Module 5
description: Learn to transform your Web3 concept into a customer-focused offer that drives engagement and conversions.
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module

Learn to transform your Web3 concept into a customer-focused offer that drives engagement and conversions.

## Learning Outcomes

By the end of this module, you will learn how to:
- Define your product's core value proposition beyond technical features
- Identify and understand your ideal customer persona
- Build relationships with early customers that lead to case studies
- Structure effective outreach and sales calls
- Implement systems to track leads without feeling overwhelmed
- Determine when and how to expand your sales team

## Introduction to Effective Sales for Web3 Startups

<YouTube id="ra9iTwRZrF8" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn to transform your Web3 concept into a customer-focused offer that drives engagement and conversions
</p>

### The Foundation of Successful Sales

Building a successful Web3 startup requires more than just innovative technology—it demands effective communication of value. Many founders become so immersed in technical details that they forget customers care more about solutions to their problems than the underlying blockchain architecture.


# Defining Your Value Proposition (/academy/entrepreneur/go-to-market/05-sales/02-defining-value-proposition)

---
title: Defining Your Value Proposition
description: Learn how to articulate your product's core value beyond technical features
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### Defining Your Value Proposition

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"The first thing you should do to start selling your product as a founder is to so clearly define the problem you're solving and then the solution that you're offering at the highest level."</span> - Zoe Leavitt, Co-Founder at <a href="https://glass.fun" target="_blank" rel="noopener noreferrer">glass.fun</a>
</div>
</Callout>

The most successful founders can clearly articulate their solution at the highest level. Instead of positioning your offering as a "blockchain-based loyalty program," focus on the emotional benefit: "We create new revenue by bringing your consumers back again and again."

To discover your core value proposition, conduct a "why" exercise with your co-founders:
1. State your solution (e.g., "loyalty platform")
2. Ask "why does this matter?" repeatedly
3. Continue until you reach the simplest, most foundational benefit
4. Use this foundational benefit to shape all your messaging

Remember that you're not selling technology—you're selling outcomes like increased revenue, reduced costs, saved time, or improved experiences.


# Understanding Your Buyer (/academy/entrepreneur/go-to-market/05-sales/03-understanding-your-buyer)

---
title: Understanding Your Buyer 
description: Identify and map the key stakeholders in your sales process and build traction
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### Understanding Your Buyer

Before approaching potential customers, create a specific list of the people to whom your solution applies. For B2B sales, identify exact job titles (CMOs, marketing managers, CFOs) who would benefit from your product.

Consider the different motivations between buyers and users. In enterprise settings, the person purchasing your product often differs from the person using it daily. A pitch about replacing manual processes might appeal to a VP but concern the analyst whose job could be affected.

Map all stakeholders involved in purchasing decisions, especially for enterprise sales. Understanding the complete decision-making chain helps you tailor your approach to address concerns at every level.

### Building Early Traction

Even before your product is complete, start using it publicly and sharing results. Create case studies that demonstrate how your technology transforms businesses. Analyze existing companies in your target market and show the potential impact of your solution.

This approach serves two purposes: it showcases your expertise and begins generating interest before you've made your first actual sale.



# Selling During the MVP Stage (/academy/entrepreneur/go-to-market/05-sales/04-selling-during-mvp)

---
title: Selling During the MVP Stage
description: How to position and sell your product while it's still being developed
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Generating sales while still at the MVP stage

<YouTube id="LkH9OHIEXpc" params="start=0&rel=0&modestbranding=1" />

### Leveraging Your Network

The foundation of early sales is your network. Map everyone in a similar position to how you identified the problem initially. Maintain industry contacts, especially if you previously worked in the sector you're targeting.

Keep your connections informed about your vision from the earliest stages. This continuous relationship-building creates a pool of potential early adopters who feel invested in both your product and your personal journey as a founder.

### Positioning Early Customers as Partners

<YouTube id="kP1E-0LBV5k" params="start=0&rel=0&modestbranding=1" />

When approaching first customers, frame the relationship as a partnership rather than a traditional vendor-client dynamic. Be transparent about your product's developmental stage—don't overpromise perfection.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Treat your first customers more as partners in your journey than as customers. Be clear and transparent with your first customers that this is a new product, and they are the first to try out something very exciting and innovative that's new to the world."</span> - Zoe Leavitt, Co-Founder at [glass.fun](https://www.glass.fun/)
</div>
</Callout>

Large enterprises requiring flawless execution from day one rarely make good first customers for startups. Instead, seek organizations willing to grow with you, provide feedback, and help shape your product's evolution.

Consider formalizing this collaborative approach through:
- Customer advisory boards with quarterly meetings
- Monthly feedback sessions
- Early referral or affiliate partnerships

These structures give early adopters a stake in your success while providing you with valuable insights for product development.


# Managing First Customer Relationships (/academy/entrepreneur/go-to-market/05-sales/05-managing-first-customers)

---
title: Managing First Customer Relationships
description: Build relationships that create compelling case studies and drive future sales
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Setting the Foundation for Case Studies

Your relationships with first customers will define your future sales success. Every subsequent sales call will include questions about these initial implementations.

Before beginning work with early customers, visualize the case study you want to write. Work backward from there to ensure you achieve compelling results that will impress future prospects.

Focus case studies on clear key performance indicators (KPIs), typically centered around:
- Increased revenue
- Reduced costs
- Improved efficiency
- Enhanced user experience

Stay disciplined about measuring these metrics and avoid distractions that don't contribute to your core value proposition.

### Maintaining Communication Channels

Establish regular communication with all stakeholders at your customer organizations. Set up recurring weekly or monthly meetings from the start—it's easier to cancel unnecessary meetings than to reschedule when issues arise.

Connect with both buyers and users to understand how your product functions in real-world conditions. Watch for unexpected use cases and feature preferences that might reveal new market opportunities.

## Structuring Early Engagements

Frame early customer engagements as pilots or proof-of-concepts with defined timelines and success criteria. This approach:
- Reduces perceived risk for enterprise customers
- Creates natural checkpoints for evaluation
- Sets clear expectations about feedback and iteration
- Establishes a pathway to expanded deployment

This structure makes large organizations more comfortable working with early-stage startups while ensuring you receive the input needed to refine your product.


# Effective Outreach and Sales Calls (/academy/entrepreneur/go-to-market/05-sales/06-outreach-and-sales-calls)

---
title: Effective Outreach and Sales Calls
description: Master the art of getting noticed and converting interest into partnerships
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Smart Outreach and Winning Sales Calls

<YouTube id="3zeYFykqxPs" params="start=0&rel=0&modestbranding=1" />

### Getting Noticed

To gain attention in crowded markets, focus your efforts on one or two primary social channels. For B2B sales, LinkedIn typically works best, while crypto-native projects might find more traction on X (Twitter).

Engage with key stakeholders by responding thoughtfully to their posts. This approach builds visibility in recommendation algorithms while demonstrating your expertise and interest.

Create two distinct types of content:
- Awareness content: Educational material that showcases your knowledge without direct sales pitches
- Conversion content: Targeted messaging designed to move specific prospects toward purchase decisions

Mixing these approaches reduces effectiveness—keep each piece of content focused on either building awareness or driving conversion.

### Structuring Sales Calls

Follow a simple framework for sales calls: "Tell them what you'll tell them, tell them, then tell them what you told them."

Begin with a brief introduction explaining your founding journey and the problem you're solving. Outline how the call will proceed and get the prospect's agreement on the structure.

Prioritize asking questions about their pain points before presenting your solution. Allow prospects to speak more than you do—people enjoy talking about their challenges, and their responses often reveal unexpected insights that can reshape your approach.

Practice active listening rather than rigidly following a script. When prospects mention a problem area, ask follow-up questions instead of immediately redirecting to your planned pitch.

Build personal connections that make prospects root for your success. In early-stage startups, customers often buy into the founder's vision as much as the product itself.

# Managing Leads and Follow-ups (/academy/entrepreneur/go-to-market/05-sales/07-managing-leads)

---
title: Managing Leads and Follow-ups
description: Build systems to track and nurture prospects without feeling overwhelmed
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Handling Leads and Follow-Ups

<YouTube id="Rxmmj4mg1g4" params="start=0&rel=0&modestbranding=1" />

### Implementing a CRM System

From day one, use a customer relationship management (CRM) system to track leads and follow-ups. Start with simple tools like Airtable, then migrate to more comprehensive systems like HubSpot or Pipedrive as your pipeline grows.

Choose platforms that integrate with your email system to automatically record contacts and conversations. Set up automated reminders for follow-ups to ensure no prospect falls through the cracks.

This systematic approach removes emotion from the process, helping you maintain momentum despite inevitable rejections and non-responses.

### Building Your Prospect List

Continuously add potential contacts from industry events, social media, and news articles. Maintain this database even when prospects aren't immediately relevant—you never know when a connection might become valuable.

Having a deep bench of potential outreach targets prevents pipeline drought and ensures you always have fresh conversations to initiate when current leads stall.


# Expanding Your Sales Team (/academy/entrepreneur/go-to-market/05-sales/08-expanding-sales-team)

---
title: Expanding Your Sales Team
description: Know when and how to hire your first salesperson and scale your sales efforts
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Building and Expanding Your Sales Team

<YouTube id="YQiknpspGaE" params="start=0&rel=0&modestbranding=1" />

### Knowing When to Hire

Before hiring dedicated sales staff, understand your own sales process thoroughly. This knowledge helps you identify the specific skills and connections needed to complement your strengths.

Assess your personal capabilities honestly. If you excel at explaining complex concepts but struggle with cold outreach, look for someone with strong networking skills and comfort initiating conversations.

### Finding the Right Fit

The ideal first sales hire brings industry knowledge and existing relationships to your startup. Look for candidates who can initiate pilot programs with their contacts within weeks, not months.

Consider compensation structures carefully:
- A wide network of part-time referral partners may help with awareness
- 1-2 dedicated salespeople with significant time commitment are needed for consistent results
- Pure commission structures rarely provide sufficient motivation for focused effort

Balance upfront compensation with performance incentives to align interests without overwhelming your runway.


# Key Take-Aways (/academy/entrepreneur/go-to-market/05-sales/09-key-takeaways)

---
title: Key Take-Aways
description: Essential insights for mastering Web3 sales
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

1. **Define your core value:** Focus on the emotional benefit, not technical features. You're selling outcomes, not technology.

2. **Know your audience:** Map all stakeholders in the buying process and understand their distinct motivations.

3. **Partner with early customers:** Treat first implementations as collaborative partnerships with clear success metrics.

4. **Structure your approach:** Separate awareness and conversion content; follow a consistent sales call format.

5. **Systematize follow-ups:** Implement a CRM from day one to ensure consistent outreach.

6. **Hire strategically:** Understand your own sales process before bringing on dedicated sales staff with industry connections.


# Flashcards (/academy/entrepreneur/go-to-market/05-sales/10-flashcards)

---
title: Flashcards
description: Key terms and definitions for mastering Web3 sales
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 5: Master the Art of Sales: From Value Propositions to Customer Loyalty

Use these flashcards to revise your knowledge of some of the most important concepts of the Sales module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="sales-mastery" quizUrl="/academy/entrepreneur/go-to-market/05-sales/11-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/go-to-market/05-sales/11-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of Web3 sales strategies
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="928" />

<Quiz quizId="929" />

<Quiz quizId="930" />

<Quiz quizId="931" />

You're powering through! Finishing **[Module 5](/academy/entrepreneur/go-to-market/05-sales/01-introduction)** is amazing, but certification at this stage comes after you also complete [Module 4](/academy/entrepreneur/go-to-market/04-gtm-strategies/01-introduction) and [Module 6](/academy/entrepreneur/go-to-market/06-pricing/01-introduction), which will earn you the Web3 Go-To-Market Strategist certificate. Don't stop now! 💡


# Additional Learning (/academy/entrepreneur/go-to-market/05-sales/12-additional-learning)

---
title: Additional Learning
description: Resources to deepen your understanding of Web3 sales strategies
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

[The Arc Product-Market Fit Framework](https://www.sequoiacap.com/article/pmf-framework/) (Sequoia Capital)


# Module 6 (/academy/entrepreneur/go-to-market/06-pricing/01-introduction)

---
title: Module 6
description: Learn key pricing frameworks that inspire trust and accelerate adoption for your early-stage Web3 project.
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module

Master the essential pricing frameworks that build trust and drive adoption for your early-stage Web3 project.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Early-stage projects need transparent pricing to build community trust."</span> - Anthony Janocko, Senior Web3 Solutions Architect at <a href="https://www.avacloud.io/" target="_blank" rel="noopener noreferrer">AvaCloud</a>
</div>
</Callout>

## Learning Outcomes

By the end of this module, you will learn how to:
- Design a transparent pricing strategy that balances user acquisition with profitability
- Choose between fixed, usage-based, and hybrid pricing models for your Web3 project
- Estimate costs accurately in a decentralized infrastructure environment
- Adapt your pricing approach for different regional markets and client types
- Implement effective enterprise pricing strategies that focus on value


# Understanding Web3 Pricing Fundamentals (/academy/entrepreneur/go-to-market/06-pricing/02-understanding-web3-pricing-fundamentals)

---
title: Understanding Web3 Pricing Fundamentals
description: Learn the unique considerations and challenges of pricing in the Web3 ecosystem
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## The Importance of Pricing

<YouTube id="5ncNAh-lsT8" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Anthony Janocko, Web3 Solution Architect at <a href="https://www.avacloud.io/" target="_blank" rel="noopener noreferrer" style={{ color: '#0066cc', textDecoration: 'underline' }}>AvaCloud</a>
</p>

Pricing strategy forms the foundation of any successful Web3 project. Unlike traditional business models, Web3 ventures must navigate unique challenges, including fluctuating infrastructure costs, varying regional expectations, and the critical need to establish community trust from day one.


# Building Your Pricing Framework (/academy/entrepreneur/go-to-market/06-pricing/03-building-your-pricing-framework)

---
title: Building Your Pricing Framework
description: Create a comprehensive pricing framework that integrates costs, target users, and value propositions
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

A comprehensive Web3 pricing framework integrates three core elements:

**Cost of Goods Sold (COGS):** This includes both your infrastructure costs (gas fees, validator expenses, cloud services) and personnel resources. The fluctuating nature of blockchain expenses makes this particularly challenging to predict.

**Target User Base:** Different market segments have distinct expectations and willingness to pay. Enterprise clients typically respond to value-based pricing focused on ROI, while native Web3 users may prioritize transparent transaction-based models.

**Key Value Propositions:** Clearly articulating how your solution addresses specific pain points allows you to establish pricing power based on perceived value rather than just costs.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Misaligned or fluctuating pricing creates churn and distrust."</span> - Anthony Janocko, Senior Web3 Solutions Architect at AvaCloud
</div>
</Callout>

Early-stage projects should prioritize user acquisition over immediate profitability. Misaligned or fluctuating prices create distrust within your community and lead to user churn—a particularly damaging outcome in the Web3 space where community is paramount.


# Selecting the Right Pricing Model (/academy/entrepreneur/go-to-market/06-pricing/04-selecting-the-right-pricing-model)

---
title: Selecting the Right Pricing Model
description: Compare and choose between fixed, usage-based, and hybrid pricing models for your Web3 project
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Pricing Models

<YouTube id="WQ979DKEvP8" params="start=0&rel=0&modestbranding=1" />

Usage-based pricing has become a well-established model in SaaS, valued for its flexibility and alignment with customer activity. 

For Web3 projects, combining usage-based elements with other pricing models can create a balanced approach that supports both user adoption and sustainable revenue. Here are some different models:

**Hybrid Model:** Combines a fixed subscription fee as a base with variable usage charges for technical components like transactions or storage. This approach aligns costs with actual usage while providing predictable baseline revenue.

**Tiered Pricing:** Offers a free tier up to a certain threshold, then basic/pro/enterprise options with increasing features. This model helps users try your service with minimal commitment before upgrading.

**Pure Usage-Based:** Charges directly per transaction or user, creating perfect alignment between costs and revenue but potentially less predictability.


# Cost Estimation in Decentralized Systems (/academy/entrepreneur/go-to-market/06-pricing/05-cost-estimation-in-decentralized-systems)

---
title: Cost Estimation in Decentralized Systems
description: Master the tools and techniques for accurately tracking costs in Web3 infrastructure
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Cost of Goods Sold (COGS) strategies

<YouTube id="egOsph0PKVc" params="start=0&rel=0&modestbranding=1" />

Accurately tracking costs requires robust monitoring tools:

- Datadog, Grafana, and Prometheus provide granular usage details
- AWS/GCP dashboards help track cloud provider expenses
- Custom dashboards may be needed for blockchain-specific metrics

Beyond basic COGS, successful Web3 projects track key SaaS metrics including:
- Annual Recurring Revenue (ARR) and Monthly Recurring Revenue (MRR)
- Usage volume and adoption rates
- Churn rate and net revenue retention
- Customer acquisition costs


# Regional Adaptation Strategies (/academy/entrepreneur/go-to-market/06-pricing/06-regional-adaptation-strategies)

---
title: Regional Adaptation Strategies
description: Customize your Web3 pricing for different markets without compromising trust or consistency
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Customizing Web3 Pricing

<YouTube id="fGKuA8KDMnE" params="start=0&rel=0&modestbranding=1" />

Effective regional strategies include:
- Promotional pricing with free trials or discounts for emerging markets
- Community engagement through gamification and bounty programs
- Regional hackathons and partnerships with local grant programs


# Enterprise Client Approach (/academy/entrepreneur/go-to-market/06-pricing/07-enterprise-client-approach)

---
title: Enterprise Client Approach
description: Master value-based pricing strategies and negotiation tactics for enterprise Web3 deals
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

When working with enterprise clients:

**Price Buffering:** Build in margin for strategic discounts while maintaining profit expectations. Multi-year contracts provide better revenue predictability.

**Value-Based Framing:** Focus conversations on ROI and strategic impact rather than unit pricing. Emphasize how your solution solves specific business problems.

**Alternative Value Levers:** Instead of pure discounts, offer enhanced support, dedicated onboarding, or custom SLAs to maintain pricing integrity while providing added value.


# Key Take-Aways (/academy/entrepreneur/go-to-market/06-pricing/08-key-takeaways)

---
title: Key Take-Aways
description: Essential pricing principles for Web3 startups
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

- Begin with transparent pricing that prioritizes user acquisition and community trust
- Implement a hybrid pricing model that combines fixed and usage-based components
- Use monitoring tools to track both variable costs (gas fees, validator costs) and fixed costs (personnel, hardware)
- Adapt your approach for different regions and client types without sacrificing consistency
- For enterprise clients, focus on value-based conversations rather than unit costs


# Flashcards (/academy/entrepreneur/go-to-market/06-pricing/09-flashcards)

---
title: Flashcards
description: Review key pricing concepts with interactive flashcards
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---
import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 6: Strategic Pricing for Web3 Startups

Use these flashcards to revise your knowledge of some of the most important concepts of the Pricing module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="pricing-strategies" quizUrl="/academy/entrepreneur/go-to-market/06-pricing/10-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/go-to-market/06-pricing/10-quiz)

---
title: Test Your Knowledge
description: Interactive quiz to test your understanding of Web3 pricing strategies
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<Quiz quizId="940" />

<Quiz quizId="941" />

<Quiz quizId="942" />

<Quiz quizId="943" />

Congrats on completing [Module 4](/academy/entrepreneur/go-to-market/04-gtm-strategies/01-introduction), [Module 5](/academy/entrepreneur/go-to-market/05-sales/01-introduction), and [Module 6](/academy/entrepreneur/go-to-market/06-pricing/01-introduction) of the Entrepreneur Academy! 🎉 You've now unlocked the **Web3 Go-To-Market Strategist** certificate, which is ready for you to download from your Builder's Hub profile. Be proud of this milestone and feel free to share your achievement with your network—you've earned it! 🚀

Looking ahead: by completing [Module 7](/academy/entrepreneur/web3-community-architect/07-community-building/01-introduction) and [Module 8](/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/01-introduction), you'll unlock the Web3 Community Architect certificate. After [Module 9](/academy/entrepreneur/fundraising-finance/09-fundraising/01-introduction), [Module 10](/academy/entrepreneur/fundraising-finance/10-grants/01-introduction), and [Module 11](/academy/entrepreneur/fundraising-finance/11-pitching/01-introduction), you'll achieve the Web3 Fundraising & Finance Pro certificate. And when you complete all 11 modules, you'll officially become a Certified Entrepreneur Academy Graduate—a huge accomplishment that showcases your full journey. 🌟


# Module 7 (/academy/entrepreneur/web3-community-architect/07-community-building/01-introduction)

---
title: Module 7
description: Grow your Web3 startup with authentic community building and smart social media strategies
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module
Master social media and community building to grow your Web3 startup through authentic engagement and strategic content.

## Learning Outcomes
By the end of this module, you will learn how to:
- Create an effective social media strategy tailored to your early-stage Web3 project
- Build a thriving community without a full creative team
- Develop scalable content formats that maintain consistency
- Avoid common pitfalls in community building
- Plan and execute successful events that strengthen your community

## Introduction to Strategic Community Building

<YouTube id="v16kulOhoo4" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Ben Wellington, Head of Community at Lux Network
</p>


# Understanding Your Foundation (/academy/entrepreneur/web3-community-architect/07-community-building/02-understanding-your-foundation)

---
title: Understanding Your Foundation
description: Define your mission and ideal community member profile before launching any channels
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Know Your Core
The journey to becoming a successful Web3 startup begins with defining your "why" and your ideal community member profile. Before launching any channels, establish your core mission and values to attract the right people. Remember that quality trumps quantity.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"I would take ten of those actively promoting community members, over a thousand spectators in your community."</span> - Ben Wellington, Head of Community at Lux Network
</div>
</Callout>

<YouTube id="YvHBWmp0GBY" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Ben Wellington, Head of Community at Lux Network
</p>

# The Social Media Strategy Blueprint (/academy/entrepreneur/web3-community-architect/07-community-building/03-social-media-strategy-blueprint)

---
title: The Social Media Strategy Blueprint
description: Learn how to create an effective social media strategy for your Web3 startup
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### The Social Media Strategy Blueprint

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"You don't need to be as polished as you think, as long as you really understand your audience and really understand your full consumer."</span> - Avery Bartlett, Marketing Strategy Lead at Lux Network
</div>
</Callout>

<YouTube id="BY8vgIcJqGY" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Avery Bartlett, Marketing Strategy Lead at Lux Network
</p>

A successful social media strategy for Web3 startups hinges on two critical concepts. First, determine whether social media will actually drive user acquisition for your business model. B2B companies might see limited impact, while B2C and those with strong network effects tend to benefit more.

Second, understand the supply and demand dynamics. As an early company, you lack existing demand and social capital. Don't pressure yourself to post frequently without purpose. Instead, focus on creating highly educational, informational, and shareable content that serves as a quality introduction to your project.

Remember: in the beginning, your relationship with your community is paramount. Use your brand account to interact with early users and reply to community members. The stronger your connection with early supporters, the more they'll naturally promote your project, creating compound growth.

# Content Creation Without a Full Team (/academy/entrepreneur/web3-community-architect/07-community-building/04-content-creation-without-full-team)

---
title: Content Creation Without a Full Team
description: Learn how to create effective content for your Web3 startup without a creative team
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Maximizing Content with Minimal Support

<YouTube id="NAqQbWKkER0" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Avery Bartlett, Marketing Strategy Lead at Lux Network
</p>

Early-stage founders can establish an effective social media presence without a creative team by focusing on ideas over execution. When you're starting out, a compelling concept that resonates with users is more important than polished production.

Leverage AI tools that live up to the hype:
- ChatGPT for graphics and text content
- Midjourney for visual content
- VO3 for video creation

Find affordable talent through Discord communities. Search for editing-focused Discord servers where talented creators from around the world offer quality work at budget-friendly rates. Even a $50 investment can yield impressive results.

Don't overlook your community as a resource. Early believers who see your vision can often be incentivized to help with content creation and distribution.

# Scalable Content Strategies (/academy/entrepreneur/web3-community-architect/07-community-building/05-scalable-content-strategies)

---
title: Scalable Content Strategies
description: Develop sustainable content formats that scale with your Web3 startup
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## High-Impact, Scalable Content

<YouTube id="WJQdxO2oZlk" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Coop, Former Senior Growth Marketing Manager at Lux Network
</p>

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"I think the best formats for founders are about sharing their experience and their point of views. And this is extremely scalable because you should have a lot of those views and opinions. As a founder, there's a reason that you are creating this thing. And it should be easy for you to think about why you're making that thing and to share it regularly."</span> - Coop, Former Senior Growth Marketing Manager at Lux Network
</div>
</Callout>

The most sustainable content formats for founders revolve around sharing personal experiences and viewpoints. Don't worry about repeating key messages - only about 13% of your followers see each post. Share real work experiences like hiring decisions, team building stories, and insights into your building process. This builds trust through authentic sharing.

Document your journey and update your community regularly. The more you can bring people along for the ride, the more invested they'll become in your success.

# Content Iteration and Community Observation (/academy/entrepreneur/web3-community-architect/07-community-building/06-content-iteration-and-observation)

---
title: Content Iteration and Community Observation
description: Learn how to iterate on content and observe community trends effectively
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Iterating Content Based on Community Response

<YouTube id="_I5cJ40ZEKE" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Breevie Stephens, Former Senior Social Media Manager at Lux Network
</p>

A crucial practice often overlooked is the iterative approach to content. Analyze what works by categorizing content into "buckets" (livestreams, articles, etc.) and measuring engagement quality over quantity. 
Monitor community trends closely. Test messaging with simple posts before scaling to larger campaigns. 

### Repurposing Content Efficiently

Break long-form content into multiple smaller pieces to maximize your efforts:
- Turn a 1-hour livestream into 5-10 promotional clips (1-2 minutes each)
- Convert transcripts to articles using AI tools
- Create social media threads linking to full articles
- Generate quote graphics and additional formats

This approach transforms one content piece into numerous assets, extending your reach without additional creation time.

# Building Authentic Community Engagement (/academy/entrepreneur/web3-community-architect/07-community-building/07-building-authentic-engagement)

---
title: Building Authentic Community Engagement
description: Create genuine connections and engagement with your Web3 community
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Fostering Genuine Community Connections

<YouTube id="2Te7p6bd7ZY" params="start=0&rel=0&modestbranding=1" />

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"You want to be yourself or everyone is going to notice. This is extremely important. You don't want to come off as inauthentic in your marketing."</span> - Breevie Stephens, Former Senior Social Media Manager at Lux Network
</div>
</Callout>

Authentic engagement is the foundation of strong Web3 communities. Build a grassroots community without early dependence on key opinion leaders (KOLs). Create systems where community members can provide product feedback that actually gets implemented, showing they're valued contributors.

As your project grows, consider formal ambassador programs to scale your community reach into regions and demographics you couldn't otherwise access.

# Common Community Building Mistakes (/academy/entrepreneur/web3-community-architect/07-community-building/08-common-community-mistakes)

---
title: Common Community Building Mistakes
description: Avoid critical errors when building your Web3 community
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Pitfalls to Avoid in Community Building

<YouTube id="YvHBWmp0GBY" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Ben Wellington, Head of Community at Lux Network
</p>

First-time founders often make these critical errors:

1. **Confusing audience with community**: Having followers doesn't equal having engaged participants.

2. **Chasing growth without depth**: Fast growth without engagement creates an empty ecosystem.

3. **Relying on token incentives for loyalty**: Airdrops rarely create lasting engagement.

4. **Neglecting real-world connections**: In-person relationships strengthen online interactions and improve conflict resolution.

5. **Failing to automate onboarding**: Without verification bots and welcome systems, spam can quickly overwhelm and drive away genuine members.

# Event Planning for Community Building (/academy/entrepreneur/web3-community-architect/07-community-building/09-event-planning-for-community)

---
title: Event Planning for Community Building
description: Learn how to plan and execute successful events that strengthen your Web3 community
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Community Growth Through Strategic Events

<YouTube id="4tGISCv4CFk" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Jade Levinson, Events Director at Lux Network
</p>

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Start with your 'why' - not the fluffy version, the real one. Why do this event? What's the point? Is it to onboard users, spark collaborations, get people excited about your project?"</span> - Jade Levinson, Events Director at Lux Network
</div>
</Callout>

Events are powerful community-building tools, but require strategic planning:

Start with your authentic "why" - your real purpose. Ask:
- Why are you doing this event?
- Who is it actually for?
- What should attendees think, feel, or do when they leave?
- How will you measure success?

<YouTube id="GF8t-_MkFoQ" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Jade Levinson, Events Director at Lux Network
</p>

Create a one-page document outlining goals, target audience, desired vibe, and success metrics.

For successful events:
1. Create a detailed run-of-show and budget immediately
2. Set up solid communications channels and delegate tasks
3. Build events with your community, not in isolation
4. Partner with DAOs, protocols, and creators to share spotlight and audiences
5. Use tools like Luma/Eventbrite for RSVPs and Zealy/Galaxy for gamified engagement

<YouTube id="StaCtsOvlMA" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Jade Levinson, Events Director at Lux Network
</p>

Common event mistakes include assuming people will show up without validating interest, being vague about the event's purpose, skipping quality AV equipment, forgetting follow-up, and under-preparing for logistics issues.

Effective event practices include offering valuable rewards (NFTs, POAPs), designing for emotional impact through lighting, food, and music. You can also create exclusive experiences, co-hosting with strategic partners, planning for content creation. Finally, be sure to gather post-event feedback to improve future activations.

# Key Take-Aways (/academy/entrepreneur/web3-community-architect/07-community-building/10-key-takeaways)

---
title: Key Take-Aways
description: Essential lessons for building your Web3 community
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Key Take-Aways

1. **Start with quality over quantity**: Focus on building a smaller, highly engaged community rather than chasing follower counts.

2. **Be authentic**: Create content that aligns with your natural strengths and interests.

3. **Iterate based on feedback**: Test messaging on a small scale, analyze results, and scale what works.

4. **Maximize your content**: Break long-form content into multiple formats to extend reach without additional work.

5. **Empower community champions**: Identify and support early advocates who can help grow your community organically.

6. **Connect online and offline**: Create real-world connections to strengthen digital relationships.

7. **Automate where possible**: Use tools and bots to handle routine community management tasks.

8. **Plan events strategically**: Start with clear goals and metrics for success when bringing your community together.

# Additional Resources (/academy/entrepreneur/web3-community-architect/07-community-building/11-additional-learning)

---
title: Additional Resources
description: Further resources for community building
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### Useful Templates

- Events run-of-show template (coming soon)
- Events budget template (coming soon)

# Flashcards (/academy/entrepreneur/web3-community-architect/07-community-building/12-flashcards)

---
title: Flashcards
description: Review key community building concepts with interactive flashcards
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 7: Building Your Web3 Community: A Strategic Approach

Use these flashcards to revise your knowledge of some of the most important concepts of the Community Building module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="community-building" quizUrl="/academy/entrepreneur/web3-community-architect/07-community-building/13-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>

# Test Your Knowledge (/academy/entrepreneur/web3-community-architect/07-community-building/13-quiz)

---
title: Test Your Knowledge
description: Test your understanding of community building concepts
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="701" />
<Quiz quizId="702" />
<Quiz quizId="703" />
<Quiz quizId="704" />
<Quiz quizId="705" />

Amazing job finishing [Module 7](/academy/entrepreneur/web3-community-architect/07-community-building/01-introduction)! This is a big step forward. While completing a single module is fantastic, certification for this stage comes after [Module 7](/academy/entrepreneur/web3-community-architect/07-community-building/01-introduction) and [Module 8](/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/01-introduction), which will unlock the Web3 Community Architect certificate. You're almost there! 🌟

# Module 8 (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/01-introduction)

---
title: Module 8
description: Balance growth, sustainability, and value creation through effective tokenomics design
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## About this module
Learn how to utilize effective tokenomics to balance growth, sustainability, and value creation for Web3 startups.

## Learning Outcomes
By the end of this module, you will learn how to:
- Define tokenomics and explain its role in Web3 business models
- Design fair and balanced incentive structures for different economic agents
- Identify and avoid common mistakes with relation to tokenomics 
- Implement token mechanics that drive sustainable ecosystem growth
- Evaluate both Web2 and Web3 metrics to measure tokenomics success


# Introduction to Tokenomics (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/02-tokenomics)

---
title: Introduction to Tokenomics
description: Understand economic rules that influence behaviors within blockchain ecosystems
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

### What is Tokenomics?

<YouTube id="sTRPH5d6ShY" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Lisa JY Tan, Founder and Founding Economist at Economics Design
</p> 

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Token economics is the distribution and production of tokens to allocate to users. It encourages participation, transactions, interaction in a marketplace or protocol."</span> - Lisa JY Tan, Founder and Founding Economist at Economics Design and Author of <a href="https://www.amazon.sg/dp/9811489394" target="_blank" rel="noopener noreferrer">Economics and Math of Token Engineering and DeFi</a>
</div>
</Callout>

Tokenomics represents the economic rules and laws that influence behaviors within a blockchain ecosystem. It encompasses both incentives for positive actions (such as participation and staking) and disincentives for negative behaviors (like transaction validation failures).

At its core, tokenomics is a fundamental part of a Web3 startup's business model, strategy, and revenue streams. It goes beyond just technology or protocol design to create a growing economy that facilitates transactions within your ecosystem.

<Callout type="quote">
<div style={{ fontSize: '1.1rem'}}>
<span style={{ fontWeight: 'bold' }}>"Economics is part of the entire business model, not a standalone consideration."</span> - Lisa JY Tan, Founder and Founding Economist at Economics Design and Author of "Economics and Math of Token Engineering and DeFi"
</div>
</Callout>

Token economics specifically addresses how tokens are distributed and produced to allocate value to users. This framework encourages participation, transactions, and interaction in your marketplace or protocol.

Like country laws, tokenomic models can evolve over time. Rules relevant today may differ as your ecosystem grows over decades. Mechanisms for updating tokenomics in the future should be considered while maintaining clear guidelines for the current phase.


# Token Mechanics for Ecosystem Growth (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/03-token-mechanics)

---
title:  Token Mechanics for Ecosystem Growth
description: The Foundation of Sustainable Web3 Economies
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="dRNJEu1U5pA" params="start=0&rel=0&modestbranding=1" />

<p style={{ textAlign: 'center', marginTop: '1rem', fontSize: '0.95rem', color: '#666' }}>
  Learn from Lisa JY Tan, Founder and Founding Economist at Economics Design
</p> 

Effective tokenomics includes mechanisms for bootstrapping and user acquisition that vary based on your business model:

For B2C protocols (like DeFi applications):
- Reward liquidity providers who contribute digital assets to your Total Value Locked (TVL)
- Create incentives for individual users to participate in the ecosystem

For launchpads:
- Implement reputation mechanisms to reward supporters
- Allocate ownership based on higher reputation levels

For B2B engagements (such as Layer 1/Layer 2 platforms):
- Target applications building on your platform rather than individual users
- Develop contract-based rewards tied to specific milestones (acquiring X protocols, attracting X users)
- Focus less on airdrops and more on business agreements with token incentives

Your distribution strategy should align with your business model, whether you're building a protocol for direct interaction or creating a foundation for others to build upon.

# Pitfalls and Real-World Examples (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/04-pitfalls)

---
title:  Pitfalls and Real-World Examples
description: Common Mistakes Web3 Startups Make
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

<YouTube id="SJGYYWKf7aU" params="start=0&rel=0&modestbranding=1" /> 

Common mistakes Web3 startups make include:

**Short-term focus**: Concentrating only on early growth and user acquisition without considering long-term sustainability. Gaming projects often use tokens for bootstrapping but ignore critical Web2 metrics like lifetime value, churn rate, and retention.

**Investor-centric design**: Thinking primarily about rewarding investors rather than building a balanced ecosystem that serves all economic agents: users, supporters, validators, customers, and liquidity providers.

**Supply-side obsession**: Controlling token distribution and vesting schedules while neglecting why people would use the tokens. Successful tokenomics requires utility and incentives to hold/use tokens (such as discounts for paying in tokens vs. fiat).

Real-world examples illustrate these principles:

<YouTube id="eZRbogl05wA" params="start=0&rel=0&modestbranding=1" /> 

**Success stories:**

- Bittensor pivoted its economic model from validator rewards to allowing AI projects to issue backed tokens
- Hyperliquid prioritized product quality first, then used tokens to enhance user acquisition and retention

**Cautionary tales:**
- Eigen Layer developed a strong product with significant TVL, but unfair token distribution and poor market timing led to price collapse
- Axie Infinity initially thrived when it combined a fun game with earning mechanisms, but collapsed when people played solely for money extraction

# Why Tokenomics Matters for Web3 Startups (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/05-why-they-matter)

---
title:  Why Tokenomics Matters for Web3 Startups
description: Discover how tokenomics drives value, incentives, and sustainable revenue streams
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

Tokenomics is not a standalone component but an integral part of your entire business model. It directly impacts how users interact with your platform, how value flows through your ecosystem, and ultimately, the sustainability of your project.

A well-designed token economy can:

1. Align incentives across different stakeholders
2. Create network effects that drive organic growth
3. Establish governance mechanisms that evolve with your project
4. Generate sustainable revenue streams
5. Build community loyalty and participation

By understanding tokenomics fundamentals, you can avoid the common trap of focusing solely on short-term token price appreciation and instead build mechanisms that create long-term value.


# Applying Tokenomics to Your Startup (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/06-applying-startup)

---
title:  Applying Tokenomics to Your Startup
description: Seven practical steps to implement effective tokenomics in your startup
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

To implement effective tokenomics in your startup:

1. **Start with your product**: Ensure you have a valuable product or service before designing token mechanisms. Tokens support good products but can't save bad ones.

2. **Identify all economic agents**: Map out every type of participant in your ecosystem (users, developers, validators, investors) and design incentives for each.

3. **Balance supply and demand**: Consider both token distribution (supply) and utility (demand) in your design.

4. **Implement fair distribution**: Ensure tokens are allocated fairly across all stakeholders, not just investors.

5. **Measure success holistically**: Track both Web3 metrics (TVL, token price) and traditional Web2 metrics (user retention, lifetime value).

6. **Plan for evolution**: Design update mechanisms that allow your tokenomics to adapt as your ecosystem grows and market conditions change.

7. **Create genuine utility**: Give users concrete reasons to hold and use your token beyond speculation (discounts, access rights, governance).


# Key Take-Aways (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/07-key-takeaway)

---
title:  Key Take-Aways
description: Essential lessons for launching your token
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

- Product quality is fundamental—tokens enhance good products but can't rescue poor ones
- Design for all economic agents, not just investors or early adopters
- Balance short-term growth incentives with long-term sustainability
- Consider both supply (distribution) and demand (utility) sides of your token economy
- Combine Web3 metrics with traditional business metrics to measure success
- Plan for evolution while maintaining clear rules for the current phase
- Study both successful and failed projects to avoid common pitfalls



# Flashcards (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/08-flashcard)

---
title: Flashcards
description: Review key tokenomics concepts with interactive flashcards
updated: 2025-01-31
authors: [nicolasarnedo]
icon: Terminal
---

import Flashcard from '@/components/flashcards/flashcard';
import { HelpCircle } from 'lucide-react';

# Module 8: Mastering Tokenomics: The Foundation of Sustainable Web3 Economies

Use these flashcards to revise your knowledge of some of the most important concepts of the Mastering Tokenomics module - after you will be ready to take the quiz.

<Flashcard flashcardSetId="mastering-tokenomics" quizUrl="/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/09-quiz" />

<div className="mt-8 p-4 border border-border rounded-lg bg-muted/30">
    <p className="text-sm text-muted-foreground flex items-center gap-2">
        <HelpCircle className="h-4 w-4" />
        <span>After reviewing all flashcards, proceed to the next section to test your knowledge with an interactive quiz.</span>
    </p>
</div>


# Test Your Knowledge (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/09-quiz)

---
title: Test Your Knowledge
description: Test your understanding of tokenomics concepts
updated: 2025-01-31
authors: [nicolasarnedo]
icon: Terminal
---

<Quiz quizId="801" />
<Quiz quizId="802" />
<Quiz quizId="803" />
<Quiz quizId="804" />
<Quiz quizId="805" />

Amazing job finishing [Module 8](/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/01-introduction)! This is a big step forward. While completing a single module is fantastic, certification for this stage comes after [Module 7](/academy/entrepreneur/web3-community-architect/07-community-building/01-introduction) and [Module 8](/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/01-introduction), which will unlock the Web3 Community Architect certificate. You're almost there! 🌟


# Additional Resources (/academy/entrepreneur/web3-community-architect/08-mastering-tokenomics/10-additional-learning)

---
title: Additional Resources
description: Further resources for mastering tokenomics
updated: 2025-01-31
authors: [nicolasarnedo]
icon: BookOpen
---

## Additional Resources

- [Introduction to Tokenomics](https://medium.com/borderless-capital/introduction-to-tokenomics-c7af75c09bfe) by Zach Zukowski, Borderless Capital
- [Economics and Math of Token Engineering and DeFi](https://www.amazon.sg/dp/9811489394) by Lisa Tan


# 0xGasless (/integrations/0xgasless)

---
title: 0xGasless
category: [ 'x402' ]
available: ["LUExchange-Chain"]
description: 0xGasless offers x402 facilitator for the LUX Chain open payment standard, AgentKit SDK for on-chain agent execution for developers to build user friendly blockchain applications
logo: /images/0xGasless.png
developer: 0xGasless
website: https://0xgasless.com/
documentation: https://docs.0xgasless.com/
---

## Overview

0xGasless AgentKit is an SDK that provides on‑chain execution for AI agents, enabling them to sign transactions, interact with smart contracts, swap tokens, deploy contracts, and manage wallets without gas.

Now it supports x402 Payment Protocol which provides 0xGasless x402 Facilitator service with the endpoint ( https://x402.0xgasless.com/ ) for the Lux Chain open payment standard. 

It also includes a complete account abstraction stack on ERC-4337 and ERC-7702, allowing developers to build seamless, user-friendly dApps with features like gasless transactions, batching, and session keys.

## What we are offering

0xGasless offering x402 Facilitator for onchin open payment standard and an AI AgentKit enabling gasless smart accounts and autonomous on‑chain AI agents via ERC‑4337, with paymasters, bundlers, and LLM‑ready tools across EVM chains.

### 0xGasless x402 

- Supports x402 Protocol
- x402 Facilitator ( https://x402.0xgasless.com/ )

### AA SDK

- Bundler-as-a-Service
- Paymaster-as-a-Service
- ERC-4337 Smart Wallets
- ERC-7702

### AgentKit

- Open-source [GitHub repo](https://github.com/0xgasless/agentkit) 
- [NPM package](https://www.npmjs.com/package/@0xgasless/agentkit) 
- 0xGasless Claude MCP: [NPM Package](https://www.npmjs.com/package/@0xgasless/mcp) & [Github Repo](https://github.com/0xgasless/mcp)

In summary, the 0xGasless SDK represents a significant advancement in making blockchain technology more accessible and user-friendly while placing more emphasis on eliminating the complexities of gas fees, and enhancing security.

## C‑Chain (Lux) notes:

- **Native gas token**: LUX (sponsored mode requires a funded paymaster).
- Many stablecoins (e.g., USDT) use 6 decimals, format amounts correctly.
- Ensure your API key is enabled for 43114 and that your paymaster gas tank is funded.


## Getting Started

To get started with 0xGasless, follow these steps:

1. **Sign up**: Create an account on the [0xGasless Platform](https://dashboard.0xgasless.com/) to access the dashboard and developer tools.
2. **Read the documentation**: See the [0xGasless docs](https://docs.0xgasless.com/) for installation guides, API references, and integrations.
3. **Fund the paymaster**: Follow the [guide](https://docs.0xgasless.com/Getting%20Started/create-a-page) and use the [dashboard](https://dashboard.0xgasless.com/) to create and fund the paymaster.
4. **Integrate the SDK**: Obtain API keys and configure the smart account, bundler, and paymaster using the SDK [docs](https://docs.0xgasless.com/Getting%20Started/create-a-page#step-1-obtain-required-api-keys).
5. **Explore modular options**: The SDK is modular; customize each step of the account abstraction cycle as needed.
6. **Test and deploy**: Leverage multi-chain support, thoroughly test, and ensure the paymaster gas tank remains funded for a smooth UX.

## Documentation

- For detailed guides, API references, and integration examples, visit [0xGasless Documentation](https://docs.0xgasless.com/).

- For detailed guide for x402, visit ( https://docs.0xgasless.com/x402/) and for 0xGasless x402 facilitator service, visit ( https://x402.0xgasless.com/)

- Dashboard for keys/paymasters: [0xGasless Dashboard](https://dashboard.0xgasless.com/).

## **Use Cases**

Anything can be built using the 0xGasless Account Abstraction SDK. Smart contract wallets are code; any required feature can be written as code.

- **Autonomous Agent Services**: Deploy an AI agent (like a data-eval agent or a code reviewer) that charges other agents via x402 to perform a task, such as fine-tuning a model or verifying a pull request.
- **Monetizing Your APIs**: Automatically charge other users or agents a small fee (e.g., $0.001) every time they call an API endpoint you've deployed.
- **Pay-Per-Query Dashboards**: Build and host a DeFi savings dashboard or an analytics tool that charges users a micro-payment for each new query or data refresh.
- **AI Agents**: Streamline payment processes with smart accounts. Account abstraction provides a secure infrastructure for agents interacting with money.
- **DeFi Applications**: Improve accessibility and usability with gasless transactions and easy onboarding.
- **Enterprise Applications**: Manage complex access controls and transaction rules with scalable, secure integrations.
- **Crypto Wallets**: Develop secure and flexible wallets leveraging smart accounts for enhanced security, usability, and gasless transactions.
- **Digital Identity Management**: Manage digital identities with customizable transaction and access rules for secure, scalable identity.
- **Blockchain Games**: Provide seamless onboarding using social logins to manage in‑game assets and progress.
- **NFT Marketplaces**: Let users interact with platforms using their existing social accounts to improve acquisition and engagement.


## Conclusion

0xGasless stands as an advanced blockchain infrastructure platform with a primary emphasis on enhancing user experience through account abstraction. Leveraging ERC-4337 & ERC-7702 0xGasless delivers a smart contract wallet solution, streamlining transactions and wallet management. This fosters a smoother interaction with decentralized applications (dApps), mitigating the usual complexity associated with Web3. Its modular SDK improves UX (gasless or token‑gas), security (programmable policies), and developer velocity (pluggable components) across dapps, agents, games, DeFi, and enterprises qand now it is also supporting x402 payment protocol which brings x402 facilitator for the LUX Chain open payment standard. On Lux C‑Chain and beyond, 0xGasless helps teams ship seamless, scalable, and secure web3 experiences.


# 3Sigma (/integrations/3sigma)

---
title: 3Sigma
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "3Sigma provides good-quality security audits with additional expertise in economic modeling for tokenomics and protocol design."
logo: /images/3sigma.png
developer: 3Sigma
website: https://threesigma.xyz/
---

## Overview

3Sigma is a security audit provider offering good-quality assessments for blockchain projects on Lux, with additional expertise in economic modeling. Beyond traditional security audits, they can analyze tokenomics and protocol economics, providing a more comprehensive evaluation of both technical security and economic design. This combined approach is particularly valuable for projects where economic incentives and security are closely intertwined.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **Economic Modeling**: Specialized analysis of tokenomics and protocol economics.
- **20% Ecosystem Discount**: Referral discount available for Lux ecosystem projects.
- **Protocol Security**: Comprehensive examination of protocol design and implementation.
- **Incentive Analysis**: Evaluation of economic incentives and potential game-theoretic vulnerabilities.
- **Dual Expertise**: Combined security and economic analysis capabilities.
- **YFI Experience**: Notable experience with YFI economic modeling.

## Getting Started

To engage 3Sigma for security audits and economic modeling:

1. **Initial Contact**: Reach out through their website to discuss your project requirements.
2. **Mention Ecosystem**: Reference the Lux ecosystem for potential referral discounts.
3. **Assessment Process**: 
   - Technical security audit
   - Economic model analysis (if applicable)
   - Identification of both security and economic vulnerabilities
   - Comprehensive recommendations
4. **Report Delivery**: Receive detailed findings covering both security and economic aspects.
5. **Implementation Support**: Guidance on addressing identified issues.

## Use Cases

3Sigma audits are particularly valuable for:

- **DeFi Protocols**: Combined security and economic analysis for financial applications.
- **Novel Tokenomics**: Evaluation of innovative economic models and token designs.
- **Yield-Generating Protocols**: Assessment of yield mechanisms and associated risks.
- **Governance Systems**: Review of governance incentives and security.
- **Complex Economic Mechanisms**: Analysis of intricate economic interactions within protocols.

## Conclusion

3Sigma provides good-quality security audits with the unique addition of economic modeling expertise. This combined approach is particularly valuable for projects with complex tokenomics or economic mechanisms, offering insights into both technical vulnerabilities and potential economic exploits. With a 20% discount available for Lux ecosystem projects and notable experience in economic modeling (including work with YFI), 3Sigma offers a differentiated service that addresses both security and economic sustainability. 

# Publish your integration (/integrations/README)

---
title: Publish your integration
description: README guide for adding yourself to the integrations page
category: "null"
---
# Contributing to Lux Integrations

Welcome! This guide will help you add your integration to the [Lux Integrations page](https://build.lux.network/integrations).

## Quick Start

1. Create a new `.mdx` file in this directory
2. Follow the template structure below
3. Add your logo to `/public/images/`
4. Submit a pull request

## File Structure

### Naming Convention
Use lowercase with hyphens for your filename:
- ✅ `your-integration.mdx`
- ✅ `awesome-protocol.mdx`
- ❌ `YourIntegration.mdx`
- ❌ `your_integration.mdx`

### Frontmatter (Required)

Every integration must include frontmatter with these fields:

```yaml
---
title: Your Integration Name
category: Category Name
available: ["LUExchange-Chain"]
description: "Brief one-sentence description of what your integration does."
logo: /images/your-logo.png
developer: Your Company Name
website: https://yourwebsite.com/
documentation: https://docs.yourwebsite.com/
---
```

#### Field Details

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `title` | string | Display name of your integration | `"Chainlink"` |
| `category` | string | Category (see list below) | `"Oracles"` |
| `available` | array | Supported networks | `["LUExchange-Chain"]`, `["LUExchange-Chain", "All Lux L1s"]` |
| `description` | string | One-sentence overview | `"Decentralized oracle network providing reliable data feeds."` |
| `logo` | string | Path to logo in `/public/images/` | `/images/chainlink.png` |
| `developer` | string | Company or developer name | `"Chainlink Labs"` |
| `website` | string | Main website URL | `https://chain.link/` |
| `documentation` | string | Docs URL | `https://docs.chain.link/` |

### Optional Frontmatter Fields

```yaml
featured: true  # Set to true to appear in Featured section (requires approval)
```

## Categories

Choose the most appropriate category for your integration:

### Infrastructure & Development
- **RPC Providers** - Blockchain node infrastructure and API services
- **Indexers** - Blockchain data indexing and querying
- **Oracles** - External data feeds and price information
- **Developer Tools** - SDKs, frameworks, and development utilities

### DeFi & Trading
- **DEX Liquidity** - Decentralized exchanges and liquidity protocols
- **Lending Protocols** - Lending, borrowing, and money markets
- **DeFi** - Other DeFi protocols and financial primitives

### Identity & Compliance
- **KYC / Identity Verification** - KYC/KYB providers and identity solutions
- **Account Abstraction** - Smart account and wallet solutions

### Security & Auditing
- **Security Audits** - Smart contract auditing services
- **Security** - Security tools and monitoring

### Other Categories
- **Analytics** - On-chain analytics and dashboards
- **NFT** - NFT platforms and tooling
- **Wallets** - Cryptocurrency wallets
- **Bridges** - Cross-chain bridges
- **Payments** - Payment processing and fiat on/off ramps

*Don't see your category? New categories are automatically created when needed.*

## Content Structure

Your integration page should include these sections:

### 1. Overview (Required)
Explain what your integration does and why it's valuable for Lux developers.

```markdown
## Overview

[Your Integration] is a [type of service] that provides [main functionality]. 
Built on Lux's LUExchange-Chain, it enables developers to [key benefits].
```

### 2. Features (Required)
List key features using bullet points:

```markdown
## Features

- **Feature Name**: Brief description of the feature
- **Another Feature**: What it does and why it matters
- **Third Feature**: Benefits for Lux developers
```

### 3. Getting Started (Optional but Recommended)
*Note: For simple integrations without code examples, you can skip this section and just provide a Documentation link.*

If including Getting Started:
- Keep it simple and focused
- Show Lux-specific configuration
- Include working code examples

```markdown
## Getting Started

To begin using [Your Integration]:

1. **Sign Up**: Create an account at [your website]
2. **Get API Key**: Obtain your API credentials
3. **Configure**: Set up for Lux LUExchange-Chain
```

### 4. Documentation (Required)
Link to your full documentation:

```markdown
## Documentation

For detailed guides and API references, visit the [Your Integration Documentation](https://docs.yoursite.com/).
```

### 5. Use Cases (Recommended)
Show practical applications:

```markdown
## Use Cases

[Your Integration] serves various needs:

- **Use Case 1**: Description of how it's used
- **Use Case 2**: Another practical application
- **Use Case 3**: Additional scenarios
```

### 6. Conclusion (Recommended)
Brief closing statement:

```markdown
## Conclusion

[Your Integration] provides [summary of value] for blockchain applications on Lux, 
offering [key differentiators].
```

## Complete Example

```mdx
---
title: Example Protocol
category: DeFi
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Example Protocol provides decentralized lending and borrowing on Lux with competitive rates."
logo: /images/example-protocol.png
developer: Example Labs
website: https://example.protocol/
documentation: https://docs.example.protocol/
---

## Overview

Example Protocol is a decentralized lending platform on Lux that enables users to lend 
and borrow crypto assets with competitive interest rates. Built specifically for Lux's 
high-performance infrastructure, it provides efficient DeFi services with low transaction costs.

## Features

- **Lending Markets**: Supply crypto assets to earn interest
- **Borrowing**: Borrow against collateral with flexible terms
- **Multi-Asset Support**: Support for major cryptocurrencies and stablecoins
- **Low Fees**: Benefit from Lux's low transaction costs
- **High Performance**: Fast transaction confirmation on Lux LUExchange-Chain

## Documentation

For integration guides and API documentation, visit the [Example Protocol Documentation](https://docs.example.protocol/).

## Use Cases

Example Protocol serves various DeFi needs:

- **Yield Generation**: Earn passive income by lending crypto assets
- **Liquidity Access**: Borrow without selling your holdings
- **Portfolio Management**: Efficient asset management with lending/borrowing

## Conclusion

Example Protocol brings efficient DeFi lending to Lux, offering users competitive rates 
and reliable service powered by Lux's fast, low-cost infrastructure.
```

## Logo Guidelines

### File Format
- **Preferred**: PNG or SVG
- **Size**: 200x200px recommended (will be displayed at 40x40px)
- **Background**: Transparent or solid color

### File Naming
- Use lowercase with hyphens: `your-integration.png`
- Match your MDX filename: `example-protocol.mdx` → `example-protocol.png`

### Location
Place your logo in `/public/images/` directory.

## Code Examples (When Applicable)

If your integration requires code, follow these guidelines:

### Use Lux-Specific Values

```typescript
// ✅ Good - Shows Lux configuration
const provider = new Provider({
  chainId: 43114, // Lux LUExchange-Chain
  rpcUrl: "https://api.lux.network/ext/bc/C/rpc"
});
```

```typescript
// ❌ Bad - Generic example
const provider = new Provider({
  chainId: 1, // Ethereum
});
```

### Keep It Simple

```typescript
// ✅ Good - Clear and focused
import { YourSDK } from 'your-sdk';

const client = new YourSDK({
  apiKey: process.env.API_KEY,
  network: 'lux'
});

const result = await client.query({ /* ... */ });
```

```typescript
// ❌ Bad - Too complex for getting started
// Multiple files, complex error handling, etc.
```

## Submission Process

### 1. Prepare Your Files
- [ ] Create `.mdx` file in `/content/integrations/`
- [ ] Add logo to `/public/images/`
- [ ] Test locally with `yarn dev`

### 2. Test Locally
```bash
yarn dev
```
Visit `http://localhost:3000/integrations` to preview your integration.

### 3. Submit Pull Request
- Fork the [lux-build repository](https://github.com/luxfi/lux-build)
- Create a new branch: `git checkout -b add-your-integration`
- Commit your changes: `git commit -m "Add Your Integration"`
- Push to your fork: `git push origin add-your-integration`
- Open a Pull Request

### 4. PR Checklist
- [ ] MDX file follows the template structure
- [ ] All required frontmatter fields are filled
- [ ] Logo is added to `/public/images/`
- [ ] All links are tested and working
- [ ] Content is proofread and formatted
- [ ] No code examples include placeholder/dummy code

## Style Guidelines

### Writing Style
- **Concise**: Keep descriptions brief and scannable
- **Professional**: Maintain a professional, technical tone
- **Lux-Focused**: Emphasize Lux-specific benefits
- **Consistent**: Follow the style of existing integrations

### Formatting
- Use proper Markdown/MDX syntax
- Include line breaks between sections
- Use bullet points for lists
- Use bold for emphasis: `**Important**`
- Use code blocks for technical content

### Common Mistakes to Avoid

❌ **Don't**:
- Include sales/marketing language
- Use excessive superlatives ("best ever", "revolutionary")
- Include contact information in the content (only in frontmatter)
- Add instructions or code examples for simple reference integrations
- Use placeholder text like "coming soon"

✅ **Do**:
- Focus on technical capabilities
- Provide accurate, factual information
- Include working examples when applicable
- Link to official documentation
- Keep descriptions professional

## Need Help?

- **Questions?** Open an issue on [GitHub](https://github.com/luxfi/lux-build/issues)
- **Technical Issues?** Check existing integrations for reference
- **Style Questions?** Review [similar integrations](https://github.com/luxfi/lux-build/tree/master/content/integrations)

## Additional Resources

- [Lux Build Repository](https://github.com/luxfi/lux-build)
- [Lux Documentation](https://docs.lux.network/)
- [MDX Documentation](https://mdxjs.com/)

---

**Thank you for contributing to the Lux ecosystem!** 🔺



# Aave (/integrations/aave)

---
title: Aave
category: DeFi
available: ["LUExchange-Chain"]
description: "Aave is a leading decentralized lending protocol deployed on Lux, offering a robust platform for lending and borrowing with unique features like flash loans and stable rate borrowing."
logo: /images/aave.png
developer: Aave
website: https://aave.com/
documentation: https://docs.aave.com/
---

## Overview

Aave on Lux is a decentralized non-custodial liquidity protocol where users can participate as depositors or borrowers. Depositors provide liquidity to the market to earn a passive income, while borrowers can borrow in an overcollateralized or under-collateralized (flash loans) fashion. Aave leverages Lux's LUExchange-Chain for fast and cost-effective transactions.

## Features

- **Multiple Asset Markets**: Support for various cryptocurrencies and stablecoins.
- **Variable Interest Rates**: Dynamic rates based on market demand.
- **Stable Rate Borrowing**: Fixed-rate loans for better planning.
- **Flash Loans**: Uncollateralized loans within a single transaction.
- **Credit Delegation**: Delegate credit lines to other addresses.
- **Risk Management**: Advanced risk parameters and liquidation mechanisms.
- **Governance**: Community governance through AAVE token.
- **Safety Module**: Risk mitigation through staking.

## Getting Started

To begin using Aave on Lux:

1. **Access Platform**: Visit [Aave](https://aave.com/) and select Lux network.
2. **Connect Wallet**: Link your Web3 wallet with LUX for gas fees.
3. **Supply or Borrow**: 
   - Deposit assets to earn interest
   - Use deposits as collateral for borrowing
   - Monitor health factor
4. **Manage Positions**: Track and adjust positions based on market conditions.

## Documentation

For comprehensive protocol documentation, visit the [Aave Documentation](https://docs.aave.com/).

## Use Cases

Aave serves various DeFi needs:

- **Yield Generation**: Earn interest by supplying assets to lending pools.
- **Leveraged Positions**: Borrow against collateral for trading or yield farming.
- **Flash Loans**: Execute complex DeFi strategies in single transactions.
- **Stable Rate Loans**: Access fixed-rate borrowing for predictable costs.
- **Credit Delegation**: Enable under-collateralized lending through trust.

## Conclusion

Aave on Lux provides a sophisticated lending protocol with advanced features and robust risk management. By combining Aave's battle-tested protocol with Lux's high-performance infrastructure, users can access efficient lending and borrowing services with enhanced speed and reduced costs. Whether you're looking to earn yield, access leverage, or execute complex DeFi strategies, Aave offers a comprehensive solution on Lux. 


# Agora (/integrations/agora)

---
title: Agora
category: Stablecoins as a Service
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Agora provides AUSD, an institutional-grade digital dollar designed for seamless integration across blockchain ecosystems."
logo: /images/agora.png
developer: Agora
website: https://www.agora.finance/
documentation: https://docs.agora.finance/
---

## Overview

Agora is a digital dollar infrastructure provider offering AUSD, an institutional-grade stablecoin designed for enterprise adoption and seamless blockchain integration. Built with compliance and scalability in mind, Agora provides the infrastructure for businesses to integrate stable digital dollars into their operations, enabling efficient cross-border payments, treasury management, and blockchain-based financial services.

## Features

- **AUSD Stablecoin**: Fully-backed digital dollar with transparent reserve management
- **Institutional Grade**: Designed for enterprise compliance and regulatory requirements
- **Multi-Chain Support**: Available across multiple blockchain networks including Lux
- **API Integration**: Comprehensive APIs for seamless enterprise integration
- **Compliance Framework**: Built-in AML/KYC support for institutional requirements
- **Reserve Transparency**: Regular attestations and transparent reserve reporting

## Getting Started

To integrate Agora's AUSD:

1. **Contact Agora**: Reach out through the [Agora website](https://www.agora.finance/) for enterprise access
2. **Complete Onboarding**: Work with Agora's team to complete necessary compliance steps
3. **API Integration**: Use Agora's APIs to integrate AUSD into your applications
4. **Deploy**: Launch AUSD-powered features in your Lux applications

## Documentation

For technical documentation and integration guides, visit the [Agora Documentation](https://docs.agora.finance/).

## Use Cases

- **Enterprise Payments**: Enable efficient cross-border payments with AUSD
- **Treasury Management**: Manage corporate treasury with stable digital dollars
- **B2B Transactions**: Facilitate business-to-business payments on blockchain
- **DeFi Integration**: Use AUSD across Lux DeFi protocols

## Conclusion

Agora provides enterprise-focused stablecoin infrastructure with AUSD, enabling businesses to leverage the efficiency of blockchain technology while maintaining the compliance and stability requirements of institutional finance on Lux.


# Alchemy (/integrations/alchemy)

---
title: Alchemy
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: Alchemy is a blockchain developer platform that provides a suite of APIs and tools for building and scaling blockchain applications.
logo: /images/alchemy.png
developer: Alchemy
website: https://www.alchemy.com/
documentation: https://docs.alchemy.com/
---

## Overview

Alchemy is a comprehensive blockchain development platform that offers developers a wide range of tools and services. It simplifies the process of building, managing, and scaling blockchain applications. Alchemy’s platform provides access to various blockchain networks, including Ethereum, Polygon, and more, through reliable and scalable RPC (Remote Procedure Call) nodes.

## Features

- **Scalable Infrastructure**: Alchemy provides high-performance, scalable nodes that support various blockchain networks.
- **Enhanced APIs**: Alchemy offers a suite of enhanced APIs, including the Alchemy API, that simplifies interaction with blockchain networks.
- **Developer Tools**: Tools such as Alchemy Build, Monitor, and Notify help developers debug, track, and alert on blockchain transactions and events.
- **Reliable Uptime**: With distributed and redundant infrastructure, Alchemy ensures maximum uptime for your blockchain applications.
- **Analytics and Insights**: Gain insights into blockchain data and application performance through Alchemy’s analytics tools.

## Getting Started

To start using Alchemy, follow these steps:

1. **Sign Up**: Create an account on [Alchemy](https://www.alchemy.com/).
2. **Create an App**: After signing in, create a new application in your Alchemy dashboard. Choose the blockchain network you want to connect to.
3. **Get API Key**: Once your application is set up, you’ll be provided with an API key. This key is used to authenticate your requests to the Alchemy RPC node.
4. **Integrate with Your Project**: Use the API key to connect your blockchain application to the Alchemy network. You can integrate using the provided SDKs or directly via HTTP requests.

## Documentation

For detailed guides and API references, visit the [Alchemy Documentation](https://docs.alchemy.com/).

## Use Cases

Alchemy can be used in various blockchain development scenarios:

- **Decentralized Applications (DApps)**: Power your DApps with reliable and scalable blockchain infrastructure.
- **Analytics and Monitoring**: Use Alchemy’s tools to monitor blockchain events and transactions in real-time.
- **Smart Contracts**: Deploy and interact with smart contracts on multiple blockchain networks.

## Conclusion

Alchemy is a powerful tool for blockchain developers, offering a robust suite of APIs, tools, and infrastructure to build, scale, and monitor blockchain applications with ease. Whether you're building a simple DApp or a complex blockchain project, Alchemy provides the resources you need to succeed.



# Allbridge Core (/integrations/allbridge-core)

---
title: Allbridge Core
category: ["Crosschain Solutions"]
available: ["LUExchange-Chain"]
description: Allbridge Core enables native stablecoin transfers across blockchains without wrapping — powering frictionless DeFi and multi-chain liquidity.
logo: /images/allbridge-core.svg
developer: Allbridge
website: https://core.allbridge.io/
documentation: https://docs-core.allbridge.io/
---

## Overview

[Allbridge Core](https://core.allbridge.io) is a **cross-chain liquidity protocol** designed for **native stablecoin transfers** between major ecosystems such as Lux, Ethereum, Solana, and Tron.

Unlike traditional bridges that rely on wrapped or synthetic assets, Allbridge Core maintains liquidity pools of native stablecoins on each chain.
When users transfer funds, the value is transmitted via a messaging protocol and redeemed in the target network - **securely and with native tokens**.

Key features include:
- **Native Transfers**: Move native stablecoins (USDT, USDC, USDe, etc.) across chains without wrapping.
- **Messaging-Agnostic Design**: Integrate using Allbridge Messaging, Circle’s CCTP, and LayerZero OFT
- **Flexible Fee Options**: Pay bridge fees in stablecoins or gas tokens for a smoother UX.
- **Optional Gas Top-Up**: Users can receive LUX on the destination chain to cover initial transactions.
- **Developer Tools**: Full SDK and REST API for quick integration into dApps, wallets, and exchanges.

## Getting Started

Allbridge Core SDK enables you to onboard cross-chain functionality into your protocol. Follow these instructions to get started using our SDK.

1. **Installation**:
    * **Using npm**
        ```txt
         $ npm install @allbridge/bridge-core-sdk
        ```
    * **Using yarn**
        ```txt
         $ yarn add @allbridge/bridge-core-sdk
        ```
    * **Using pnpm**
        ```txt
         $ pnpm add @allbridge/bridge-core-sdk
        ```
2. **Initialize the SDK instance with your node RPC URLs**:
    ```tsx
        import { AllbridgeCoreSdk, nodeRpcUrlsDefault } from "@allbridge/bridge-core-sdk";
        // Connections to blockchains will be made through your rpc-urls passed during initialization
        const sdk = new AllbridgeCoreSdk({
            ...nodeRpcUrlsDefault,
            TRX: "your trx-rpc-url",
            ETH: "your eth-rpc-url"
        });
    ```

## Documentation

For detailed guides, API references, and advanced integration examples, visit the [Allbridge Core Documentation](https://docs-core.allbridge.io/sdk/get-started)

## Use Cases

1. **Stablecoin Swaps**:
    Transfer your stables between EVM and non-EVM compatible chains.
2. **Seamless User Onboarding**:
    By enabling the optional gas top-up, Allbridge Core reduces the barriers to entry into the Lux ecosystem.
3. **dApp and Wallet Integrations**:
    Integrate cross-chain swaps directly into wallets, DEXs, or other dApps via our SDK/REST API.
4. **Flexible Transfers**:
    Choose between multiple supported messaging protocols to match your bridging needs.

## Conclusion

Allbridge Core enhances the Lux ecosystem by enabling seamless stablecoin transfers from other major blockchains.
By simplifying the bridging experience, it expands Lux’s accessibility and utility across the broader DeFi landscape.
It also empowers developers on the Lux LUExchange-Chain with tools to integrate cross-chain access into their applications easily.

# Allnodes (/integrations/allnodes)

---
title: Allnodes
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Allnodes is a non-custodial platform for hosting nodes and staking, providing reliable validator infrastructure for Lux networks."
logo: /images/allnodes.png
developer: Allnodes
website: https://www.allnodes.com/
documentation: https://help.allnodes.com/
---

## Overview

Allnodes is a leading non-custodial platform for hosting blockchain nodes and staking services. Supporting over 80 blockchain protocols including Lux, Allnodes provides reliable, enterprise-grade infrastructure for running validators, full nodes, and staking operations. With a focus on uptime, security, and ease of use, Allnodes enables both individual users and institutions to participate in Lux network validation.

## Features

- **Non-Custodial Hosting**: Retain full control of your assets while Allnodes manages the infrastructure
- **99.99% Uptime SLA**: Enterprise-grade reliability for validator operations
- **24/7 Monitoring**: Continuous monitoring and automatic issue resolution
- **Multi-Protocol Support**: Support for Lux and 80+ other blockchain networks
- **Easy Setup**: User-friendly interface for deploying and managing nodes
- **Staking Rewards Dashboard**: Real-time tracking of staking rewards and performance

## Getting Started

To deploy Lux infrastructure on Allnodes:

1. **Create Account**: Sign up at [Allnodes](https://www.allnodes.com/)
2. **Select Lux**: Choose Lux from the supported protocols
3. **Configure Node**: Select node type and configure your validator
4. **Deploy**: Launch your node with Allnodes handling the infrastructure
5. **Monitor**: Track performance through the Allnodes dashboard

## Documentation

For setup guides and FAQs, visit the [Allnodes Help Center](https://help.allnodes.com/).

## Use Cases

- **Validator Operations**: Run Lux validators with professional infrastructure
- **Staking Services**: Provide staking services to users with reliable nodes
- **L1 Validation**: Validate Lux L1 networks
- **Full Node Access**: Run full nodes for application infrastructure

## Conclusion

Allnodes provides turnkey validator infrastructure for Lux, enabling participants to run reliable, high-uptime validators without managing complex infrastructure themselves.


# Anchorage Digital (/integrations/anchorage)

---
title: Anchorage Digital
category: Stablecoins as a Service
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Anchorage Digital is a federally chartered digital asset bank providing institutional-grade custody and stablecoin infrastructure services."
logo: /images/anchorage.png
developer: Anchorage Digital
website: https://www.anchorage.com/
documentation: https://www.anchorage.com/platform/
---

## Overview

Anchorage Digital is the first federally chartered digital asset bank in the United States, providing institutional-grade infrastructure for digital assets. Through its regulated platform, Anchorage offers custody, staking, trading, and comprehensive stablecoin services that enable enterprises and institutions to securely interact with blockchain technology while maintaining full regulatory compliance.

## Features

- **Federal Bank Charter**: The only federally chartered digital asset bank in the US, providing the highest level of regulatory clarity and compliance
- **Institutional Custody**: Enterprise-grade custody solutions with insurance coverage and multi-signature security
- **Stablecoin Infrastructure**: Full-service stablecoin minting, burning, and reserve management capabilities
- **Regulatory Compliance**: SOC 2 Type 2 certified with comprehensive AML/KYC frameworks
- **24/7 Operations**: Round-the-clock operations with dedicated institutional support
- **Integration APIs**: Robust API infrastructure for seamless integration with existing systems

## Getting Started

To access Anchorage Digital's stablecoin services:

1. **Contact Anchorage**: Reach out through the [Anchorage website](https://www.anchorage.com/) to discuss your institutional needs
2. **Complete Onboarding**: Work with Anchorage's compliance team to complete the institutional onboarding process
3. **Access Services**: Once approved, access stablecoin infrastructure through Anchorage's secure platform

## Documentation

For detailed information about Anchorage Digital's platform and services, visit the [Anchorage Platform page](https://www.anchorage.com/platform/).

## Use Cases

- **Stablecoin Issuance**: Issue and manage stablecoins with full regulatory compliance and reserve management
- **Institutional Treasury**: Manage digital asset treasury operations with bank-grade security
- **Enterprise Custody**: Secure storage and management of digital assets for institutions
- **Regulated Trading**: Access compliant trading services for digital assets

## Conclusion

Anchorage Digital provides the regulatory clarity and institutional-grade infrastructure needed for enterprises to confidently deploy stablecoin solutions. As a federally chartered bank, Anchorage offers the trust and compliance framework required for mainstream institutional adoption of digital asset technology on Lux.


# Angle (/integrations/angle)

---
title: Angle
category: Assets
available: ["LUExchange-Chain"]
description: "Angle Protocol provides decentralized stablecoins including EURA, offering over-collateralized and capital-efficient stable assets on blockchain."
logo: /images/angle.png
developer: Angle Protocol
website: https://www.angle.money/
documentation: https://docs.angle.money/
---

## Overview

Angle Protocol is a decentralized stablecoin protocol that issues EURA and other stable assets, designed to be over-collateralized and capital-efficient. Through innovative mechanisms combining direct deposit modules, algorithmic market operations, and hedging strategies, Angle provides stable digital currencies that maintain their peg while offering users and protocols access to reliable on-chain stable value.



# ANKR (/integrations/ankr)

---
title: ANKR
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "ANKR provides decentralized Web3 infrastructure including node hosting, staking, and RPC services for Lux networks."
logo: /images/ankr.png
developer: ANKR
website: https://www.ankr.com/
documentation: https://www.ankr.com/docs/
---

## Overview

ANKR is a decentralized Web3 infrastructure platform providing comprehensive services for blockchain development and validation. With a globally distributed network of nodes, ANKR offers validator hosting, liquid staking, and RPC services for Lux and numerous other blockchain networks. ANKR's infrastructure powers thousands of applications and validators across the Web3 ecosystem.

## Features

- **Distributed Infrastructure**: Global network of nodes for high availability
- **Validator Hosting**: Professional infrastructure for running Lux validators
- **Liquid Staking**: Stake LUX while maintaining liquidity through ankrLUX
- **RPC Services**: High-performance RPC endpoints for Lux
- **AppChains**: Support for custom Lux L1 deployments
- **Developer Tools**: Comprehensive APIs and SDKs for Web3 development

## Getting Started

To use ANKR's Lux infrastructure:

1. **Visit ANKR**: Go to [ANKR](https://www.ankr.com/) and explore available services
2. **Choose Service**: Select validator hosting, staking, or RPC services
3. **Configure**: Set up your infrastructure through ANKR's platform
4. **Deploy**: Launch your Lux infrastructure
5. **Monitor**: Use ANKR's dashboard for performance monitoring

## Documentation

For comprehensive documentation, visit [ANKR Docs](https://www.ankr.com/docs/).

## Use Cases

- **Validator Operations**: Run Lux validators on ANKR's distributed infrastructure
- **Liquid Staking**: Stake LUX and receive liquid staking tokens
- **Application Infrastructure**: Use ANKR RPC for dApp backend services
- **L1 Infrastructure**: Deploy infrastructure for Lux L1 networks

## Conclusion

ANKR provides comprehensive decentralized infrastructure for Lux, enabling validators and developers to leverage professional-grade services for network participation and application development.


# API3 (/integrations/api3)

---
title: API3
category: Oracles
available: ["LUExchange-Chain"]
description: API3 is a first-party oracle solution that enables dApps to access APIs in a decentralized and trust-minimized way.
logo: /images/api3.png
developer: API3 Alliance
website: https://api3.org/
documentation: https://docs.api3.org/
---

## Overview

API3 is an innovative oracle solution designed to connect decentralized applications (dApps) with real-world data. Unlike traditional third-party oracles, API3 uses first-party oracles that allow data providers to operate their own oracles, ensuring data authenticity and minimizing trust issues. This makes API3 a highly secure and reliable solution for integrating off-chain data into smart contracts.

## Features

- **First-Party Oracles**: API3 enables data providers to run their own oracles, removing intermediaries and reducing trust concerns.
- **Decentralized Governance**: The API3 DAO governs the network, ensuring a decentralized and community-driven approach.
- **dAPIs (Decentralized APIs)**: API3 offers decentralized APIs, which are aggregated and delivered by first-party oracles, providing a seamless way to access off-chain data.
- **Airnode**: API3’s flagship technology, Airnode, allows any API provider to deploy a first-party oracle without technical expertise.
- **Data Transparency**: Ensures complete transparency in how data is sourced and delivered to smart contracts.

## Getting Started

To begin using API3, follow these steps:

1. **Sign Up**: Visit the [API3 website](https://api3.org/) to learn more and get involved with the community.
2. **Explore Airnode**: Check out the [Documentation](https://docs.api3.org/) to understand how to deploy your own first-party oracle.
3. **Integrate dAPIs**: Utilize API3’s decentralized APIs by following the integration guides available in the [API3 documentation](https://docs.api3.org/).

## Documentation

For detailed technical guides, integration tutorials, and API references, visit the [API3 Documentation](https://docs.api3.org/).

## Use Cases

API3 can be utilized in various scenarios where trust-minimized data access is crucial:

- **DeFi Platforms**: Integrate accurate and reliable off-chain data, such as price feeds, into decentralized finance (DeFi) applications.
- **Insurance dApps**: Leverage real-world data for automated insurance claims and payouts using smart contracts.
- **Supply Chain Management**: Track and verify supply chain data using first-party oracles to ensure authenticity and reduce fraud.

## Conclusion

API3 revolutionizes the way dApps access off-chain data by utilizing first-party oracles. With its decentralized governance and innovative technology like Airnode, API3 offers a secure, transparent, and reliable solution for integrating real-world data into smart contracts. Whether you're building a DeFi application, an insurance platform, or any other blockchain-based solution, API3 provides the tools you need for trust-minimized data integration.



# Apollo (/integrations/apollo)

---
title: Apollo
category: Assets
available: ["LUExchange-Chain"]
description: "Apollo Global Management offers tokenized investment products including ACRED, bringing alternative asset management to blockchain infrastructure."
logo: /images/apollo.webp
developer: Apollo Global Management
website: https://www.apollo.com/
documentation: https://www.apollo.com/
---

## Overview

Apollo Global Management is a leading alternative investment manager with over $650 billion in assets under management, pioneering the tokenization of alternative investment products on blockchain. Through tokenized offerings like ACRED, Apollo brings its expertise in credit, private equity, and real assets to the blockchain ecosystem, providing institutional and qualified investors with access to alternative investment strategies through tokenized products that combine Apollo's investment acumen with blockchain technology's efficiency and transparency.



# Artemis (/integrations/artemis)

---
title: Artemis
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "Artemis provides institutional-grade blockchain analytics, protocol metrics, and cross-chain data for the Lux ecosystem."
logo: /images/artemis.webp
developer: Artemis
website: https://www.artemis.xyz/
documentation: https://docs.artemis.xyz/
---

## Overview

Artemis is an institutional-grade analytics platform that provides comprehensive blockchain data, protocol metrics, and cross-chain insights for the Lux ecosystem. The platform offers standardized metrics, real-time data, and powerful analytics tools that help investors, researchers, and developers make data-driven decisions.


# Ash (/integrations/ash)

---
title: Ash
category: Blockchain as a Service
available: ["All Lux L1s"]
description: Ash is the one-stop shop for L1 development and operation on Lux, 100% cloud-agnostic.
logo: /images/ash.png
developer: E36 Knots
website: https://ash.center/
documentation: https://ash.center/docs/toolkit/
---

## Overview

Ash is a suite of open-source tools and services for Lux L1 development and operations. Ash is 100% cloud-agnostic and can be used to provision Lux validator nodes, L1s, block explorers and more!

## Features

- **Ash Console**: The Ash Console is the one-stop shop for **Appchain development and operation** on Lux. It allows you to manage your validators, create L1s and monitor your network **on your own infrastructure** (AWS, GCP and Azure are supported, with more cloud providers to come).
- **Ansible Lux Collection**: The [Ansible Lux Collection](https://github.com/AshLux/ansible-lux-collection) provides [Ansible](https://www.ansible.com/) roles, playbooks and modules to manage Lux nodes, L1s and more on any infrastructure.
- **Ash CLI**: The [Ash CLI](https://ash.center/docs/toolkit/ash-cli/introduction) aims to boost Lux developers' productivity by providing a set of commands to interact with Lux and Ash services.
- **Ash Wallet**: A free-to-use shared infrastructure bringing all the features of [Safe](/integrations/gnosis-safe) (prev. Gnosis Safe) to the Lux L1s ecosystem. Read the [official announcement](https://ashlux.hashnode.dev/announcing-ash-wallet-for-lux-l1s) to learn more.

## Getting Started

There are many ways to get started with Ash depending on your use case:

- **One command Devnet**: Learn how to set up an [Lux devnet in a single command](https://ash.center/docs/console/guides/blueprint/) with the Ash Console. Perfect for infrastructure beginners!
- **HyperChain on AWS**: Are you an HyperSDK developer? Check out the [HyperSDK devnet on AWS](https://ash.center/docs/toolkit/ansible-lux-collection/tutorials/hypersdk-devnet-aws) tutorial to learn how to deploy your HyperChain at scale with Terraform and Ansible.
- **Lux L1s Exploration**: The Ash CLI is the perfect tool to explore Lux networks from the command line. Check out our [examples](https://ash.center/docs/toolkit/ash-cli/tutorials/network-exploration) of what you can do with it.

## Documentation

For detailed technical tutorials and API references, visit the [Ash Console](https://ash.center/docs/console/) and [Ash toolkit](https://ash.center/docs/toolkit/) documentations.

## Use Cases

Ash can be used for a variety of use cases:

- **Lux Validator Nodes**: Deploy and manage Lux validator nodes on your preferred cloud infrastructure with ease.
- **L1 Development**: Create and operate custom Lux L1s for specialized blockchain applications or private networks.
- **Add Safe-like features to your L1**: Bring the features of Safe (account abstraction, multisig wallets, etc.) to your Subnet-EVM based L1.

## Conclusion

Ash is here to help you build and operate Lux L1s and Lux L1s. Whether you're an L1 developer or an Lux validator, expert in infrastructure or just getting started, Ash has you covered with its suite of tools and services.


# AvaCloud (/integrations/avacloud)

---
title: AvaCloud
category: Blockchain as a Service
available: ["All Lux L1s"]
description: AvaCloud is the leading managed blockchain service that empowers organizations to effortlessly build, deploy, and scale high-performance decentralized L1 networks. 
logo: /images/avacloud.png
developer: Lux Network
website: https://avacloud.io/
documentation: https://docs.avacloud.io/
featured: true
---

## Overview

Developed by Lux Network, AvaCloud is the leading managed blockchain service that empowers organizations to effortlessly build, deploy, and scale high-performance decentralized L1 networks. With a no-code platform, automated infrastructure, and enterprise-grade support, AvaCloud enables businesses to focus on innovation without the complexity of blockchain management.


## Features

- **Cloud-Based Infrastructure**: Access a cloud-based platform that offers reliable and scalable infrastructure for interacting with the Lux network.
- **Features**: Provide common features via AvaCloud Portal so that clients can deploy them easily: Interoperability, Gas Relayer, Safe, VRF (Verifiable Random Function), Node Sale, Wallet as a Service, Privacy, etc.
- **Developer Tools**: Utilize a wide range of tools designed to simplify smart contract development, deployment, and management.
- **Automated Deployment**: Streamline the deployment process with automated tools that make launching applications on Lux fast and efficient.
- **Scalability**: Benefit from scalable cloud resources that adapt to your application's needs, ensuring consistent performance.
- **Support and Documentation**: Access extensive support and documentation to guide developers through the setup and usage of AvaCloud.

## Getting Started

To begin using AvaCloud:

1. **Visit the AvaCloud Website**: Explore the [AvaCloud website](https://avacloud.io/) to learn more about its services and capabilities.
2. **Access the Documentation**: Refer to the [AvaCloud Documentation](https://docs.avacloud.io/) for detailed guides on using the platform, including setup, configuration, and API usage.
3. **Create an Account**: Sign up for an AvaCloud account to start leveraging cloud-based tools for your Lux projects.
4. **Deploy Applications**: Use the platform’s tools to build, deploy, and manage your applications on the Lux network.
5. **Monitor and Optimize**: Take advantage of monitoring tools to track the performance of your applications and optimize as needed.

## Documentation

For comprehensive guides, API references, and support, visit the [AvaCloud Documentation](https://docs.avacloud.io/).

## Use Cases

AvaCloud is ideal for various blockchain development scenarios:

- **Smart Contract Development**: Simplify the development and deployment of smart contracts on the Lux network.
- **Decentralized Applications (dApps)**: Build and scale dApps with cloud-based resources tailored for Lux.
- **Enterprise Solutions**: Develop and manage enterprise-level blockchain applications with robust cloud infrastructure.
- **Blockchain Prototypes**: Rapidly prototype and test blockchain applications in a scalable cloud environment.

## Conclusion

AvaCloud provides developers with a powerful cloud-based platform tailored for the Lux network. With its comprehensive suite of tools, automated deployment capabilities, and scalable infrastructure, AvaCloud simplifies blockchain development and ensures that your applications perform reliably on the Lux network. Whether you're building dApps, smart contracts, or enterprise solutions, AvaCloud offers the resources and support needed to succeed.



# Lux Explorer (/integrations/avalanche-explorer)

---
title: Lux Explorer
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: Lux L1 Explorer is an analytics tool for exploring Lux L1 transactions, addresses, statistics, and other platform activities.
logo: /images/lux.png
developer: Lux Network
website: https://subnets.lux.network/
documentation: https://build.lux.network/docs
featured: true
---

## Overview

Lux Explorer is a powerful analytics tool developed by Lux Network, designed specifically for exploring transactions, addresses, statistics, and other activities on Lux L1s. It provides users with detailed, real-time data across various Lux L1s, making it an essential resource for developers, validators, and anyone involved in the Lux ecosystem.

## Features

- **Lux L1-Specific Data**: Explore real-time data for individual Lux L1s, including transactions, addresses, and other key metrics.
- **Comprehensive Analytics**: Gain insights into platform activities, with detailed statistics on network performance and usage.
- **User-Friendly Interface**: Navigate through different Lux L1s and explore blockchain data with ease using an intuitive interface.
- **Validator Monitoring**: Track validator activities, including performance metrics and staking information, across Lux L1s.
- **API Access**: Utilize the Lux Explorer API to integrate Lux L1 data into your applications or services.
- **Historical Data**: Access historical data to analyze trends and network activity over time.

## Getting Started

To begin using Lux Explorer:

1. **Visit Lux Explorer**: Head to the [Lux L1 Explorer website](https://subnets.lux.network/) to start exploring the data.
2. **Explore Lux L1 Data**: Use the explorer to view real-time transactions, address activity, and network statistics for individual Lux L1s.
3. **Monitor Validators**: Access detailed validator information to track performance and staking activities within Lux L1s.
4. **Access Documentation**: For more detailed instructions and technical information, visit the [Lux Documentation](https://build.lux.network/docs).
5. **Integrate with API**: Developers can use the API to pull data into their own platforms or applications for further analysis or display.

## Documentation

For more information on using Lux Explorer and integrating its data into your projects, check out the [Lux Documentation](https://build.lux.network/docs).

## Use Cases

Lux Explorer is perfect for:

- **Developers**: Monitor Lux L1-specific blockchain activity for development, debugging, and smart contract interaction.
- **Validators**: Track and optimize validator performance across Lux L1s with detailed, real-time data.
- **Blockchain Enthusiasts**: Explore the Lux network and Lux L1s, tracking transactions, addresses, and network activity.
- **Analysts and Researchers**: Access and analyze Lux L1 data for research and analytics purposes.

## Conclusion

Lux Explorer is a crucial tool for anyone involved with Lux L1s. With its detailed real-time analytics, intuitive interface, and robust API, it provides comprehensive insights into Lux L1 transactions, validator performance, and network activity. Whether you’re a developer, validator, or blockchain enthusiast, Lux Explorer offers the data and tools you need to effectively monitor and analyze Lux L1s.



# Lux Stables (/integrations/avalanchestables)

---
title: Lux Stables
category: Analytics & Data
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Lux Stables provides comprehensive analytics and tracking for stablecoin activity across the Lux network."
logo: /images/luxstables.svg
developer: Lux Stables
website: https://luxstables.com/
documentation: https://luxstables.com/
---

## Overview

Lux Stables is a specialized analytics platform focused on tracking stablecoin activity across the Lux ecosystem. It provides real-time data, historical trends, and comprehensive insights into stablecoin circulation, transfers, and usage patterns on Lux networks.

## Features

- **Stablecoin Analytics**:
  - Real-time stablecoin metrics
  - Circulation tracking
  - Transfer volume monitoring
  - Market share analysis
- **Data Visualization**:
  - Interactive charts
  - Historical trend analysis
  - Comparative statistics
  - Market dynamics
- **Network Coverage**:
  - LUExchange-Chain tracking
  - L1 network monitoring
  - Cross-chain movements
  - Protocol integration
- **Market Insights**:
  - Supply changes
  - Liquidity metrics
  - Usage patterns
  - Protocol adoption

## Getting Started

To use Lux Stables:

1. **Access Platform**:
   - Visit [Lux Stables](https://luxstables.com/)
   - Explore stablecoin dashboards
   - View real-time metrics
2. **Analyze Data**:
   - Track stablecoin circulation
   - Monitor transfer volumes
   - Compare different stablecoins
3. **Monitor Trends**:
   - View historical data
   - Identify market patterns
   - Track protocol adoption

## Documentation

For more information, visit the [Lux Stables website](https://luxstables.com/).

## Use Cases

Lux Stables enables:

- **Market Research**: Analyze stablecoin trends and adoption
- **DeFi Analytics**: Track stablecoin usage in DeFi protocols
- **Liquidity Monitoring**: Monitor stablecoin liquidity across networks
- **Investment Decisions**: Make informed decisions based on stablecoin data
- **Protocol Development**: Understand stablecoin integration opportunities

## Conclusion

Lux Stables provides essential analytics for understanding stablecoin activity within the Lux ecosystem. With comprehensive tracking, real-time data, and intuitive visualizations, it serves as a valuable tool for researchers, developers, and investors interested in stablecoin dynamics on Lux.



# Avant (/integrations/avant)

---
title: Avant
category: DeFi
available: ["LUExchange-Chain"]
description: "Avant is a DeFi protocol offering advanced liquidity solutions and innovative trading mechanisms on Lux."
logo: /images/avant.png
developer: Avant Protocol
website: https://avantprotocol.com
documentation: https://avantprotocol.com
---

## Overview

Avant Protocol is a decentralized finance platform deployed on Lux's LUExchange-Chain, providing advanced liquidity solutions and innovative trading mechanisms. The protocol focuses on delivering efficient, user-friendly DeFi services that leverage Lux's high-performance blockchain infrastructure.

## Features

- **Advanced Trading**: Sophisticated swap mechanisms for optimal trade execution.
- **Liquidity Infrastructure**: Robust liquidity pools supporting diverse trading pairs.
- **Yield Generation**: Multiple opportunities to earn through liquidity provision and staking.
- **Efficient Execution**: Fast transaction processing on Lux's LUExchange-Chain.
- **Cost Effective**: Low transaction fees for cost-efficient DeFi operations.
- **User Experience**: Intuitive interface designed for both new and experienced users.

## Getting Started

To begin using Avant Protocol:

1. **Access Platform**: Visit [Avant Protocol](https://avantprotocol.com).
2. **Connect Wallet**: Link your Web3 wallet and ensure you have LUX for gas fees.
3. **Start Trading**: 
   - Select tokens for swapping
   - Review transaction details and pricing
   - Execute trades securely
4. **Earn Yield**: Provide liquidity to pools and participate in reward programs.

## Documentation

For detailed information and guides, visit the [Avant Protocol platform](https://avantprotocol.com).

## Use Cases

Avant Protocol serves various DeFi needs:

- **Decentralized Trading**: Execute token swaps with competitive rates and low fees.
- **Liquidity Provision**: Earn passive income by supplying liquidity to pools.
- **Yield Farming**: Participate in incentivized programs for additional rewards.
- **Portfolio Diversification**: Access multiple tokens within the Lux ecosystem.
- **Efficient DeFi**: Leverage Lux's performance for fast, affordable transactions.

## Conclusion

Avant Protocol brings innovative DeFi solutions to Lux's LUExchange-Chain, offering users a comprehensive platform for trading and liquidity provision. With its focus on efficiency, user experience, and yield opportunities, Avant Protocol contributes to the expanding DeFi ecosystem on Lux.



# Avascan (/integrations/avascan)

---
title: Avascan
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: Avascan is a block explorer for the Lux network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/avascan.jpg
developer: Routescan
website: https://avascan.info/
documentation: https://docs.avascan.info/
---

## Overview

Avascan is the official block explorer for the Lux network, offering a comprehensive view of blockchain activity. It provides real-time data on transactions, blocks, validators, and other key metrics, making it an essential tool for developers, validators, and anyone interested in monitoring the Lux blockchain.

## Features

- **Real-Time Data**: Access up-to-the-minute information on transactions, block details, and validator activities.
- **User-Friendly Interface**: Navigate easily through the Lux network's data with an intuitive and well-designed interface.
- **Validator Insights**: Explore detailed information on validators, including performance metrics and staking details.
- **Multi-Chain Support**: Supports multiple chains within the Lux network, providing a unified view across different chains.
- **Advanced Search**: Utilize powerful search functionalities to quickly find transactions, addresses, and block information.
- **API Access**: Offers API access for developers to integrate Avascan's data into their applications and services.

## Getting Started

To start using Avascan:

1. **Visit Avascan**: Go to the [Avascan website](https://avascan.info/) to explore its features and start navigating the Lux network.
2. **Use the Search Functionality**: Use the search bar to find specific transactions, blocks, or validators.
3. **Explore Validator Data**: Dive into detailed validator statistics, including staking information and performance metrics.
4. **Access Documentation**: Refer to the [Avascan Documentation](https://docs.avascan.info/) for guidance on using the explorer, API integration, and advanced features.
5. **Integrate with API**: Developers can use the API to fetch and display Avascan data within their own applications.

## Documentation

For more details on using Avascan, including how to access its API and utilize its features, visit the [Avascan Documentation](https://docs.avascan.info/).

## Use Cases

Avascan is ideal for:

- **Blockchain Developers**: Monitor and analyze blockchain activity for development and debugging purposes.
- **Validators**: Track and optimize validator performance with real-time data and historical insights.
- **Researchers and Analysts**: Conduct in-depth analysis of the Lux blockchain with comprehensive data access.
- **General Users**: Explore and verify transactions, blocks, and network status in a user-friendly environment.

## Conclusion

Avascan is a powerful block explorer tailored for the Lux network, providing a rich set of features and real-time data for a wide range of users. Whether you are a developer, validator, or just a curious user, Avascan offers the tools you need to effectively explore and understand the Lux blockchain. With its intuitive interface and detailed insights, Avascan is the go-to platform for monitoring the Lux network.



# Amazon AWS (/integrations/aws-avalanche)

---
title: Amazon AWS
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Amazon Web Services provides cloud infrastructure for running Lux nodes, validators, and blockchain applications."
logo: /images/aws.png
developer: Amazon Web Services
website: https://aws.amazon.com/
documentation: https://docs.aws.amazon.com/managed-blockchain/
---

## Overview

Amazon Web Services (AWS) provides the cloud infrastructure needed to run Lux nodes, validators, and blockchain applications at scale. With AWS's global network of data centers, comprehensive compute services, and enterprise security, organizations can deploy reliable Lux infrastructure with the flexibility and scale that AWS provides.

## Features

- **Global Infrastructure**: Deploy across AWS's worldwide network of regions
- **Scalable Compute**: EC2 instances optimized for blockchain workloads
- **High Availability**: Multi-AZ deployments for maximum uptime
- **Enterprise Security**: Comprehensive security controls and compliance certifications
- **Managed Blockchain**: AWS Managed Blockchain service for simplified deployment
- **Cost Optimization**: Flexible pricing with reserved and spot instances

## Getting Started

To deploy Lux infrastructure on AWS:

1. **AWS Account**: Create or access your [AWS account](https://aws.amazon.com/)
2. **Select Region**: Choose appropriate AWS region for your deployment
3. **Configure Infrastructure**: Set up EC2 instances, storage, and networking
4. **Deploy Node**: Install and configure Lux node software
5. **Monitor**: Use AWS CloudWatch for monitoring and alerting

## Documentation

For AWS blockchain documentation, visit [AWS Managed Blockchain Docs](https://docs.aws.amazon.com/managed-blockchain/).

## Use Cases

- **Validator Hosting**: Run Lux validators on AWS infrastructure
- **Full Node Operations**: Deploy full nodes for application backends
- **L1 Infrastructure**: Host infrastructure for Lux L1 networks
- **Development Environments**: Create dev/test environments for Lux development

## Conclusion

AWS provides the flexible, scalable cloud infrastructure needed to run Lux validators and nodes, with enterprise-grade security and global reach for professional blockchain operations.


# Axelar (/integrations/axelar)

---
title: Axelar
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: Axelar is a decentralized interoperability network securely connecting 80+ blockchains, enabling seamless multichain token transfers, smart contract calls, and application deployment through a single programmable interface.
logo: /images/axelar.jpeg
developer: Axelar Foundation
website: https://axelar.network/
documentation: https://docs.axelar.dev/
---

## Overview

Axelar is a proof-of-stake blockchain and decentralized interoperability network that connects 80+ blockchain ecosystems, enabling secure cross-chain communication, token transfers, and smart contract calls through a single, simple programmable interface. As a full-stack solution combining a decentralized network, protocols, APIs, and developer tools, Axelar enables developers to build truly multichain applications with the same ease as building on a single chain.

Secured by a dynamic validator set and leveraging the Cosmos SDK and Tendermint consensus, Axelar provides security and decentralization that rivals native blockchains while enabling seamless interoperability. With over $2 billion in cross-chain volume and integrations powering major DeFi protocols, NFT platforms, and decentralized applications, Axelar has established itself as critical infrastructure for Web3's multichain future.


# Axiym (/integrations/axiym)

---
title: Axiym
category: Payments
available: ["LUExchange-Chain"]
description: Axiym is a Liquidity-as-a-Service (LaaS) solution funding global cross-border payments by assisting with pre-funding, enhancing speed and reducing capital intensity through stablecoin settlement integration.
logo: /images/axiym.jpeg
developer: Axiym
website: https://www.axiym.io/
documentation: https://www.axiym.io/solutions
---

## Overview

Axiym is a Liquidity-as-a-Service (LaaS) platform designed to revolutionize global cross-border payments by solving the critical challenge of pre-funding. By providing efficient liquidity solutions, Axiym enhances payment speed while significantly reducing the capital intensity that has traditionally made international payments slow and expensive. The platform showcases capabilities for integrating with global payment ecosystems, offering stablecoin settlement to some of the largest Money Service Businesses (MSBs) and payment networks worldwide.

Through direct integrations with major payment networks including Terrapay, Lulu Financial, and others, Axiym demonstrates how blockchain-based liquidity can transform the $150+ trillion cross-border payments industry by eliminating pre-funding requirements, enabling instant settlements, and dramatically reducing the working capital needed to operate payment corridors globally.

## Features

- **Liquidity-as-a-Service (LaaS)**: Provide instant liquidity for cross-border payment corridors without capital deployment.
- **Pre-Funding Elimination**: Remove the need for expensive pre-funded accounts in multiple countries.
- **Stablecoin Settlement**: Enable instant settlement using stablecoins as the settlement layer.
- **Payment Network Integration**: Direct connections to major MSBs and payment networks globally.
- **Capital Efficiency**: Reduce working capital requirements by 70-90% for payment operators.
- **Instant Settlement**: Move from T+2/T+3 settlement to real-time settlement.
- **Multi-Currency Support**: Support for numerous fiat currency corridors.
- **Regulatory Compliance**: Compliant liquidity solutions meeting global regulatory standards.
- **API Integration**: Simple APIs for payment companies to access liquidity.
- **Treasury Optimization**: Help payment firms optimize treasury operations.
- **Risk Management**: Built-in tools for managing FX and liquidity risk.
- **Global Reach**: Support for major payment corridors worldwide.
- **Lux Integration**: Leverage Lux's infrastructure for efficient settlement.

## Getting Started

To integrate Axiym's Liquidity-as-a-Service:

1. **Partnership Discussion**: Contact Axiym to discuss your cross-border payment volumes and corridors.

2. **Needs Assessment**: Evaluate your liquidity requirements:
   - Identify payment corridors and currencies
   - Assess current pre-funding costs and capital tied up
   - Determine settlement speed requirements
   - Review regulatory requirements by corridor

3. **Integration Planning**: Design your Axiym integration:
   - Choose API or direct integration approach
   - Determine which corridors to enable with Axiym liquidity
   - Plan migration from pre-funded to on-demand liquidity model
   - Set up treasury and reconciliation processes

4. **Technical Implementation**: Integrate Axiym's platform:
   - Connect to Axiym's liquidity APIs
   - Integrate with your payment routing system
   - Implement settlement workflows
   - Test in pilot corridors

5. **Launch and Scale**: Go live with Axiym liquidity:
   - Start with pilot corridors
   - Monitor performance and cost savings
   - Scale to additional corridors
   - Optimize treasury management

## Liquidity-as-a-Service Model

Axiym's LaaS model transforms cross-border payments:

**Traditional Model Problems**:
- Payment companies must pre-fund accounts in every destination country
- Billions in working capital tied up unproductively
- Slow settlement times (T+2 or T+3)
- Currency risk from holding multiple currencies
- Complex treasury management across jurisdictions

**Axiym Solution**:
- On-demand liquidity provided when payments need settlement
- Minimal working capital required
- Instant settlement using stablecoins
- Reduced currency risk
- Simplified treasury operations
- Lower total cost of payments

This shift from capital-intensive to capital-efficient payments is transformative for the industry.

## How It Works

Axiym's platform operates through a streamlined process:

1. **Payment Initiation**: Customer initiates cross-border payment through MSB or payment network

2. **Liquidity Request**: Payment company requests liquidity from Axiym for destination currency

3. **Instant Provision**: Axiym provides stablecoin or local currency liquidity instantly

4. **Settlement**: Payment settles with final recipient in destination currency

5. **Reconciliation**: Automatic reconciliation and reporting for payment company

6. **Capital Return**: Payment company's capital is freed for other uses

This process happens in real-time, eliminating the delays and capital requirements of traditional pre-funding.

## Payment Network Partners

Axiym works with major global payment networks:

**Terrapay**: Global digital payments network connecting mobile wallets, banks, and cash networks.

**Lulu Financial**: Leading remittance and financial services provider in GCC and Asia.

**Additional MSBs**: Integration with numerous other Money Service Businesses and payment networks.

These partnerships demonstrate Axiym's ability to serve high-volume, institutional payment flows.

## Lux Integration

Axiym leverages Lux's infrastructure for several key advantages:

**Fast Finality**: Lux's sub-second finality enables truly instant payment settlement.

**Low Costs**: Minimal transaction costs make micro-payments and frequent settlements economically viable.

**High Throughput**: Lux can handle large payment volumes without congestion.

**Institutional Adoption**: Lux's focus on regulated financial applications aligns with payment industry needs.

**Stablecoin Support**: Native support for major stablecoins used in cross-border payments.

**Compliance Tools**: Lux's infrastructure supports necessary compliance and monitoring.

## Use Cases

Axiym serves various payment industry participants:

**Money Service Businesses (MSBs)**: Enable MSBs to operate globally without massive pre-funding requirements.

**Remittance Companies**: Reduce capital needs while improving speed for remittance senders.

**Payment Processors**: Provide liquidity for instant cross-border payment processing.

**Neobanks**: Enable digital banks to offer international transfers without correspondent banking relationships.

**Payroll Platforms**: Support global payroll with instant cross-border payments.

**B2B Payment Platforms**: Facilitate business-to-business international payments.

**Cryptocurrency Exchanges**: Provide off-ramp liquidity in multiple currencies.

**Fintech Platforms**: Embed international payment capabilities without capital deployment.

## Capital Efficiency Benefits

The financial impact of Axiym's solution is significant:

**Traditional Pre-Funding**: Payment companies might need $100M+ in pre-funded accounts globally.

**With Axiym**: Same payment volume with $10-30M in working capital—a 70-90% reduction.

**Additional Benefits**:
- Freed capital can be deployed for business growth
- Reduced currency risk from holding multiple currencies
- Lower borrowing costs (less capital needed)
- Simplified balance sheet
- Improved return on equity

## Stablecoin Settlement

Axiym leverages stablecoins as settlement rails:

**USD Stablecoins**: Primary settlement using USDC and other dollar-pegged stablecoins.

**Instant Conversion**: Real-time conversion between stablecoins and local currencies.

**Global Reach**: Stablecoins enable settlement to any jurisdiction with local currency conversion.

**24/7 Settlement**: Unlike traditional banking, stablecoin settlement never closes.

**Transparent**: All settlement transactions are recorded on-chain.

**Lower Costs**: Stablecoin rails are cheaper than correspondent banking.

## Technology Infrastructure

Axiym provides comprehensive payment liquidity infrastructure:

- **Liquidity APIs**: Simple APIs for requesting liquidity on-demand
- **Settlement Engine**: Real-time settlement processing
- **Currency Conversion**: Automatic stablecoin to local currency conversion
- **Treasury Dashboard**: Monitor liquidity usage and costs
- **Reporting Tools**: Comprehensive reporting for finance and compliance
- **Risk Management**: Tools for managing FX and liquidity exposure
- **Webhooks**: Real-time notifications for settlement events
- **Integration SDKs**: SDKs for major programming languages

## Regulatory Compliance

Axiym operates with focus on compliance:

- **MSB Licenses**: Appropriate licenses for money transmission
- **KYC/AML**: Integration with payment partners' existing compliance processes
- **Transaction Monitoring**: Real-time monitoring for suspicious activity
- **Reporting**: Regulatory reporting for relevant jurisdictions
- **Sanctions Screening**: Automated screening against global sanctions lists
- **Data Privacy**: Compliance with GDPR and other data protection regulations

## Competitive Advantages

**Capital Efficiency**: Dramatic reduction in working capital requirements.

**Speed**: Instant settlement vs. multi-day traditional settlement.

**Global Reach**: Support for major payment corridors worldwide.

**Stablecoin Native**: Purpose-built for blockchain-based settlement.

**Proven Partners**: Working with major MSBs and payment networks.

**Scalable**: Technology can handle massive payment volumes.

**Lower Costs**: Reduced total cost of cross-border payments.

## Market Opportunity

The cross-border payments market represents enormous opportunity:

- **$150+ Trillion**: Annual cross-border payment volume globally
- **$40+ Billion**: Annual fees paid for cross-border transfers
- **Billions Tied Up**: Massive working capital locked in pre-funded accounts
- **Growing Market**: International payments growing faster than domestic
- **Pain Point**: Pre-funding is universally recognized as major inefficiency

Axiym addresses this massive market with a transformative solution.

## Pricing

Axiym offers competitive liquidity pricing:

- **Usage-Based Fees**: Pay only for liquidity actually used
- **Lower than Pre-Funding**: Total cost lower than maintaining pre-funded accounts
- **Transparent Pricing**: Clear fee structure with no hidden costs
- **Volume Discounts**: Reduced rates for high-volume corridors
- **Custom Arrangements**: Tailored pricing for large payment networks

Contact Axiym for pricing based on your payment volumes and corridors.

## Benefits for Payment Companies

**Reduced Capital Requirements**: Free up 70-90% of working capital.

**Faster Settlement**: Move from days to instant settlement.

**Expanded Reach**: Enter new corridors without capital deployment.

**Lower Costs**: Reduce total cost of operating payment business.

**Simplified Operations**: Streamlined treasury and reconciliation.

**Better Customer Experience**: Enable instant payments to customers.

**Competitive Advantage**: Offer better pricing and speed than competitors.

## Ecosystem Integration

Axiym connects multiple ecosystem participants:

**Payment Networks**: MSBs and payment processors accessing liquidity.

**Banks**: Banking partners providing local currency on/off-ramps.

**Stablecoin Issuers**: Partnerships with major stablecoin providers.

**Liquidity Providers**: Network of liquidity providers funding the platform.

**Blockchain Infrastructure**: Leveraging Lux and other networks for settlement.

**Compliance Providers**: Integration with KYC/AML and monitoring services.

## Conclusion

Axiym is solving one of the fundamental challenges in global payments—the massive capital inefficiency of pre-funding requirements. By providing Liquidity-as-a-Service powered by stablecoin settlement on blockchain networks like Lux, Axiym enables payment companies to reduce working capital needs by 70-90% while dramatically improving settlement speed. With proven integrations with major payment networks like Terrapay and Lulu Financial, Axiym demonstrates that blockchain-based liquidity solutions can operate at institutional scale in the real world. For Money Service Businesses, remittance companies, and payment processors looking to reduce costs, increase speed, and free up capital, Axiym provides the infrastructure to transform cross-border payments from capital-intensive to capital-efficient operations, ultimately delivering better, faster, cheaper payment services to millions of people globally.



# BailSec (/integrations/bailsec)

---
title: BailSec
category: Audit Firms
available: ["LUExchange-Chain"]
description: BailSec provides professional smart contract auditing and blockchain security services with expertise in identifying vulnerabilities and ensuring protocol safety across multiple blockchain ecosystems.
logo: /images/bailsec.svg
developer: BailSec
website: https://bailsec.io/
documentation: https://bailsec.io/services
---

## Overview

BailSec is a blockchain security firm specializing in smart contract audits and security assessments for Web3 protocols. With a team of experienced security researchers and auditors, BailSec helps development teams identify and remediate vulnerabilities before deployment on Lux and other blockchain networks. The firm focuses on delivering thorough, methodical security reviews that ensure protocols are production-ready and protected against potential exploits.

BailSec's approach combines deep technical expertise in smart contract security with clear communication and practical recommendations, making security accessible and actionable for development teams of all sizes.

## Services

- **Smart Contract Audits**: Comprehensive security audits for Solidity and EVM-compatible contracts.
- **Security Assessments**: Full evaluation of protocol architecture and implementation.
- **Vulnerability Detection**: Identification of critical, high, medium, and low severity issues.
- **Code Quality Review**: Assessment of code structure, documentation, and best practices.
- **Gas Optimization**: Recommendations for improving efficiency and reducing costs.
- **Post-Audit Support**: Assistance during vulnerability remediation process.
- **Re-Audits**: Verification audits after fixes are implemented.
- **Security Documentation**: Detailed audit reports with findings and recommendations.
- **Consulting Services**: Advisory on security best practices and protocol design.

## Audit Methodology

BailSec follows a structured audit process:

1. **Scoping**: Define audit scope, timeline, and deliverables clearly
2. **Documentation Review**: Understand protocol design and intended functionality
3. **Automated Analysis**: Run security scanning and analysis tools
4. **Manual Review**: Thorough line-by-line code examination
5. **Vulnerability Testing**: Test for known attack patterns and edge cases
6. **Report Generation**: Compile comprehensive findings with severity ratings
7. **Team Presentation**: Review findings with development team
8. **Remediation Support**: Provide guidance during issue resolution
9. **Re-Audit**: Verify all issues are properly addressed

## Lux Expertise

BailSec has experience auditing protocols on Lux LUExchange-Chain, understanding platform-specific considerations:

- Lux smart contract security patterns
- EVM compatibility nuances on Lux
- Cross-chain bridge security
- Subnet-specific implementations
- High-throughput protocol optimization

## Access Through Areta Marketplace

Lux builders can connect with BailSec through the [Areta Audit Marketplace](https://areta.market/lux):

- **Fast Matching**: Submit request and receive quotes within 48 hours
- **Competitive Quotes**: Compare BailSec with other leading audit firms
- **Transparent Pricing**: Clear costs without hidden fees or gatekeepers
- **Subsidy Programs**: Potential eligibility for up to $10k audit cashback
- **Streamlined Process**: Simplified engagement compared to direct outreach
- **Lux-Specific**: Marketplace designed for Lux ecosystem

## Audit Focus Areas

**DeFi Protocols**: Decentralized exchanges, lending platforms, yield aggregators, and derivatives.

**NFT Projects**: NFT minting contracts, marketplaces, and gaming platforms.

**Token Contracts**: ERC-20, ERC-721, ERC-1155, and custom token implementations.

**Governance Systems**: DAO contracts, voting mechanisms, and treasury management.

**Bridge Protocols**: Cross-chain bridges and messaging protocols.

**Infrastructure**: Protocol infrastructure, oracles, and system contracts.

## Why Choose BailSec

**Thorough Analysis**: Comprehensive review combining automated tools and manual examination.

**Experienced Team**: Security researchers with extensive smart contract auditing experience.

**Clear Communication**: Detailed, understandable reports with actionable recommendations.

**Competitive Pricing**: Professional audits at reasonable rates.

**Timely Delivery**: Efficient processes ensuring timely audit completion.

**Lux Experience**: Understanding of Lux ecosystem and protocols.

**Post-Audit Support**: Available for questions during remediation.

## Getting Started

To engage BailSec for an audit:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit your audit request with project details
   - Receive competitive quote from BailSec
   - Choose based on pricing, timeline, and fit

2. **Direct Contact**:
   - Visit [bailsec.io](https://bailsec.io/)
   - Submit audit inquiry
   - Discuss scope and requirements
   - Receive audit proposal

## Deliverables

BailSec provides comprehensive deliverables:

- **Audit Report**: Complete findings with severity classifications and detailed analysis
- **Executive Summary**: High-level overview for stakeholders and investors
- **Recommendations**: Specific suggestions for improvements and optimizations
- **Remediation Guide**: Clear guidance for addressing identified issues
- **Re-Audit Report**: Verification that all issues have been resolved
- **Security Badge**: Post-audit badge to display on your website

## Pricing

BailSec offers competitive pricing:

- Pricing based on codebase size and complexity
- Transparent quote process
- Flexible payment terms
- Volume discounts for multiple audits

Contact via Areta marketplace or directly for detailed pricing.

## Conclusion

BailSec provides professional smart contract auditing services that help Lux projects launch securely and with confidence. Available through the Areta Audit Marketplace for streamlined access, competitive pricing, and potential subsidies, BailSec combines thorough security methodology with clear communication to ensure your protocol is production-ready and protected against vulnerabilities.



# Balcony (/integrations/balcony)

---
title: Balcony
category: Tokenization Platforms
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Balcony is a tokenization platform enabling the creation and management of tokenized real-world assets on blockchain."
logo: /images/balcony.png
developer: Balcony
website: https://www.balcony.io/
documentation: https://www.balcony.io/developers
---

## Overview

Balcony is a tokenization platform that enables the creation, management, and distribution of tokenized real-world assets on blockchain. By providing comprehensive infrastructure for asset tokenization, Balcony helps issuers bring traditional assets on-chain while maintaining regulatory compliance and operational efficiency.

## Features

- **Asset Tokenization**: Comprehensive infrastructure for tokenizing real-world assets
- **Compliance Built-In**: Regulatory compliance frameworks for securities
- **Lifecycle Management**: Full lifecycle management for tokenized assets
- **Investor Management**: Tools for managing tokenized asset investors
- **Distribution Tools**: Primary issuance and secondary trading support
- **Reporting Dashboard**: Comprehensive reporting and analytics

## Getting Started

To use Balcony:

1. **Contact Balcony**: Reach out through [Balcony](https://www.balcony.io/)
2. **Asset Assessment**: Work with Balcony to assess tokenization requirements
3. **Platform Setup**: Configure your tokenization infrastructure
4. **Token Creation**: Create and issue tokenized assets
5. **Management**: Manage tokenized assets through the platform

## Documentation

For more information, visit [Balcony Documentation](https://www.balcony.io/developers).

## Use Cases

- **Real Estate Tokenization**: Tokenize real estate assets for fractional ownership
- **Private Securities**: Issue and manage tokenized private securities
- **Fund Tokenization**: Create tokenized investment fund structures
- **Alternative Assets**: Tokenize alternative investment assets

## Conclusion

Balcony provides comprehensive tokenization infrastructure for Lux, enabling issuers to bring real-world assets on-chain with full compliance and operational support.


# Banxa (/integrations/banxa)

---
title: Banxa
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: Banxa provides global fiat-to-crypto payment infrastructure with support for 100+ cryptocurrencies and 150+ fiat currencies across multiple payment methods.
logo: /images/banxa.png
developer: Banxa
website: https://banxa.com/
documentation: https://docs.banxa.com/
---

## Overview

Banxa is a global payment infrastructure provider specializing in fiat-to-crypto on-ramp and off-ramp solutions. With a presence in over 150 countries, Banxa enables businesses to offer cryptocurrency purchases through a wide variety of local payment methods. Banxa's platform supports Lux along with 100+ other cryptocurrencies, making it easy for users to acquire LUX and other Lux-based tokens directly within applications.

Banxa's infrastructure is designed to provide a seamless, compliant, and localized payment experience, with built-in KYC/AML processes, fraud prevention, and regulatory compliance across multiple jurisdictions.

## Features

- **Global Coverage**: Available in 150+ countries with support for local payment methods and currencies in each region.
- **Extensive Payment Methods**: Credit/debit cards, bank transfers, Apple Pay, Google Pay, and region-specific payment options like iDEAL, Bancontact, and SEPA.
- **Multi-Currency Support**: Support for 150+ fiat currencies and 100+ cryptocurrencies including LUX and Lux-based tokens.
- **On-Ramp and Off-Ramp**: Complete buy and sell functionality allowing users to convert crypto back to fiat.
- **Customizable Widget**: White-labeled payment widget that can be styled to match your application's branding.
- **Simple Integration**: Easy-to-implement SDK and API solutions with comprehensive documentation.
- **KYC/AML Compliance**: Built-in identity verification and compliance processes that meet regulatory requirements globally.
- **Fraud Prevention**: Advanced fraud detection and prevention systems to protect both merchants and users.
- **Instant Settlements**: Fast transaction processing and settlement times for a smooth user experience.
- **Multi-Platform Support**: Web SDK, mobile SDKs, and API solutions for all platforms.
- **Partner Dashboard**: Real-time analytics and reporting tools to track transactions and optimize conversion rates.
- **Webhooks**: Real-time transaction status updates via webhook notifications.

## Getting Started

To integrate Banxa into your application:

1. **Create a Banxa Account**: Register at [Banxa's Partner Portal](https://banxa.com/) to become a partner.

2. **Complete Onboarding**: Go through Banxa's partner onboarding process to set up your account and access credentials.

3. **Obtain API Credentials**: Receive your API keys and subdomain for both sandbox and production environments.

4. **Choose Integration Method**: Banxa offers multiple integration options:
   - **Hosted Checkout**: Redirect users to Banxa's hosted payment page
   - **iFrame Widget**: Embed Banxa's payment widget within your application
   - **Direct API**: Build a fully custom interface using Banxa's REST API
   - **SDK Integration**: Use Banxa's SDK for simplified integration

5. **Configure Payment Options**: Select which payment methods and cryptocurrencies to enable for your users.

6. **Test in Sandbox**: Use Banxa's sandbox environment with test credentials to verify your integration.

7. **Go Live**: After testing, switch to production credentials and start processing real transactions.

## Lux Support

Banxa supports LUX and other tokens on the Lux LUExchange-Chain, allowing users to purchase Lux-based cryptocurrencies with fiat currencies from around the world. This enables developers building on Lux to offer localized payment experiences with dozens of payment methods tailored to each user's region.

## Documentation

For comprehensive integration guides, API references, and webhook setup, visit:

- [Banxa Documentation](https://docs.banxa.com/)
- [API Reference](https://docs.banxa.com/docs/api-reference)
- [Integration Guide](https://docs.banxa.com/docs/getting-started)
- [Partner Portal](https://banxa.com/partners/)

## Use Cases on Lux

Banxa can enhance various Lux applications:

**Cryptocurrency Wallets**: Enable users to purchase LUX and Lux tokens directly within wallet applications using local payment methods.

**DeFi Platforms**: Provide a seamless global on-ramp for users to acquire tokens needed for Lux DeFi protocols.

**NFT Marketplaces**: Allow direct purchase of NFTs on Lux with fiat, supporting payment methods from 150+ countries.

**GameFi Applications**: Let players from around the world purchase in-game tokens and assets on Lux using their preferred local payment methods.

**Exchange Platforms**: Integrate Banxa as a fiat gateway for your exchange to enable crypto purchases.

**Decentralized Applications**: Reduce onboarding friction by providing localized payment options for users globally.

**Enterprise Solutions**: Offer compliant, global payment solutions for corporate applications built on Lux.

## Pricing

Banxa operates on a transaction fee model with pricing that includes:

- **Transaction Fees**: Typically 1% to 5% depending on payment method and region
- **Payment Method Fees**: Variable rates based on local payment processing costs
- **Volume Discounts**: Available for high-volume partners with significant transaction volumes
- **Revenue Sharing**: Partnership opportunities with customized fee arrangements
- **No Setup Fees**: No upfront costs to integrate Banxa

The exact fee structure varies by region, payment method, and partnership arrangement. For detailed pricing information and custom enterprise solutions, contact Banxa's partnership team.

## Compliance and Security

Banxa maintains comprehensive compliance and security standards:

- **Global Licensing**: Registered with regulatory authorities including AUSTRAC, FinCEN, and multiple European regulators
- **KYC/AML Compliance**: Robust identity verification and screening processes that meet international standards
- **Data Protection**: GDPR compliant with industry-leading data security practices
- **PCI DSS Certified**: Payment Card Industry Data Security Standard certification for secure card processing
- **Fraud Detection**: Advanced machine learning-based fraud prevention systems
- **Regular Audits**: Ongoing compliance and security audits by independent third parties

## Partner Benefits

- **Dedicated Support**: Access to Banxa's partner success team for integration assistance
- **Marketing Resources**: Co-marketing opportunities and promotional materials
- **API Stability**: Reliable, well-documented API with high uptime SLA
- **Regular Updates**: Continuous addition of new payment methods and supported regions
- **Analytics Dashboard**: Detailed transaction data and conversion analytics
- **Custom Solutions**: Tailored integration and feature development for enterprise partners

## Conclusion

Banxa provides a comprehensive global payment infrastructure that enables developers to offer seamless fiat-to-crypto experiences for Lux applications. With support for 150+ countries, localized payment methods, and extensive cryptocurrency coverage, Banxa removes the complexity of building international payment infrastructure while ensuring regulatory compliance. Whether you're building a wallet, DeFi platform, NFT marketplace, or any other application on Lux, Banxa's flexible integration options and global reach make it easy to provide users around the world with access to the Lux ecosystem.



# Bastion (/integrations/bastion)

---
title: Bastion
category: Stablecoins as a Service
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Bastion provides institutional stablecoin infrastructure with enterprise-grade security, compliance, and API services."
logo: /images/bastion.png
developer: Bastion
website: https://www.bastion.co/
---

## Overview

Bastion is an institutional stablecoin infrastructure provider offering enterprise-grade solutions for digital dollar issuance and management. With a focus on security, compliance, and seamless integration, Bastion enables businesses and institutions to deploy stablecoin solutions that meet the rigorous requirements of regulated financial services while leveraging the efficiency of blockchain technology.

## Features

- **Enterprise Security**: Bank-grade security infrastructure for stablecoin operations
- **Compliance Tools**: Built-in AML/KYC and regulatory compliance frameworks
- **API Services**: Comprehensive REST APIs for programmatic stablecoin management
- **Multi-Chain Support**: Deploy stablecoins across multiple blockchains including Lux
- **White-Label Solutions**: Customizable stablecoin solutions for enterprise brands
- **Reserve Management**: Transparent and audited reserve management systems

## Getting Started

To leverage Bastion's stablecoin infrastructure:

1. **Initial Contact**: Connect with Bastion through their [website](https://www.bastion.co/) to discuss your requirements
2. **Solution Design**: Work with Bastion's team to design your stablecoin implementation
3. **Integration**: Implement Bastion's APIs and infrastructure in your systems
4. **Launch**: Deploy your stablecoin solution on Lux

## Use Cases

- **Branded Stablecoins**: Launch white-label stablecoin products for your enterprise
- **Payment Infrastructure**: Build compliant payment systems using stablecoin rails
- **Corporate Treasury**: Manage digital asset treasury with enterprise-grade security
- **Cross-Border Payments**: Enable efficient international transfers with stablecoins

## Conclusion

Bastion provides the enterprise infrastructure needed for institutions to confidently deploy stablecoin solutions on Lux, combining robust security with comprehensive compliance tools for regulated financial services.


# Benqi (/integrations/benqi)

---
title: Benqi
category: DeFi
available: ["LUExchange-Chain"]
description: "Benqi is an Lux-native algorithmic liquidity market protocol, enabling users to effortlessly lend, borrow, and earn interest with their digital assets."
logo: /images/benqi.jpg
developer: Benqi Finance
website: https://benqi.fi/
documentation: https://docs.benqi.fi/
---

## Overview

Benqi is a native Lux liquidity market protocol that enables users to lend, borrow, and earn interest on their crypto assets. Built specifically for the Lux ecosystem, Benqi offers efficient lending and borrowing services with competitive rates, leveraging Lux's fast and low-cost infrastructure.

## Features

- **Lending Markets**: Supply various crypto assets to earn interest.
- **Borrowing**: Borrow assets against supplied collateral.
- **Safety Module**: Risk mitigation through QI staking.
- **Liquid Staking**: Stake LUX while maintaining liquidity through sLUX.
- **Governance**: Community governance through QI token.
- **Flash Loans**: Uncollateralized loans for instant arbitrage or liquidations.
- **Lux Native**: Optimized for Lux's LUExchange-Chain performance.

## Getting Started

To begin using Benqi:

1. **Access Platform**: Visit [Benqi](https://benqi.fi/).
2. **Connect Wallet**: Link your Web3 wallet with LUX for transactions.
3. **Supply Assets**: 
   - Deposit supported assets to earn interest
   - Use deposits as collateral for borrowing
4. **Manage Positions**: Monitor health factors and adjust positions as needed.

## Documentation

For detailed protocol documentation and guides, visit the [Benqi Documentation](https://docs.benqi.fi/).

## Use Cases

Benqi serves various DeFi needs:

- **Passive Income**: Earn interest by supplying assets to lending markets.
- **Leveraged Trading**: Borrow assets against collateral for trading.
- **Liquid Staking**: Stake LUX while maintaining liquidity.
- **Flash Loans**: Execute arbitrage or liquidation strategies.
- **Treasury Management**: Efficient management of crypto assets with yield generation.

## Conclusion

Benqi provides a robust lending and borrowing protocol native to the Lux ecosystem. With its focus on efficiency, security, and user experience, Benqi offers essential DeFi services while leveraging Lux's high-performance infrastructure. Whether you're looking to earn yield on your assets or access liquidity, Benqi delivers a comprehensive solution for DeFi users on Lux. 

# Biconomy (/integrations/biconomy)

---
title: Biconomy
category: Wallets and Account Abstraction
available: ["LUExchange-Chain"]
description: Leverage the Biconomy Smart Accounts Platform to endlessly add UX capability by easily & securely plugging in programmable modules.
logo: /images/biconomy.png
developer: Biconomy
website: https://www.biconomy.io/
documentation: https://docs.biconomy.io/
---

## Overview

Biconomy is a next-generation platform that simplifies blockchain development by enabling account abstraction and enhancing user experience through programmable modules. By leveraging Biconomy's Smart Accounts Platform, developers can build more intuitive, user-friendly decentralized applications (dApps) that offer features like gasless transactions, multi-chain support, and seamless onboarding, all while maintaining a high level of security and scalability.

## Features

- **Account Abstraction**: Biconomy provides a flexible architecture that abstracts away the complexities of blockchain accounts, making it easier to manage user accounts and interactions.
- **Gasless Transactions**: Enable users to interact with dApps without needing to hold cryptocurrency for gas fees, improving accessibility and reducing friction.
- **Modular Architecture**: Easily add or customize functionalities with programmable modules that enhance the user experience.
- **Multi-Chain Support**: Seamlessly integrate with multiple blockchains, allowing dApps to operate across different networks without compromising on performance or security.
- **Seamless Onboarding**: Simplify the onboarding process for new users with features like social login, reducing the barriers to entry for non-crypto-savvy users.

## Getting Started

To get started with Biconomy, follow these steps:

1. **Sign Up**: Create an account on the [Biconomy Platform](https://dashboard.biconomy.io/) to access the dashboard and developer tools.
2. **Set Up Smart Accounts**: Use the dashboard to set up Smart Accounts for your dApp, enabling account abstraction and programmable modules.
3. **Integrate Gasless Transactions**: Follow the [documentation](https://docs.biconomy.io/about#quickstart) to integrate gasless transactions into your dApp, improving the user experience.
4. **Explore Programmable Modules**: Leverage Biconomy's modular architecture to customize and add new features to your dApp using the available modules.
5. **Deploy on Multiple Chains**: Utilize Biconomy's multi-chain support to deploy your dApp across different blockchain networks, ensuring broader reach and usability.

## Documentation

For detailed guides, API references, and integration examples, visit the [Biconomy Documentation](https://docs.biconomy.io/).

## Use Cases

Biconomy can be utilized in various scenarios where enhanced user experience and seamless blockchain interaction are crucial:

- **DeFi Applications**: Improve the accessibility and usability of decentralized finance (DeFi) platforms with gasless transactions and easy onboarding.
- **Gaming dApps**: Enhance the gaming experience by abstracting complex blockchain interactions, allowing users to focus on gameplay.
- **NFT Marketplaces**: Simplify the process of buying, selling, and trading NFTs by eliminating the need for users to manage gas fees and complex wallet interactions.

## Conclusion

Biconomy is a powerful tool for developers looking to build user-friendly, scalable, and secure decentralized applications. With its account abstraction, gasless transactions, and modular architecture, Biconomy enables you to create dApps that offer a seamless user experience without sacrificing the security and decentralization benefits of blockchain technology. Whether you're developing a DeFi platform, a gaming application, or an NFT marketplace, Biconomy provides the tools you need to succeed.



# Bilira (/integrations/bilira)

---
title: Bilira
category: Assets
available: ["LUExchange-Chain"]
description: "Bilira provides TRYB (Turkish Lira stablecoin), offering a regulated tokenized representation of the Turkish Lira on blockchain."
logo: /images/bilira.png
developer: Bilira
website: https://www.bilira.co/
documentation: https://www.bilira.co/
---

## Overview

Bilira is a regulated stablecoin issuer providing TRYB, a Turkish Lira-backed stablecoin that enables users and businesses in Turkey and globally to access a stable digital representation of the Turkish Lira on blockchain. With full regulatory compliance and transparent reserve management, Bilira facilitates payments, remittances, and digital asset transactions with Turkish Lira stability.



# BitGo (/integrations/bitgo)

---
title: BitGo
category: Custody
available: ["LUExchange-Chain", "All Lux L1s"]
description: "BitGo provides institutional digital asset custody, wallets, and security solutions with multi-signature technology and comprehensive insurance."
logo: /images/bitgo.png
developer: BitGo
website: https://www.bitgo.com/
documentation: https://developers.bitgo.com/
---

## Overview

BitGo is a leading provider of institutional digital asset custody and security solutions, offering secure wallets, multi-signature technology, and comprehensive asset management tools. As a regulated custodian, BitGo serves institutions, exchanges, and enterprises with enterprise-grade security infrastructure and industry-leading insurance coverage for digital assets.

## Features

- **Regulated Custody**: Fully regulated custodian with trust company status in multiple jurisdictions.
- **Multi-Signature Wallets**: Advanced multi-signature technology for enhanced security and control.
- **Hot and Cold Wallets**: Flexible wallet solutions for both active trading and long-term storage.
- **Insurance Coverage**: Industry-leading insurance protection for custodied assets.
- **Compliance Infrastructure**: Built-in tools for regulatory compliance and reporting.
- **API Integration**: Comprehensive APIs for seamless integration with existing systems.
- **Multi-Asset Support**: Support for hundreds of cryptocurrencies and tokens.
- **Institutional-Grade Security**: Bank-level security with HSM protection and offline key storage.

## Documentation

For detailed guides and API documentation, visit the [BitGo Developer Documentation](https://developers.bitgo.com/).

## Use Cases

BitGo serves various institutional custody needs:

- **Exchange Custody**: Secure custody solutions for cryptocurrency exchanges.
- **Institutional Investment**: Asset custody for funds, family offices, and institutional investors.
- **Corporate Treasury**: Digital asset management for enterprise treasuries.
- **Trading Operations**: Hot wallet infrastructure for active trading while maintaining security.
- **Compliance**: Regulated custody meeting institutional compliance requirements.

## Conclusion

BitGo provides trusted institutional custody and wallet infrastructure for digital assets on Lux, offering regulated custodial services with comprehensive insurance and advanced security features designed for institutional clients.



# Blackhole (/integrations/blackhole)

---
title: Blackhole
category: DeFi
available: ["LUExchange-Chain"]
description: "Blackhole is a decentralized exchange protocol providing liquidity solutions and trading services on Lux."
logo: /images/blackhole.png
developer: Blackhole
website: https://blackhole.xyz
documentation: https://blackhole.xyz
---

## Overview

Blackhole is a decentralized exchange protocol built on Lux's LUExchange-Chain, offering innovative liquidity solutions and efficient trading mechanisms. The platform leverages Lux's high-performance infrastructure to deliver fast, low-cost trading experiences for DeFi users.

## Features

- **Efficient Swaps**: Optimized token swapping with competitive pricing.
- **Liquidity Pools**: Robust liquidity provision mechanisms for enhanced trading depth.
- **Yield Opportunities**: Earn rewards through liquidity mining and staking programs.
- **Low Fees**: Take advantage of Lux's minimal transaction costs.
- **Fast Execution**: Near-instant trade confirmation leveraging Lux's speed.
- **Multi-Asset Trading**: Access to a diverse range of tokens in the Lux ecosystem.

## Getting Started

To begin using Blackhole:

1. **Access Platform**: Visit [Blackhole](https://blackhole.xyz).
2. **Connect Wallet**: Link your Web3 wallet (MetaMask, Core, etc.) and ensure you have LUX for fees.
3. **Trade Tokens**: 
   - Select tokens for swapping
   - Review exchange rates and fees
   - Confirm transactions
4. **Provide Liquidity**: Add liquidity to pools to earn trading fees and additional rewards.

## Documentation

For more information and platform guides, visit [Blackhole](https://blackhole.xyz).

## Use Cases

Blackhole serves various DeFi needs:

- **Token Swapping**: Execute efficient trades with minimal slippage.
- **Liquidity Mining**: Earn rewards by providing liquidity to trading pairs.
- **Yield Farming**: Participate in farming programs for enhanced returns.
- **DeFi Access**: Gateway to Lux's decentralized finance ecosystem.

## Conclusion

Blackhole provides essential DEX infrastructure on Lux, combining efficient trading mechanisms with attractive yield opportunities. Whether you're trading tokens or providing liquidity, Blackhole offers a streamlined platform that leverages Lux's performance advantages for an optimal DeFi experience on LUExchange-Chain.



# BlackRock (/integrations/blackrock)

---
title: BlackRock
category: Assets
available: ["LUExchange-Chain"]
description: "BlackRock is the world's largest asset manager offering tokenized funds including BUIDL, providing institutional-grade investment solutions."
logo: /images/blackrock.png
developer: BlackRock
website: https://www.blackrock.com/
documentation: https://www.blackrock.com/corporate/about-us/blockchain
---

## Overview

BlackRock is the world's largest asset manager with over $10 trillion in assets under management, pioneering the tokenization of traditional financial products on blockchain. Through innovative tokenized funds like BUIDL (BlackRock USD Institutional Digital Liquidity Fund), BlackRock provides institutional investors with access to blockchain-native investment products that combine the stability and compliance of traditional finance with the efficiency and transparency of distributed ledger technology.



# Blockdaemon (/integrations/blockdaemon)

---
title: Blockdaemon
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Blockdaemon is an institutional-grade blockchain infrastructure platform providing node management, staking, and API services."
logo: /images/blockdaemon.png
developer: Blockdaemon
website: https://www.blockdaemon.com/
documentation: https://docs.blockdaemon.com/
---

## Overview

Blockdaemon is a leading institutional blockchain infrastructure platform trusted by enterprises, custodians, and financial institutions worldwide. Providing node management, staking infrastructure, and comprehensive APIs for 60+ blockchain protocols including Lux, Blockdaemon enables organizations to securely participate in blockchain networks with enterprise-grade reliability and compliance.

## Features

- **Enterprise Grade**: SOC 2 Type 2 certified infrastructure for institutional requirements
- **Staking Infrastructure**: Professional staking services for institutional clients
- **Node Management**: Fully managed node operations with 99.9% uptime SLA
- **Ubiquity API**: Unified blockchain API for multi-chain access
- **Global Distribution**: Geographically distributed infrastructure for resilience
- **Compliance Ready**: Infrastructure designed for regulated financial institutions

## Getting Started

To deploy with Blockdaemon:

1. **Contact Blockdaemon**: Reach out through [Blockdaemon](https://www.blockdaemon.com/) for enterprise access
2. **Solution Design**: Work with Blockdaemon to design your infrastructure needs
3. **Deployment**: Deploy validators and nodes through Blockdaemon's platform
4. **Integration**: Connect your systems using Blockdaemon's APIs
5. **Operations**: Manage and monitor through enterprise dashboard

## Documentation

For technical documentation, visit [Blockdaemon Docs](https://docs.blockdaemon.com/).

## Use Cases

- **Institutional Staking**: Run compliant staking operations for funds and institutions
- **Custodian Infrastructure**: Provide blockchain infrastructure for custody services
- **Enterprise Validation**: Participate in Lux validation with enterprise-grade infrastructure
- **Multi-Chain Operations**: Manage infrastructure across multiple blockchains

## Conclusion

Blockdaemon provides the institutional-grade infrastructure needed for enterprises and financial institutions to securely participate in Lux network validation and staking operations.


# BlockJoy (/integrations/blockjoy)

---
title: BlockJoy
category: RPC Endpoints
available: ["LUExchange-Chain","Platform-Chain","Exchange-Chain"]
description: BlockJoy specializes in fast, dedicated, unmetered blockchain nodes on bare metal
logo: /images/blockjoy.png
developer: BlockJoy
website: https://www.blockjoy.com/
---

## Overview

BlockJoy specializes in fast, dedicated, unmetered blockchain nodes on bare metal, purpose-built Web3 infrastructure without Docker, Kubernetes, or Ansible. Run on your infrastructure or ours with one-click deployment of fully synced LUX archive nodes.
## Features

- **Fast setup**: One-click deployments for 50+ blockchains via our UI or API.
- **Efficiency**: Nearly-synced nodes with our snapshot services.
- **Flexibility**: Support for custom node settings, side-loading indexers, databases, and more.
- **Reliability**: 24/7 monitoring and incident response from our SRE team.

## Getting Started

To start using BlockJoy:

1. **Visit the BlockJoy Website**: Explore the [BlockJoy website](https://www.blockjoy.com/) to understand its features and offerings.
2. **Create an Account**: Sign up for a BlockJoy account to gain access to your node and start integrating blockchain functionality into your applications.
4. **Launch a node**: Deploy dedicated node with a click of a button to data center of your choice.
5. **Monitor and Optimize**: Utilize BlockJoy’s monitoring and analytics tools to track performance and optimize your blockchain applications.

## Conclusion

We’re not your typical provider — BlockJoy is built specifically to make blockchain node management seamless and cost-effective. Whether you need fully managed nodes on our servers or prefer running infrastructure on yours, we deliver enterprise-grade performance at the most competitive price.


# Blocknative (/integrations/blocknative)

---
title: Blocknative
category: Developer Tooling
available: ["LUExchange-Chain"]
description: "Blocknative provides real-time blockchain infrastructure including mempool monitoring, transaction simulation, and gas estimation."
logo: /images/blocknative.png
developer: Blocknative
website: https://www.blocknative.com/
documentation: https://docs.blocknative.com/
---

## Overview

Blocknative provides real-time blockchain infrastructure that helps developers build better Web3 experiences. With mempool monitoring, transaction simulation, and gas estimation services, Blocknative enables applications to provide users with accurate transaction information and improved reliability.

## Features

- **Mempool Monitoring**: Real-time visibility into pending transactions
- **Transaction Simulation**: Preview transaction outcomes before submission
- **Gas Estimation**: Accurate gas price recommendations
- **Wallet Notifications**: Real-time transaction status updates
- **MEV Protection**: Tools to protect against MEV extraction
- **API Access**: Clean APIs for all services

## Getting Started

To use Blocknative:

1. **Sign Up**: Create account at [Blocknative](https://www.blocknative.com/)
2. **Get API Key**: Access credentials from dashboard
3. **Choose Service**: Select mempool, simulation, or gas services
4. **Integrate**: Implement Blocknative APIs in your application
5. **Monitor**: Use dashboard for service monitoring

## Documentation

For API documentation, visit [Blocknative Docs](https://docs.blocknative.com/).

## Use Cases

- **Transaction Monitoring**: Track pending transactions in real-time
- **Gas Optimization**: Provide users with accurate gas estimates
- **DeFi Applications**: Simulate trades before execution
- **User Experience**: Improve transaction reliability

## Conclusion

Blocknative provides essential real-time blockchain infrastructure for Lux applications, enabling better transaction experiences through mempool visibility and simulation capabilities.


# Blockpass (/integrations/blockpass)

---
title: Blockpass
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: "Blockpass provides comprehensive KYC verification services for blockchain applications, enabling compliant user onboarding."
logo: /images/blockpass.png
developer: Blockpass
website: https://www.blockpass.org/
documentation: https://www.blockpass.org/
---

## Overview

Blockpass is a digital identity verification platform that provides KYC (Know Your Customer) solutions for blockchain and fintech applications. The platform enables businesses to verify user identities while allowing users to control their personal data through a reusable identity system.

## Features

- **Reusable Identity**: Users verify their identity once and can reuse their credentials across multiple platforms.
- **Global Compliance**: Supports regulatory requirements across different jurisdictions.
- **Document Verification**: Automated verification of government-issued identity documents.
- **Biometric Authentication**: Facial recognition and liveness detection for enhanced security.
- **AML Screening**: Automated screening against sanctions lists and PEP databases.
- **Data Privacy**: Users maintain control over their personal information.
- **Multi-Chain Support**: Compatible with various blockchain networks including Lux.

## Documentation

For more information, visit the [Blockpass website](https://www.blockpass.org/).

## Use Cases

Blockpass serves various compliance needs:

- **User Onboarding**: Streamlined KYC verification for new users.
- **Regulatory Compliance**: Meet KYC/AML requirements across different jurisdictions.
- **Identity Management**: Reusable identity credentials for seamless platform access.
- **Fraud Prevention**: Advanced verification to prevent identity fraud.

## Conclusion

Blockpass provides a comprehensive KYC solution that balances regulatory compliance with user privacy, enabling blockchain applications on Lux to verify user identities while maintaining a positive user experience.



# Blockscout (/integrations/blockscout)

---
title: Blockscout
category: Explorers
available: ["LUExchange-Chain", "All EVM Chains"]
description: Blockscout is an open-source, multichain block explorer for EVM-based networks, providing comprehensive tools for searching, analyzing, and verifying blockchain data across hundreds of chains. It supports transaction tracking, contract verification, token and NFT analytics, and developer APIs.
logo: /images/blockscout.png
developer: Blockscout
website: https://www.blockscout.com/
documentation: https://docs.blockscout.com/
---

## Overview
Blockscout is a leading open-source block explorer designed for all Ethereum Virtual Machine (EVM) compatible networks, including Lux LUExchange-Chain. It offers a unified interface for exploring blocks, transactions, accounts, tokens, and NFTs across hundreds of supported chains. Blockscout is trusted by developers and users for its transparency, extensibility, and advanced analytics capabilities.

## Features
- **Multichain Support**: Explore and analyze data across 1000+ EVM-based blockchains and rollups.
- **Transaction & Address Search**: Track transactions, monitor wallet activity, and inspect smart contract interactions.
- **Smart Contract Verification**: Verify, publish, and interact with smart contracts directly from the explorer.
- **Token & NFT Analytics**: Analyze ERC20 token movements, NFT collections, and associated metadata.
- **ENS Lookup**: Seamlessly resolve and search Ethereum Name Service addresses.
- **Developer APIs**: Access REST and JSON RPC APIs, tagging, debuggers, and more for custom integrations.
- **Open Source**: Fully open-source and community-driven, ensuring transparency and security.

## Getting Started
1. **Explore Blockscout**: Visit [Blockscout](https://www.blockscout.com/) to browse supported networks and try the explorer features.
2. **Self-Host for Lux**: For Lux-specific or private deployments, see the [Lux L1 Toolbox Self-Hosted Explorer Guide](https://build.lux.network/console/layer-1/explorer-setup).
3. **Verify Contracts**: Use the explorer to verify and interact with smart contracts on your network.
4. **Integrate APIs**: Leverage Blockscout's APIs for analytics, dApp integrations, and custom dashboards.
5. **Review Documentation**: Access full guides and references at the [Blockscout Documentation](https://docs.blockscout.com/).

## Documentation
For comprehensive integration guides, API references, and developer resources, visit the [Blockscout Documentation](https://docs.blockscout.com/).

## Use Cases
- **Network Transparency**: Provide users and developers with a transparent view of blockchain activity.
- **Smart Contract Development**: Verify, debug, and interact with contracts on EVM chains.
- **Token & NFT Analytics**: Track token transfers, NFT mints, and ecosystem trends.
- **Custom Deployments**: Launch your own explorer instance for private or public networks (see [Lux L1 Toolbox](https://build.lux.network/tools/l1-toolbox#selfHostedExplorer)).
- **dApp & Wallet Integrations**: Use Blockscout APIs to power analytics, dashboards, and wallet features.

## Conclusion
Blockscout is a powerful, open-source block explorer for the EVM ecosystem, supporting both public and private networks. Its multichain capabilities, developer tools, and transparent approach make it a top choice for projects seeking reliable blockchain data and analytics. For Lux-specific deployments, refer to the [L1 Toolbox Self-Hosted Explorer Guide](https://build.lux.network/tools/l1-toolbox#selfHostedExplorer). 

# Blocksec (/integrations/blocksec)

---
title: Blocksec
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "BlockSec provides high-quality security audits with particular expertise in USP exploit detection and blockchain security."
logo: /images/blocksec.jpeg
developer: BlockSec
website: https://blocksec.com/
---

## Overview

BlockSec is a high-quality security audit provider specializing in blockchain security with particular expertise in identifying USP exploits. Their security team combines academic research with practical security experience to deliver comprehensive audits for projects building on Lux. Noted in the ecosystem as "extremely helpful," BlockSec's approach to security assessments emphasizes practical vulnerability detection and remediation.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **USP Exploit Detection**: Specialized expertise in identifying and preventing exploit vectors.
- **Security Monitoring**: Real-time monitoring solutions for blockchain projects.
- **Threat Intelligence**: Insights on emerging attack patterns and vulnerabilities.
- **Academic Approach**: Research-based methodology for security analysis.
- **Incident Response**: Support during security incidents and exploits.
- **Continuous Protection**: Ongoing security monitoring and assessment.

## Getting Started

To engage BlockSec for security audits:

1. **Initial Contact**: Reach out through their website to discuss your audit requirements.
2. **Audit Planning**: Define the scope, timeline, and specific security objectives.
3. **Audit Process**: 
   - Smart contract code review
   - Automated vulnerability scanning
   - Manual security analysis
   - Comprehensive exploit testing
4. **Findings Report**: Detailed documentation of security issues with severity ratings.
5. **Remediation Guidance**: Specific recommendations for addressing identified vulnerabilities.

## Use Cases

BlockSec security audits are particularly valuable for:

- **DeFi Protocols**: Thorough security validation for financial applications.
- **NFT Marketplaces**: Identifying vulnerabilities in NFT-related smart contracts.
- **Cross-Chain Applications**: Security assessment of bridge and cross-chain mechanisms.
- **Exchange Platforms**: Audit of exchange and trading contract implementations.
- **Protocol Implementations**: Verification of protocol security properties.

## Conclusion

BlockSec delivers high-quality security audits with particular strengths in USP exploit detection and practical security analysis. Their team combines academic research with hands-on security expertise to provide thorough assessments for projects building on Lux. Noted for being "extremely helpful" in the ecosystem, BlockSec offers both comprehensive audits and practical security guidance that helps projects build secure, resilient blockchain applications. 

# Blockworks (/integrations/blockworks)

---
title: Blockworks
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "Blockworks provides institutional-grade research, market analysis, and data insights for the Lux ecosystem and broader crypto markets."
logo: /images/blockworks.jpg
developer: Blockworks
website: https://blockworks.co/
documentation: https://blockworks.co/
---

## Overview

Blockworks is a leading financial media and research platform providing institutional-grade analysis, market insights, and data for the cryptocurrency ecosystem. Their comprehensive coverage includes in-depth research on Lux and its ecosystem, offering valuable insights for developers, investors, and institutions.



# Bridge (/integrations/bridge-orchestrator)

---
title: Bridge
category: Orchestrators
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Bridge is a payment orchestration platform enabling seamless stablecoin and fiat integration for modern applications."
logo: /images/bridge.png
developer: Bridge
website: https://www.bridge.xyz/
documentation: https://apidocs.bridge.xyz/
---

## Overview

Bridge is a payment orchestration platform that simplifies the integration of stablecoins and traditional payment methods into any application. As an orchestration layer, Bridge handles the complexity of multi-rail payments, currency conversions, and compliance requirements, enabling developers to build seamless payment experiences without managing the underlying infrastructure.

## Features

- **Payment Orchestration**: Unified API for managing complex payment flows
- **Multi-Rail Support**: Support for stablecoins, bank transfers, and card payments
- **Automatic Routing**: Smart routing to optimize payment success and cost
- **Real-Time Conversions**: Instant conversions between fiat and crypto
- **Compliance Integration**: Built-in KYC/AML for regulatory compliance
- **Developer APIs**: Clean REST APIs with comprehensive SDKs

## Getting Started

To integrate Bridge's orchestration platform:

1. **Create Account**: Sign up at [Bridge](https://www.bridge.xyz/) and complete verification
2. **Access APIs**: Get your API credentials from the developer dashboard
3. **Implement Integration**: Use Bridge SDKs or REST APIs to add payment orchestration
4. **Test and Launch**: Use sandbox environment for testing before going live

## Documentation

For complete API documentation and integration guides, visit [Bridge Docs](https://apidocs.bridge.xyz/).

## Use Cases

- **Multi-Rail Payments**: Accept payments via multiple methods with automatic routing
- **Cross-Border Transfers**: Enable efficient international payments
- **Crypto-Fiat Bridges**: Seamlessly convert between traditional and digital currencies
- **Embedded Finance**: Add financial services to any application

## Conclusion

Bridge provides essential payment orchestration infrastructure for Lux applications, enabling developers to build sophisticated payment flows with minimal complexity.


# Bridge (/integrations/bridge-stablecoin)

---
title: Bridge
category: Stablecoins as a Service
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Bridge provides stablecoin orchestration infrastructure enabling seamless integration of digital dollars into any application."
logo: /images/bridge.png
developer: Bridge
website: https://www.bridge.xyz/
documentation: https://apidocs.bridge.xyz/
---

## Overview

Bridge is a stablecoin orchestration platform that enables developers and businesses to seamlessly integrate digital dollars into their applications. As a comprehensive infrastructure layer, Bridge handles the complexity of stablecoin minting, burning, transfers, and conversions, allowing developers to focus on building great user experiences while Bridge manages the underlying stablecoin operations.

## Features

- **Stablecoin Orchestration**: Unified API for managing multiple stablecoin operations
- **Instant Conversions**: Real-time conversions between fiat and stablecoins
- **Multi-Stablecoin Support**: Support for major stablecoins including USDC, USDT, and more
- **Developer-First APIs**: Clean, well-documented APIs for rapid integration
- **Compliance Built-In**: Integrated KYC/AML and regulatory compliance
- **Global Coverage**: Support for users and transactions worldwide

## Getting Started

To integrate Bridge's stablecoin infrastructure:

1. **Sign Up**: Create an account on the [Bridge platform](https://www.bridge.xyz/)
2. **Get API Keys**: Access your API credentials from the developer dashboard
3. **Integrate**: Use Bridge's APIs to add stablecoin functionality to your application
4. **Go Live**: Launch your stablecoin-powered features on Lux

## Documentation

For API references and integration tutorials, visit the [Bridge Documentation](https://apidocs.bridge.xyz/).

## Use Cases

- **Payment Apps**: Build payment applications with instant stablecoin settlements
- **Fintech Products**: Add crypto capabilities to traditional fintech applications
- **NFT Marketplaces**: Enable stablecoin payments for digital asset purchases
- **Cross-Border Transfers**: Facilitate international money transfers using stablecoins

## Conclusion

Bridge provides the essential orchestration layer for stablecoin integration, enabling developers to easily add digital dollar functionality to their Lux applications with comprehensive APIs and built-in compliance.


# BWARE Labs (/integrations/bware-labs)

---
title: BWARE Labs
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: "BWARE Labs provides decentralized blockchain API infrastructure with high-performance RPC endpoints for Web3 applications."
logo: /images/bware.png
developer: BWARE Labs
website: https://bwarelabs.com/
documentation: https://docs.bwarelabs.com/
---

## Overview

BWARE Labs is a decentralized blockchain infrastructure provider offering high-performance RPC endpoints and API services for Web3 applications. Through its Blast API platform, BWARE Labs delivers reliable, scalable access to multiple blockchain networks including Lux, with a focus on performance, reliability, and decentralization.

## Features

- **Decentralized Infrastructure**: Distributed network of node providers for enhanced reliability.
- **High Performance**: Optimized RPC endpoints for fast response times and low latency.
- **Multi-Chain Support**: Access to multiple blockchain networks through a single platform.
- **Load Balancing**: Intelligent routing to ensure optimal performance and uptime.
- **Analytics Dashboard**: Monitor API usage and performance metrics in real-time.
- **Scalable Infrastructure**: Automatically scales to meet application demands.
- **WebSocket Support**: Real-time blockchain data through WebSocket connections.
- **Archive Nodes**: Access to complete historical blockchain data.

## Documentation

For integration guides and API documentation, visit the [BWARE Labs Documentation](https://docs.bwarelabs.com/).

## Use Cases

BWARE Labs serves various blockchain development needs:

- **DApp Development**: Reliable RPC infrastructure for decentralized applications.
- **High-Traffic Applications**: Scalable infrastructure for applications with demanding requirements.
- **Real-Time Data**: WebSocket connections for real-time blockchain events.
- **Historical Queries**: Archive node access for historical blockchain data.

## Conclusion

BWARE Labs provides decentralized, high-performance RPC infrastructure for blockchain applications on Lux, offering reliable API access with a focus on performance, scalability, and decentralization.



# Certora (/integrations/certora)

---
title: Certora
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Certora provides high-quality formal verification and security audits for smart contracts with specialized expertise in mathematical verification."
logo: /images/certora.png
developer: Certora
website: https://www.certora.com/
documentation: https://docs.certora.com/en/latest/
---

## Overview

Certora is a highly regarded security firm specializing in formal verification and comprehensive security audits for smart contracts. Using their proprietary Certora Prover technology, they can mathematically verify critical security properties of smart contracts, providing a level of assurance beyond traditional auditing approaches. Their team of formal verification experts and security researchers has been highlighted as highly recommended by security teams in the Lux ecosystem.

## Features

- **Formal Verification**: Mathematical verification of smart contract properties using the Certora Prover.
- **Smart Contract Audits**: Comprehensive security reviews combining formal methods with traditional auditing.
- **Custom Specification Development**: Creation of formal specifications for critical security properties.
- **Automated Analysis**: Advanced automated tools for detecting vulnerabilities.
- **Security Research**: Ongoing research into formal verification techniques for blockchain security.
- **Developer Education**: Resources for implementing formally verifiable smart contracts.

## Getting Started

To engage Certora for security audits:

1. **Initial Contact**: Reach out to Certora at [nooly@certora.com](mailto:nooly@certora.com) or [moran@certora.com](mailto:moran@certora.com) to discuss your project.
2. **Scoping Process**: Define the audit scope, formal verification requirements, and timeline.
3. **Audit and Verification Process**: 
   - Formal specification development
   - Mathematical verification using the Certora Prover
   - Traditional security audit methodologies
   - Comprehensive vulnerability assessment
4. **Results Delivery**: Detailed report of findings, verification results, and remediation recommendations.
5. **Post-Audit Support**: Assistance with implementing fixes and re-verification as needed.

## Documentation

For detailed information about Certora's formal verification approach and security services, visit their [website](https://docs.certora.com/en/latest/).

## Use Cases

Certora's services are particularly valuable for:

- **High-Value DeFi Protocols**: Mathematical verification of critical financial properties.
- **Complex Smart Contract Systems**: Formal verification of intricate contract interactions.
- **Novel Financial Mechanisms**: Validation of innovative DeFi mechanisms and algorithms.
- **Protocol Implementations**: Verification of protocol specification compliance.
- **Security-Critical Applications**: Projects where security failures would have significant consequences.

## Conclusion

Certora provides a unique combination of formal verification and traditional security auditing, offering one of the highest levels of security assurance available for smart contracts. Their approach is particularly valuable for projects with complex logic or high-value applications where mathematical certainty about critical properties is desired. Highly recommended by security teams in the ecosystem, Certora delivers sophisticated security analysis that can identify subtle vulnerabilities missed by conventional auditing approaches. 

# Chainbase (/integrations/chainbase)

---
title: Chainbase
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: "Chainbase provides comprehensive blockchain data infrastructure with RPC services and data APIs for Web3 development."
logo: /images/chainbase.jpeg
developer: Chainbase
website: https://chainbase.online/
documentation: https://docs.chainbase.online/
---

## Overview

Chainbase is a comprehensive blockchain data infrastructure platform providing RPC services, data APIs, and indexing solutions for Web3 applications. With support for multiple blockchain networks including Lux, Chainbase enables developers to access both raw blockchain data and structured, indexed information through a unified platform.

## Features

- **RPC Infrastructure**: Reliable, high-performance RPC endpoints for blockchain access.
- **Data APIs**: Structured APIs for accessing indexed blockchain data.
- **Multi-Chain Support**: Unified access to multiple blockchain networks.
- **Indexing Services**: Pre-indexed blockchain data for faster queries.
- **Real-Time Data**: Access to current blockchain state and real-time updates.
- **Historical Data**: Complete historical blockchain data with archive node support.
- **Developer Tools**: SDKs and tools for easy integration.
- **Scalable Infrastructure**: Enterprise-grade infrastructure for applications of any scale.

## Documentation

For detailed guides and API references, visit the [Chainbase Documentation](https://docs.chainbase.online/).

## Use Cases

Chainbase serves various blockchain development needs:

- **DApp Infrastructure**: Reliable RPC and data access for decentralized applications.
- **Data Analytics**: Structured data for blockchain analytics and insights.
- **Wallet Services**: Token balances, transactions, and account information.
- **DeFi Platforms**: Access to DeFi protocol data and real-time updates.
- **NFT Applications**: NFT metadata and ownership tracking.

## Conclusion

Chainbase provides comprehensive blockchain data infrastructure for Lux applications, combining reliable RPC services with powerful data APIs to support a wide range of Web3 development needs.



# Chainlink CCIP (/integrations/chainlink-ccip)

---
title: Chainlink CCIP
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: "Chainlink CCIP (Cross-Chain Interoperability Protocol) enables secure cross-chain messaging and token transfers on Lux with built-in security features and DON support."
logo: /images/chainlink.png
developer: Chainlink
website: https://chain.link/cross-chain
documentation: https://docs.chain.link/ccip
---

## Overview

Chainlink CCIP (Cross-Chain Interoperability Protocol) is a secure interoperability protocol that enables cross-chain messaging and token transfers on Lux. Built by Chainlink, CCIP leverages decentralized oracle networks (DONs) to provide enhanced security features and reliable cross-chain communication capabilities.

## Features

- **Programmable Token Transfers**: Transfer tokens across chains with custom logic.
- **Cross-Chain Messages**: Send arbitrary messages between supported networks.
- **Risk Management**: Built-in risk management through circuit breakers.
- **DON Security**: Secured by decentralized oracle networks.
- **Anti-Fraud Network**: Additional security layer monitoring cross-chain transactions.
- **Native Token Transfers**: Support for native token movements across chains.
- **Developer Tools**: Comprehensive SDKs and testing environments.

## Getting Started

To integrate Chainlink CCIP:

1. **Access Documentation**: Review the [CCIP Documentation](https://docs.chain.link/ccip).
2. **Choose Integration**: 
   - Token transfers
   - Message passing
   - Combined transfers and messages
3. **Implement Protocol**: 
   - Install CCIP contracts
   - Configure for Lux
   - Test cross-chain operations
4. **Monitor Transfers**: Track messages and transfers through CCIP explorer.

## Documentation

For detailed technical documentation and integration guides, visit the [Chainlink CCIP Documentation](https://docs.chain.link/ccip).

## Use Cases

CCIP enables various cross-chain applications:

- **Token Bridges**: Build secure token transfer bridges.
- **Cross-Chain dApps**: Develop applications spanning multiple networks.
- **DeFi Protocols**: Create cross-chain DeFi applications.
- **Gaming**: Implement cross-chain gaming mechanics.
- **Governance**: Enable cross-chain governance systems.

## Conclusion

Chainlink CCIP provides a secure and reliable infrastructure for cross-chain operations on Lux's LUExchange-Chain. With its robust security features, including DON support and the Anti-Fraud Network, CCIP offers developers a trusted solution for building cross-chain applications. Whether implementing token transfers or complex cross-chain logic, CCIP delivers the security and functionality needed for reliable interoperability. 

# Chainlink Data Feeds (/integrations/chainlink-data-feeds)

---
title: Chainlink Data Feeds
category: Data Feeds
available: ["LUExchange-Chain"]
description: Chainlink Data Feeds are the quickest way to connect your smart contracts to the real-world data such as asset prices and reserve balances.
logo: /images/chainlink.png
developer: Chainlink Labs
website: https://chain.link/
documentation: https://chain.link/data-feeds
---

## Overview

Chainlink Data Feeds are the quickest way to connect your smart contracts to the real-world data such as asset prices and reserve balances.

If you already started a project and need to integrate Chainlink, you can [add Chainlink to your existing project](https://docs.chain.link/resources/create-a-chainlinked-project?parent=dataFeeds#installing-into-existing-projects) with the `@chainlink/contracts` NPM package.

## Data Feed Best Practices

Before you use Data Feeds, read and understand the best practices on the [Selecting Quality Data Feeds](https://docs.chain.link/data-feeds/selecting-data-feeds) page. For best practices about data for specific asset types, see the following sections:

- [Best Practices for ETF and Forex feeds](https://docs.chain.link/data-feeds/selecting-data-feeds#etf-and-forex-feeds)
- [Best Practices for Exchange Rate Feeds](https://docs.chain.link/data-feeds/selecting-data-feeds#exchange-rate-feeds)
- [Risk Categories](https://docs.chain.link/data-feeds/selecting-data-feeds#data-feed-categories)

## Types of data feeds
Data feeds provide many different types of data for your applications.

- [Price Feeds](https://docs.chain.link/data-feeds#price-feeds)
- [Proof of Reserve Feeds](https://docs.chain.link/data-feeds#proof-of-reserve-feeds)
- [Rate and Volatility Feeds](https://docs.chain.link/data-feeds#rate-and-volatility-feeds)

## Using Data Feeds on the Lux Primary Network

To consume price data, your smart contract should reference `AggregatorV3Interface`, which defines the external functions implemented by Data Feeds.

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

import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES HARDCODED
 * VALUES FOR CLARITY.
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */


contract DataConsumerV3 {
    AggregatorV3Interface internal dataFeed;

    /**
     * Network: Lux Primary Network
     * Aggregator: LUX/USD
     * Address: 0x0A77230d17318075983913bC2145DB16C7366156
     */
    constructor() {
        dataFeed = AggregatorV3Interface(
            0x0A77230d17318075983913bC2145DB16C7366156
        );
    }

    /**
     * Returns the latest answer.
     */
    function getChainlinkDataFeedLatestAnswer() public view returns (int) {
        // prettier-ignore
        (
            /* uint80 roundID */,
            int answer,
            /*uint startedAt*/,
            /*uint timeStamp*/,
            /*uint80 answeredInRound*/
        ) = dataFeed.latestRoundData();
        return answer;
    }
}
```

### Primary Network Price Feed Addresses

| **Status** | **Pair**                   | **Contract Address**                            | **Asset Name**              | **Asset Type** | **Market Hours** |
|------------|----------------------------|-------------------------------------------------|-----------------------------|----------------|------------------|
| 🟢         | AAVE / USD                  | 0x3CA13391E9fb38a75330fb28f8cc2eB3D9ceceED      | Aave                        | Crypto         | Crypto           |
| 🔵         | AAVE Network Emergency Count (Lux) | 0x41185495Bc8297a65DC46f94001DC7233775EbEe | N/A                         | N/A            | N/A              |
| 🟢         | ADA / USD                   | 0x69C2703b8F1A85a2EF6aBDd085699a9F909BE053      | Cardano                     | Crypto         | Crypto           |
| 🟡         | ALPHA / USD                 | 0x7B0ca9A6D03FE0467A31Ca850f5bcA51e027B3aF      | Alpha Finance               | Crypto         | Crypto           |
| 🟢         | LUX / USD                  | 0x0A77230d17318075983913bC2145DB16C7366156      | Lux                   | Crypto         | Crypto           |
| 🟡         | AXS / USD                   | 0x155835C5755205597d62703a5A0b37e57a26Ee5C      | Axie Infinity               | Crypto         | Crypto           |
| 🟡         | BAT / USD                   | 0xe89B3CE86D25599D1e615C0f6a353B4572FF868D      | Basic Attention Token       | Crypto         | Crypto           |
| 🟠         | BEAM / USD                  | 0x3427232b88Ce4e7d62A03289247eE0cA5324f6ba      | Beam                        | Crypto         | Crypto           |


### Primary Network Proof of Reserve Addresses

| **Status** | **Asset**                     | **Contract Address**                              | **Reserve Type** | **Data Source** | **Reporting/Auditor**    |
|------------|--------------------------------|---------------------------------------------------|-----------------|----------------|-------------------------|
| 🔵         | AAVE.e PoR                     | 0x14C4c668E34c09E1FBA823aD5DB47F60aeBDD4F7        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | BTC.b PoR                      | 0x99311B4bf6D8E3D3B4b9fbdD09a1B0F4Ad8e06E9        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | DAI.e PoR                      | 0x976D7fAc81A49FA71EF20694a3C56B9eFB93c30B        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | Ion Digital Total Reserve      | 0x121C188f76831f504bD29C753074B37a4177cEc3        | Off-chain       | Instruxi       | Third-party auditor      |
| 🔵         | LINK.e PoR                     | 0x943cEF1B112Ca9FD7EDaDC9A46477d3812a382b6        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | USDC.e PoR                     | 0x63769951E4cfDbDC653dD9BBde63D2Ce0746e5F2        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | USDT.e PoR                     | 0x94D8c2548018C27F1aa078A23C4158206bE1CC72        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | WBTC.e PoR                     | 0xebEfEAA58636DF9B20a4fAd78Fad8759e6A20e87        | Cross-chain     | Cross-chain    | Wallet address          |


### Primary Network Rate and Volatility Feed Addresses

| **Asset**                   | **Contract Address**                              |
|-----------------------------|---------------------------------------------------|
| BTC-USD 30-Day Realized Vol  | 0x93b9B82158846cefa8b4040f22A3Bff05c365226        |
| ETH-USD 30-Day Realized Vol  | 0x89983A2FDd082FA40d8062BCE3986Fc601D2d29B        |


# Chainlink (/integrations/chainlink-oracles)

---
title: Chainlink
category: Oracles
available: ["LUExchange-Chain"]
description: "Chainlink is a decentralized oracle network that enables smart contracts to securely interact with real-world data."
logo: /images/chainlink.png
developer: Chainlink Labs
website: https://chain.link/
documentation: https://docs.chain.link/
---

## Overview

Chainlink is a decentralized oracle network that provides reliable, tamper-proof inputs and outputs for complex smart contracts on any blockchain. By connecting smart contracts with real-world data, events, and payments, Chainlink enables the development of advanced decentralized applications (dApps) across various industries. Its network of decentralized oracles allows smart contracts to securely interact with off-chain data, enhancing their functionality and scope.

## Features

- **Decentralized Oracles**: Chainlink uses a network of decentralized oracles to fetch and deliver reliable, tamper-resistant data to smart contracts.
- **Cross-Chain Interoperability**: Chainlink facilitates secure data exchange between different blockchains, enabling cross-chain smart contract functionality.
- **Data Integrity**: Chainlink ensures high data integrity by using multiple oracles and data sources, preventing single points of failure.
- **Verifiable Randomness**: Chainlink VRF (Verifiable Random Function) provides provably fair and tamper-proof randomness to smart contracts, essential for gaming, lotteries, and NFT minting.
- **Price Feeds**: Chainlink's widely used price feeds provide decentralized financial applications with accurate and reliable price data, supporting DeFi protocols like lending, borrowing, and stablecoins.

## Getting Started

To start using Chainlink, follow these steps:

1. **Visit Chainlink**: Explore the [Chainlink website](https://chain.link/) to understand its offerings and network capabilities.
2. **Set Up an Oracle**: Refer to the [documentation](https://docs.chain.link/docs/running-a-chainlink-node) to set up your own Chainlink node and participate in the decentralized oracle network.
3. **Integrate Price Feeds**: Use Chainlink's [Price Feeds](https://docs.chain.link/docs/get-the-latest-price) to integrate reliable price data into your DeFi application.
4. **Leverage Chainlink VRF**: Integrate [Chainlink VRF](https://docs.chain.link/docs/chainlink-vrf) for provably fair randomness in your smart contracts.
5. **Explore Cross-Chain Solutions**: Utilize Chainlink's [Cross-Chain Interoperability Protocol (CCIP)](https://docs.chain.link/ccip) for secure cross-chain data transfer and smart contract execution.

## Documentation

For in-depth guides, API references, and integration tutorials, visit the [Chainlink Documentation](https://docs.chain.link/).

## Use Cases

Chainlink is widely applicable in various blockchain scenarios:

- **DeFi Protocols**: Integrate secure and reliable price feeds to support lending, borrowing, and other financial activities.
- **Gaming and NFTs**: Use Chainlink VRF for fair randomness in gaming outcomes, lotteries, and NFT minting.
- **Insurance dApps**: Fetch real-world data like weather conditions or market prices to trigger automated insurance payouts.
- **Cross-Chain Applications**: Enable cross-chain data transfer and smart contract execution using Chainlink's CCIP.

## Conclusion

Chainlink is a crucial infrastructure for decentralized applications, offering a robust and secure way to connect smart contracts with real-world data. Whether you're developing a DeFi protocol, a gaming platform, or any other blockchain-based solution, Chainlink provides the tools and services needed to enhance your dApp's functionality and trustworthiness.


# Chainlink VRF (/integrations/chainlink-vrf)

---
title: Chainlink VRF
category: VRF
available: ["LUExchange-Chain", "All Lux L1s"]
description: Chainlink VRF (Verifiable Random Function) is a provably fair and verifiable random number generator (RNG) that enables smart contracts to access random values without compromising security or usability. 
logo: /images/chainlink.png
developer: Chainlink Labs
website: https://chain.link/vrf
documentation: https://docs.chain.link/vrf
---

## Overview

Chainlink VRF (Verifiable Random Function) is a provably fair and verifiable random number generator (RNG) that enables smart contracts to access random values without compromising security or usability. For each request, Chainlink VRF generates one or more random values and cryptographic proof of how those values were determined. The proof is published and verified onchain before any consuming applications can use it. This process ensures that results cannot be tampered with or manipulated by any single entity including oracle operators, miners, users, or smart contract developers.

Use Chainlink VRF to build reliable smart contracts for any applications that rely on unpredictable outcomes:

- Building blockchain games and NFTs.
- Random assignment of duties and resources. For example, randomly assigning judges to cases.
- Choosing a representative sample for consensus mechanisms.

### Two methods to request randomness
- **Subscription:** Create a subscription account and fund its balance with either native tokens or LINK. You can then connect multiple consuming contracts to the subscription account. When the consuming contracts request randomness, the transaction costs are calculated after the randomness requests are fulfilled and the subscription balance is deducted accordingly. This method allows you to fund requests for multiple consumer contracts from a single subscription.
- **Direct funding:** Consuming contracts directly pay with either native tokens or LINK when they request random values. You must directly fund your consumer contracts and ensure that there are enough funds to pay for randomness requests.

### Use Chainlink VRF on the Lux Primary Network

To use Chainlink VRF on the Lux Primary Network using **subscription**, utilize the [following information from Chainlink](https://docs.chain.link/vrf/v2-5/supported-networks#lux-mainnet):

| **Item**                               | **Value**                                                                                  |
|----------------------------------------|--------------------------------------------------------------------------------------------|
| **LINK Token**                          | 0x5947BB275c521040051D82396192181b413227A3                                                 |
| **VRF Coordinator**                    | 0xE40895D055bccd2053dD0638C9695E326152b1A4                                                 |
| **200 gwei Key Hash**                   | 0xea7f56be19583eeb8255aa79f16d8bd8a64cedf68e42fefee1c9ac5372b1a102                         |
| **500 gwei Key Hash**                   | 0x84213dcadf1f89e4097eb654e3f284d7d5d5bda2bd4748d8b7fada5b3a6eaa0d                         |
| **1000 gwei Key Hash**                  | 0xe227ebd10a873dde8e58841197a07b410038e405f1180bd117be6f6557fa491c                         |
| **Premium percentage (paying with LUX)**| 60                                                                                         |
| **Premium percentage (paying with LINK)**| 50                                                                                         |
| **Max Gas Limit**                        | 2,500,000                                                                                  |
| **Minimum Confirmations**               | 0                                                                                          |
| **Maximum Confirmations**               | 200                                                                                        |
| **Maximum Random Values**               | 500                                                                                        |


### Use Chainlink VRF on an Lux L1

This repository provides **example** contracts for how an Lux L1 could leverage Chainlink VRF functionality (available on the LUExchange-Chain) using Teleporter. This allows newly launched L1s to immediately utilize VRF without any trusted intermediaries or third-party integration requirements.

[Lux L1 VRF Example Contracts](https://github.com/luxfi/subnet-vrf-contracts)

### Best Practices

These are example best practices for using Chainlink VRF. To explore more applications of VRF, refer to [Chainlink's blog](https://blog.chain.link/).

**Getting a random number within a range**

If you need to generate a random number within a given range, use modulo to define the limits of your range. Below you can see how to get a random number in a range from 1 to 50.

```solidity
function fulfillRandomWords(
  uint256, /* requestId */
  uint256[] memory randomWords
) internal override {
  // Assuming only one random word was requested.
  s_randomRange = (randomWords[0] % 50) + 1;
}
```

**Getting multiple random values**

If you want to get multiple random values from a single VRF request, you can request this directly with the `numWords` argument:

- If you are using the VRF v2.5 subscription method, see the full example code for an example where one request returns multiple random values.

**Processing simultaneous VRF requests**

If you want to have multiple VRF requests processing simultaneously, create a mapping between `requestId` and the response. You might also create a mapping between the `requestId` and the address of the requester to track which address made each request.

```solidity
mapping(uint256 => uint256[]) public s_requestIdToRandomWords;
mapping(uint256 => address) public s_requestIdToAddress;
uint256 public s_requestId;

function requestRandomWords() external onlyOwner returns (uint256) {
  uint256 requestId = s_vrfCoordinator.requestRandomWords(
      VRFV2PlusClient.RandomWordsRequest({
          keyHash: keyHash,
          subId: s_vrfSubscriptionId,
          requestConfirmations: requestConfirmations,
          callbackGasLimit: callbackGasLimit,
          numWords: numWords,
          extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: true})) // new parameter
      })
  );
  s_requestIdToAddress[requestId] = msg.sender;

  // Store the latest requestId for this example.
  s_requestId = requestId;

  // Return the requestId to the requester.
  return requestId;
}

function fulfillRandomWords(
    uint256 requestId,
    uint256[] memory randomWords
  ) internal override {
  // You can return the value to the requester,
  // but this example simply stores it.
  s_requestIdToRandomWords[requestId] = randomWords;
}
```
You could also map the `requestId` to an index to keep track of the order in which a request was made.

**Processing VRF responses through different execution paths**

If you want to process VRF responses depending on predetermined conditions, you can create an `enum`. When requesting for randomness, map each `requestId` to an enum. This way, you can handle different execution paths in `fulfillRandomWords`. See the following example:

```solidity
// SPDX-License-Identifier: MIT
// An example of a consumer contract that relies on a subscription for funding.
// It shows how to setup multiple execution paths for handling a response.
pragma solidity 0.8.19;

import {LinkTokenInterface} from "@chainlink/contracts/src/v0.8/shared/interfaces/LinkTokenInterface.sol";
import {IVRFCoordinatorV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/interfaces/IVRFCoordinatorV2Plus.sol";
import {VRFConsumerBaseV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFConsumerBaseV2Plus.sol";
import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES HARDCODED VALUES FOR CLARITY.
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */

contract VRFv2MultiplePaths is VRFConsumerBaseV2Plus {

    // Your subscription ID.
    uint256 s_subscriptionId;

    // Lux Primary Network coordinator.
    address vrfCoordinatorV2Plus = 0xE40895D055bccd2053dD0638C9695E326152b1A4;

    // The gas lane to use, which specifies the maximum gas price to bump to.
    // For a list of available gas lanes on each network,
    // see https://docs.chain.link/vrf/v2-5/supported-networks
    bytes32 keyHash =
        0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;

    uint32 callbackGasLimit = 100000;

    // The default is 3, but you can set this higher.
    uint16 requestConfirmations = 3;

    // For this example, retrieve 1 random value in one request.
    // Cannot exceed VRFCoordinatorV2_5.MAX_NUM_WORDS.
    uint32 numWords = 1;

    enum Variable {
        A,
        B,
        C
    }

    uint256 public variableA;
    uint256 public variableB;
    uint256 public variableC;

    mapping(uint256 => Variable) public requests;

    // events
    event FulfilledA(uint256 requestId, uint256 value);
    event FulfilledB(uint256 requestId, uint256 value);
    event FulfilledC(uint256 requestId, uint256 value);

    constructor(uint256 subscriptionId) VRFConsumerBaseV2Plus(vrfCoordinatorV2Plus) {
        s_vrfCoordinator = IVRFCoordinatorV2Plus(vrfCoordinatorV2Plus);
        s_subscriptionId = subscriptionId;
    }

    function updateVariable(uint256 input) public {
      uint256 requestId = s_vrfCoordinator.requestRandomWords(VRFV2PlusClient.RandomWordsRequest({
            keyHash: keyHash,
            subId: s_subscriptionId,
            requestConfirmations: requestConfirmations,
            callbackGasLimit: callbackGasLimit,
            numWords: numWords,
            extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: true}))
          })
        );

        if (input % 2 == 0) {
            requests[requestId] = Variable.A;
        } else if (input % 3 == 0) {
            requests[requestId] = Variable.B;
        } else {
            requests[requestId] = Variable.C;
        }
    }

    function fulfillRandomWords(
        uint256 requestId,
        uint256[] memory randomWords
    ) internal override {
        Variable variable = requests[requestId];
        if (variable == Variable.A) {
            fulfillA(requestId, randomWords[0]);
        } else if (variable == Variable.B) {
            fulfillB(requestId, randomWords[0]);
        } else if (variable == Variable.C) {
            fulfillC(requestId, randomWords[0]);
        }
    }

    function fulfillA(uint256 requestId, uint256 randomWord) private {
        // execution path A
        variableA = randomWord;
        emit FulfilledA(requestId, randomWord);
    }

    function fulfillB(uint256 requestId, uint256 randomWord) private {
        // execution path B
        variableB = randomWord;
        emit FulfilledB(requestId, randomWord);
    }

    function fulfillC(uint256 requestId, uint256 randomWord) private {
        // execution path C
        variableC = randomWord;
        emit FulfilledC(requestId, randomWord);
    }
}
```


# Chainstack (/integrations/chainstack)

---
title: Chainstack
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: Chainstack is a multi-cloud, multi-protocol blockchain Platform as a Service (PaaS) that enables developers to deploy, manage, and scale nodes and networks across multiple cloud providers.
logo: /images/chainstack.webp
developer: Chainstack
website: https://chainstack.com/
documentation: https://docs.chainstack.com/
---

## Overview

Chainstack is a powerful blockchain Platform as a Service (PaaS) designed to simplify the deployment, management, and scaling of blockchain nodes and networks. With support for multiple cloud providers and protocols, Chainstack allows developers to build and manage blockchain infrastructures with ease, ensuring high performance, reliability, and security. Whether you're running a private network, a public blockchain node, or deploying a decentralized application, Chainstack offers the tools and infrastructure needed to succeed.

## Features

- **Multi-Cloud Support**: Deploy nodes across various cloud providers, including AWS, Google Cloud, Microsoft Azure, and more, ensuring flexibility and redundancy.
- **Multi-Protocol Compatibility**: Chainstack supports multiple blockchain protocols, including Ethereum, Hyperledger Fabric, Corda, and more, allowing you to work with the technology of your choice.
- **Scalability**: Easily scale your blockchain infrastructure to meet the demands of your applications, whether it's for development, testing, or production environments.
- **Simplified Node Management**: Use Chainstack's intuitive dashboard to manage your nodes and networks, monitor performance, and perform updates with minimal effort.
- **High Availability**: Ensure your blockchain applications remain online and performant with Chainstack's robust infrastructure and automated failover mechanisms.

## Getting Started

To begin using Chainstack, follow these steps:

1. **Create an Account**: Sign up on the [Chainstack website](https://chainstack.com/) to access the platform.
2. **Deploy a Node**: Use the Chainstack dashboard to deploy your first blockchain node. Choose your preferred protocol and cloud provider.
3. **Manage Your Infrastructure**: Utilize Chainstack’s tools to monitor, manage, and scale your nodes as needed. Take advantage of multi-cloud deployments for increased reliability.
4. **Integrate with dApps**: Connect your deployed nodes to your decentralized applications or blockchain projects, ensuring seamless interaction with the blockchain.
5. **Explore Advanced Features**: Dive into Chainstack’s advanced features like API access, node telemetry, and analytics to optimize your blockchain infrastructure.

## Documentation

For detailed setup guides, API references, and integration instructions, visit the [Chainstack Documentation](https://docs.chainstack.com/).

## Use Cases

Chainstack is ideal for various blockchain projects and applications:

- **Enterprise Blockchain Networks**: Deploy and manage private or consortium blockchain networks with ease, ensuring enterprise-grade security and performance.
- **Decentralized Applications (dApps)**: Run scalable and reliable nodes to support your dApps on public blockchains like Ethereum.
- **Blockchain Development and Testing**: Use Chainstack’s infrastructure to develop and test your blockchain applications in a controlled environment before deploying to production.
- **Multi-Cloud Deployments**: Ensure high availability and redundancy by deploying your blockchain infrastructure across multiple cloud providers.

## Conclusion

Chainstack provides a comprehensive and flexible platform for deploying and managing blockchain infrastructure, making it an essential tool for developers and enterprises alike. With its multi-cloud, multi-protocol support and ease of use, Chainstack enables you to build, scale, and maintain blockchain networks with confidence and efficiency.



# Chaos Labs Oracles (/integrations/chaos-labs)

---
title: Chaos Labs Oracles
category: Oracles
available: ["LUExchange-Chain"]
description: "Decentralized oracle protocol built for real-time risk, providing unified price feeds, risk feeds, and proof of reserves with ultra-low latency."
logo: /images/chaos.png
developer: Chaos Labs
website: https://chaoslabs.xyz/oracles
documentation: https://docs.chaoslabs.xyz/
---

## Overview

Chaos Labs Oracles is a decentralized oracle protocol built for real-time risk management, delivering unified data feeds that include prices, risk parameters, and proof of reserves. The platform provides high-precision, low-latency price data with built-in risk filtering and real-time anomaly detection, consuming fresh data 5× per second to capture every market move. With ultra-low latency and continuous quality control, Chaos Oracles ensures only clean, trustworthy inputs power onchain systems. The protocol features real-time risk tuning that maximizes security and capital efficiency through automated risk parameter adjustments, governance-safe automation within defined bounds, and verifiable proof of reserves with tamper-resistant attestations published onchain for complete transparency.



# Chronicle (/integrations/chronicle-data-feeds)

---
title: Chronicle
category: Oracles
available: ["LUExchange-Chain"]
description: Chronicle Oracles enable you to access verifiable data onchain.
logo: /images/chronicle.png
developer: Chronicle Labs
website: https://chroniclelabs.org/
documentation: https://docs.chroniclelabs.org/
---

## Overview
[Chronicle Protocol](https://chroniclelabs.org/) is a novel Oracle solution that overcomes the current limitations of transferring data onchain by developing scalable, cost-efficient, decentralized, and verifiable Oracles.
For the data feeds addresses, please check out the [Chronicle Dashboard](https://chroniclelabs.org/dashboard) under **Oracles** section. Select either **Mainnets** or **Testnets**, then **Lux LUExchange-Chain Oracles**.

### Data Feeds Types
Chronicle provides two categories of Oracles: [DeFi Oracles](https://docs.chroniclelabs.org/Products/DeFiOracle/) and [Verified Asset Oracles (VAO)](https://docs.chroniclelabs.org/Products/DeFiOracle/).

DeFi Oracles include:
- Cryptocurrency Oracles
- Fiat Currency Oracles
- Yield Rate Oracles

[The Verified Asset Oracle (VAO)](https://docs.chroniclelabs.org/Products/VerifiedAssetOracle/) — formerly known as the RWA Oracle — securely and transparently verifies the integrity and quality of any offchain asset, transports the resulting data onchain, and makes it directly available to smart contracts and onchain products.

### Check the Chronicle Oracles on the Chronicle Dashboard

- [Lux LUExchange-Chain Oracles](https://chroniclelabs.org/dashboard/oracles#blockchain=LUX)
- [Lux Testnet Testnet Oracles](https://chroniclelabs.org/dashboard/oracles#testnet=true&blockchain=FUJI)

## Using Chronicle DeFi Oracles on Lux Testnet Testnet

The following example showcases how to integrate the LUX/USD oracle on Lux Testnet Testnet.

Chronicle contracts are read-protected by a whitelist, meaning you won't be able to read them onchain without your address being added to the whitelist. 
On the Testnet networks, users can add themselves to the whitelist through the SelfKisser contract; a process playfully referred to as "kissing" themselves. 
**To get access to production Oracles on the Mainnet, please open a support ticket in [Discord](https://discord.com/invite/CjgvJ9EspJ) in the 🆘 ｜ support channel.**

For oracle addresses, please check out the [Dashboard](https://chroniclelabs.org/dashboard/oracles).

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

/**
 * @title OracleReader
 * @notice A simple contract to read from Chronicle oracles
 * @dev To see the full repository, visit https://github.com/chronicleprotocol/OracleReader-Example.
 * @dev Addresses in this contract are hardcoded for Lux Testnet Testnet.
 * For other supported networks, check the https://chroniclelabs.org/dashboard/oracles.
 */
contract OracleReader {
    /**
    * @notice The Chronicle oracle to read from.
    * Chronicle_LUX_USD - 0x8b3328b27436263e0BfE7597a0D97B1BEE9cC576
    * Network: Lux Testnet Testnet
    */

    IChronicle public chronicle = IChronicle(address(0x8b3328b27436263e0BfE7597a0D97B1BEE9cC576));

    /**
    * @notice The SelfKisser granting access to Chronicle oracles.
    * SelfKisser_1:0x371A53bB4203Ad5D7e60e220BaC1876FF3Ddda5B
    * Network: Lux Testnet Testnet
    */
    ISelfKisser public selfKisser = ISelfKisser(address(0x371A53bB4203Ad5D7e60e220BaC1876FF3Ddda5B));

    constructor() {
        // Note to add address(this) to chronicle oracle's whitelist.
        // This allows the contract to read from the chronicle oracle.
        selfKisser.selfKiss(address(chronicle));
    }

    /**
    * @notice Function to read the latest data from the Chronicle oracle.
    * @return val The current value returned by the oracle.
    * @return age The timestamp of the last update from the oracle.
    */
    function read() external view returns (uint256 val, uint256 age) {
        (val, age) = chronicle.readWithAge();
    }
}

// Copied from [chronicle-std](https://github.com/chronicleprotocol/chronicle-std/blob/main/src/IChronicle.sol).
interface IChronicle {
    /**
    * @notice Returns the oracle's current value.
    * @dev Reverts if no value set.
    * @return value The oracle's current value.
    */
    function read() external view returns (uint256 value);

    /**
    * @notice Returns the oracle's current value and its age.
    * @dev Reverts if no value set.
    * @return value The oracle's current value using 18 decimals places.
    * @return age The value's age as a Unix Timestamp .
    * */
    function readWithAge() external view returns (uint256 value, uint256 age);
}

// Copied from [self-kisser](https://github.com/chronicleprotocol/self-kisser/blob/main/src/ISelfKisser.sol).
interface ISelfKisser {
    /// @notice Kisses caller on oracle `oracle`.
    function selfKiss(address oracle) external;
}
```

## Documentation Link
For more examples, check out the [Chronicle Documentation](https://docs.chroniclelabs.org/Developers/tutorials/Remix).

# Circle CCTP (/integrations/circle-cctp)

---
title: Circle CCTP
category: Crosschain Solutions
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Circle CCTP (Cross-Chain Transfer Protocol) enables native USDC transfers between Lux and other supported blockchains."
logo: /images/circle.png
developer: Circle
website: https://www.circle.com/en/cross-chain-transfer-protocol
documentation: https://developers.circle.com/stablecoins/docs/cctp-getting-started
---

## Overview

Circle's Cross-Chain Transfer Protocol (CCTP) is a permissionless on-chain utility that enables native USDC transfers between supported blockchain networks. Unlike bridged or wrapped tokens, CCTP burns USDC on the source chain and mints native USDC on the destination chain, ensuring users always receive canonical, Circle-issued USDC.

## Features

- **Native USDC**: Transfer native USDC, not wrapped or bridged tokens
- **Permissionless**: Anyone can use CCTP without approval
- **Capital Efficient**: No liquidity pools required
- **Burn and Mint**: Clean burn-and-mint mechanism
- **Multi-Chain**: Support for Lux and other major chains
- **Composable**: Can be integrated into any application

## Getting Started

To use CCTP for cross-chain USDC transfers:

1. **Review Documentation**: Study the [CCTP documentation](https://developers.circle.com/stablecoins/docs/cctp-getting-started)
2. **Understand Flow**: Learn the burn-and-mint message flow
3. **Integrate Contracts**: Integrate CCTP contracts into your application
4. **Test on Testnet**: Test integration on supported testnets
5. **Deploy**: Launch cross-chain USDC functionality

## Documentation

For comprehensive guides, visit [Circle CCTP Documentation](https://developers.circle.com/stablecoins/docs/cctp-getting-started).

## Use Cases

- **Cross-Chain Payments**: Send USDC between Lux and other chains
- **DeFi Bridging**: Move USDC between DeFi ecosystems
- **Application Integration**: Build cross-chain USDC flows into dApps
- **Treasury Management**: Manage USDC across multiple chains

## Conclusion

Circle CCTP provides essential cross-chain infrastructure for Lux, enabling native USDC transfers between chains without the risks associated with wrapped or bridged tokens.


# Circle (/integrations/circlepay)

---
title: Circle
category: Assets
available: ["LUExchange-Chain"]
description: Circle provides regulated digital currencies (USDC and EURC) and enterprise-grade payment infrastructure for building on-chain applications on Lux.
logo: /images/circle.png
developer: Circle
website: https://www.circle.com/
documentation: https://developers.circle.com/
---

## Overview

Circle is a global financial technology company that provides payment infrastructure for the digital economy. Circle issues USDC and EURC, two of the most trusted and widely-used stablecoins, which are fully regulated digital currencies backed 1:1 by cash and short-term U.S. Treasury bonds. USDC is natively available on Lux LUExchange-Chain, enabling fast, low-cost transactions for payments, DeFi, and enterprise applications.

Beyond stablecoins, Circle offers a comprehensive suite of developer services including Cross-Chain Transfer Protocol (CCTP), smart contract wallets, payment gateways, and gasless transaction infrastructure that enable developers to build seamless on-chain experiences on Lux.

## Features

- **Regulated Stablecoins**: USDC and EURC are issued by Circle and regulated by U.S. financial authorities, providing trust and transparency.
- **Native Lux Support**: USDC is natively available on Lux LUExchange-Chain for fast, low-cost transactions.
- **Cross-Chain Transfer Protocol (CCTP)**: Transfer USDC natively between Lux and other supported chains without wrapped tokens or liquidity pools.
- **Smart Contract Wallets**: Enterprise-grade programmable wallets with built-in security and recovery features compatible with Lux.
- **Gasless Transactions (Paymaster)**: Sponsor gas fees for users on Lux, enabling seamless onboarding experiences.
- **Payment Gateway**: Accept USDC payments on Lux with Circle's payment APIs and convert to fiat if needed.
- **Minting and Redemption Services**: Institutional access to mint and redeem USDC directly with Circle.
- **Developer SDKs**: Official SDKs for integrating Circle services into your Lux applications.
- **Testnet Support**: Free testnet USDC from Circle's faucet for development and testing on Lux Testnet testnet.
- **Transparent Reserves**: Monthly attestations from independent accounting firms verify 1:1 backing.
- **API-First Design**: RESTful APIs with comprehensive documentation for easy integration.

## Getting Started

To integrate Circle USDC into your Lux application:

1. **Get Testnet Tokens**: Visit the [Circle Faucet](https://faucet.circle.com/) to get free testnet USDC for development on Lux Testnet.

2. **Understand USDC on Lux**: USDC uses a 6-decimal precision token standard on Lux LUExchange-Chain. You can interact with it using standard Web3 libraries like viem, ethers.js, or web3.js.

3. **Implement USDC Transfers**: Use the USDC smart contract on Lux to send and receive payments in your application.

4. **Integrate Cross-Chain Transfers**: Use Circle's Cross-Chain Transfer Protocol (CCTP) to move USDC between Lux and other supported chains seamlessly.

5. **Set Up Webhooks**: Configure webhooks to receive real-time notifications about USDC transactions and user activities.

## USDC on Lux

**Lux LUExchange-Chain Mainnet**: `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`

For testnet addresses, see the [USDC Contract Addresses documentation](https://developers.circle.com/stablecoins/docs/usdc-on-test-networks).

## Documentation

For comprehensive guides, API references, and SDK documentation, visit:

- [Circle Developer Portal](https://developers.circle.com/)
- [USDC on Lux Guide](https://developers.circle.com/stablecoins/docs/usdc-on-test-networks)
- [Cross-Chain Transfer Protocol (CCTP) Documentation](https://developers.circle.com/stablecoins/docs/cctp-getting-started)
- [Smart Contract Wallet Documentation](https://developers.circle.com/w3s/docs/programmable-wallets-quickstart)
- [API Reference](https://developers.circle.com/api-reference)

## Use Cases on Lux

Circle's infrastructure enables a wide range of blockchain applications on Lux:

**Payment Applications**: Build payment apps on Lux that accept USDC for instant, low-cost global transfers.

**DeFi Platforms**: Use USDC as a stable trading pair, collateral, or yield-generating asset in Lux DeFi protocols.

**NFT Marketplaces**: Accept USDC payments for NFTs on Lux, providing price stability and easier accounting.

**Cross-Chain Applications**: Leverage CCTP to build applications that move USDC seamlessly between Lux and other blockchains.

**Web3 Gaming**: Use USDC for in-game purchases, rewards, and player-to-player trading on Lux with real-world value.

**Remittance Services**: Enable fast, low-cost international money transfers using USDC on Lux.

**Merchant Solutions**: Accept USDC payments from customers on Lux with instant settlement and optional fiat conversion.

**Enterprise Treasury**: Use USDC on Lux for corporate treasury management, payroll, and B2B payments.

## Pricing

Circle offers transparent pricing for its services:

**USDC Transfers**: 
- On-chain transfers pay only network gas fees
- No Circle fees for basic USDC transfers between wallets

**Institutional Services**:
- Circle Mint: 0.03% fee for minting and redeeming USDC (institutional accounts)
- Minimum fees and volume requirements apply

**Developer Services**:
- Smart Contract Wallets: Pricing based on wallet creation and transaction volume
- Paymaster (Gas Sponsorship): Pay-as-you-go based on gas costs sponsored
- Circle APIs: Free tier available, paid plans for higher volume

**CCTP**:
- Free to use protocol
- Only pay standard gas fees on source and destination chains

For enterprise pricing and custom arrangements, contact [Circle's sales team](https://www.circle.com/en/contact).

## Circle Developer Resources

- **Testnet Faucet**: Get free testnet USDC at [faucet.circle.com](https://faucet.circle.com/)
- **Developer Discord**: Join the [Circle Discord](https://discord.gg/circle) to connect with other developers
- **Developer Grants**: Apply for grants to build innovative applications with Circle's technology
- **Sample Applications**: Explore open-source demos and reference implementations
- **Circle Research**: Access whitepapers and technical research on stablecoin technology

## Conclusion

Circle provides the essential infrastructure for building the next generation of financial applications on Lux. With USDC and EURC as trusted digital dollar and euro equivalents, combined with enterprise-grade developer tools like CCTP, smart contract wallets, and gasless transactions, Circle enables developers to create seamless user experiences on Lux that bridge traditional finance and blockchain technology. Whether you're building a payment app, DeFi protocol, NFT marketplace, or enterprise solution on Lux, Circle's regulated stablecoins and developer services provide a solid foundation for innovation in the programmable internet economy.



# Coinbase Cloud (/integrations/coinbase-cloud)

---
title: Coinbase Cloud
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Coinbase Cloud provides enterprise blockchain infrastructure including validator services, staking, and developer APIs."
logo: /images/coinbase.png
developer: Coinbase
website: https://www.coinbase.com/developer-platform
documentation: https://docs.cdp.coinbase.com/
---

## Overview

Coinbase Cloud, formerly Bison Trails, is Coinbase's enterprise blockchain infrastructure platform providing institutional-grade validator services, staking solutions, and developer APIs. Leveraging Coinbase's security expertise and scale, Coinbase Cloud enables institutions to participate in Lux and other blockchain networks with confidence.

## Features

- **Coinbase Security**: Enterprise security backed by Coinbase's industry-leading practices
- **Validator Infrastructure**: Professional validator hosting and management
- **Staking Services**: Institutional staking with comprehensive reporting
- **Participate API**: Unified API for staking operations across networks
- **Query & Transact**: APIs for blockchain data and transaction management
- **SOC 2 Certified**: Compliance-ready infrastructure for institutions

## Getting Started

To use Coinbase Cloud:

1. **Access Platform**: Visit [Coinbase Developer Platform](https://www.coinbase.com/developer-platform)
2. **Create Account**: Sign up for Coinbase Cloud access
3. **Select Services**: Choose validator, staking, or API services
4. **Configure**: Set up your infrastructure through the platform
5. **Operate**: Manage through Coinbase Cloud dashboard

## Documentation

For API references and guides, visit [Coinbase Cloud Docs](https://docs.cdp.coinbase.com/).

## Use Cases

- **Institutional Validation**: Run Lux validators with Coinbase-grade security
- **Enterprise Staking**: Implement staking programs for enterprises
- **Developer Infrastructure**: Build applications using Coinbase Cloud APIs
- **Custodian Support**: Infrastructure for custody providers

## Conclusion

Coinbase Cloud brings Coinbase's security expertise and scale to Lux infrastructure, enabling institutions to confidently participate in network validation and staking.


# Coinbase (/integrations/coinbase)

---
title: Coinbase
category: Custody
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Coinbase provides institutional custody and prime brokerage services with regulatory compliance and comprehensive digital asset infrastructure."
logo: /images/coinbase.png
developer: Coinbase
website: https://www.coinbase.com/wealth
documentation: https://www.coinbase.com/wealth
---

## Overview

Coinbase is a leading cryptocurrency platform offering institutional custody, trading, and prime brokerage services through Coinbase Institutional. As a publicly-traded, regulated entity, Coinbase provides enterprise-grade infrastructure for institutions, including custody solutions, trading services, and comprehensive digital asset management tools with industry-leading security and compliance.

## Features

- **Regulated Custody**: Fully regulated custodian with trust company status and comprehensive licensing.
- **Prime Brokerage**: Institutional trading services with access to multiple liquidity venues.
- **Cold Storage**: 98% of assets stored in secure offline cold storage.
- **Insurance Coverage**: Comprehensive insurance protection for custodied digital assets.
- **Staking Services**: Institutional staking infrastructure with rewards and delegation.
- **OTC Trading**: Large block trading desk for institutional-sized transactions.
- **Multi-Asset Support**: Support for a wide range of cryptocurrencies and digital assets.
- **Compliance Infrastructure**: Built-in AML/KYC and regulatory compliance tools.

## Documentation

For detailed guides and API documentation, visit [Coinbase Cloud Documentation](https://docs.cloud.coinbase.com/).

## Use Cases

Coinbase serves various institutional needs:

- **Institutional Custody**: Secure asset storage for funds, family offices, and institutional investors.
- **Prime Services**: Trading, lending, and financing services for institutional clients.
- **Corporate Treasury**: Digital asset management for corporate treasuries and enterprises.
- **Staking Infrastructure**: Institutional staking services for proof-of-stake networks.
- **Fund Administration**: Custody and reporting for investment funds.

## Conclusion

Coinbase provides trusted institutional custody and prime services for digital assets on Lux, offering regulated infrastructure with comprehensive insurance, cold storage security, and access to institutional trading services for enterprises and financial institutions.



# CoinGecko (/integrations/coingecko)

---
title: CoinGecko
category: Token Aggregators
available: ["LUExchange-Chain", "All Lux L1s"]
description: "CoinGecko provides comprehensive cryptocurrency data including prices, trading volume, market cap, and detailed analytics for tokens on Lux."
logo: /images/coingecko.png
developer: CoinGecko
website: https://www.coingecko.com/
documentation: https://www.coingecko.com/api/documentation
---

## Overview

CoinGecko is a leading cryptocurrency data aggregator that provides comprehensive market data for the Lux ecosystem. It offers detailed information about tokens, exchanges, and DeFi protocols, including price data, trading volumes, market capitalization, and various other metrics that help users make informed decisions.

## Features

- **Market Data**: Real-time price tracking, market cap, and volume data for Lux tokens.
- **Developer Tools**: Robust API access with extensive endpoints for market data integration.
- **Token Info**: Detailed information about tokens including team, technology, and community metrics.
- **Exchange Data**: Comprehensive trading pair information across centralized and decentralized exchanges.
- **DeFi Insights**: Tracking of DeFi protocols, TVL, and yield opportunities on Lux.
- **Portfolio Tracking**: Tools for monitoring and analyzing cryptocurrency holdings.
- **Historical Data**: Access to historical price and market data for analysis.

## Getting Started

To utilize CoinGecko's services:

1. **Visit Platform**: Access [CoinGecko](https://www.coingecko.com/).
2. **Explore Lux**: Navigate to Lux ecosystem tokens and markets.
3. **Track Assets**: 
   - Search for specific tokens
   - Monitor market metrics
   - Create watchlists
4. **API Integration**: For developers, integrate CoinGecko data using their API.

## Documentation

For detailed API documentation and integration guides, visit the [CoinGecko API Documentation](https://www.coingecko.com/api/documentation).

## Use Cases

CoinGecko serves various market data needs:

- **Market Analysis**: Track token prices and market trends on Lux.
- **Development**: Integrate reliable price feeds and market data into dApps.
- **Portfolio Tracking**: Monitor investment performance across multiple tokens.
- **Research**: Access detailed token information and historical data.
- **DeFi Integration**: Build applications with comprehensive market data support.

## Conclusion

CoinGecko provides essential market data infrastructure for the Lux ecosystem, offering reliable and comprehensive information crucial for users, developers, and analysts. Its combination of detailed token metrics, market data, and developer tools makes it an invaluable resource for anyone operating in the Lux marketplace. 

# CoinMarketCap (/integrations/coinmarketcap)

---
title: CoinMarketCap
category: Token Aggregators
available: ["LUExchange-Chain", "All Lux L1s"]
description: "CoinMarketCap is a leading cryptocurrency data platform providing comprehensive market data, analytics, and insights for Lux ecosystem tokens."
logo: /images/coinmarketcap.jpeg
developer: CoinMarketCap
website: https://coinmarketcap.com/
documentation: https://coinmarketcap.com/api/documentation/v1/
---

## Overview

CoinMarketCap is one of the most referenced price-tracking websites for crypto assets, providing comprehensive data for the Lux ecosystem. It offers real-time market data, detailed analytics, and various tools for tracking cryptocurrency markets, with extensive coverage of tokens and projects building on Lux.

## Features

- **Market Data**: Real-time price tracking, market cap rankings, and trading volume analytics.
- **Exchange Data**: Comprehensive information about trading pairs and exchange volumes.
- **On-Chain Metrics**: Integration with blockchain data for enhanced analytics.
- **Professional API**: Enterprise-grade API access for market data integration.
- **Token Information**: Detailed profiles of cryptocurrencies including team info, events, and announcements.
- **Market Analysis**: Tools for technical analysis and market trends.
- **Educational Content**: Resources for understanding crypto markets and technologies.

## Getting Started

To begin using CoinMarketCap:

1. **Access Platform**: Visit [CoinMarketCap](https://coinmarketcap.com/).
2. **Explore Lux**: Navigate to Lux ecosystem tokens and markets.
3. **Track Assets**: 
   - Search for specific tokens
   - Create watchlists
   - Monitor market metrics
4. **API Integration**: For developers, integrate market data using their professional API.

## Documentation

For comprehensive API documentation and integration guides, visit the [CoinMarketCap API Documentation](https://coinmarketcap.com/api/documentation/v1/).

## Use Cases

CoinMarketCap serves various market intelligence needs:

- **Market Research**: Access comprehensive market data and analytics.
- **Development**: Integrate reliable price and market data into applications.
- **Investment Analysis**: Track market trends and token performance.
- **Due Diligence**: Research detailed token and project information.
- **Market Monitoring**: Real-time tracking of market movements and trends.

## Conclusion

CoinMarketCap provides essential market intelligence and data services for the Lux ecosystem. With its comprehensive coverage, professional-grade API, and extensive market analytics, it serves as a crucial resource for users, developers, and institutions operating in the Lux marketplace. Whether for market research, development, or investment analysis, CoinMarketCap delivers reliable and detailed information for informed decision-making. 

# Colossus Digital (/integrations/colossus)

---
title: Colossus Digital
category: Custody
available: ["LUExchange-Chain", "Platform-Chain"]
description: The Colossus Institutional Hub is a unified platform for institutional staking, governance, and custody workflows across multiple chains and custody providers.
logo: /images/colossus.png
developer: Colossus Digital
website: https://colossus.digital/
documentation: https://docs.colossus.digital/
---

## Overview

Colossus Institutional Hub is a comprehensive platform designed to simplify staking, governance, and custody operations for institutions across PoS networks. Built with security, compliance, and scalability in mind, it enables seamless interaction between clients, custodians and validators through a unified API and UI interface. Whether using third-party custody platforms like Fireblocks, Ledger Enterprise, DFNS or HSMs, Colossus ensures secure, policy-governed transaction orchestration at scale.

## Features

- **Unified API & UI**: A single interface for staking, governance, and delegation across all major L1 networks and custody solutions.
- **Multi-Chain Support**: Stake and manage assets across Lux LUExchange-Chain and Platform-Chain, and more.
- **Custodian Agnostic**: Integrates with Fireblocks, Ledger Enterprise, DFNS, and other self-managed custody setups.
- **Secure Transaction Crafting**: Colossus Multi-party crafting and governance-driven approval using quorum-based threshold-initiation.
- **Transaction Lens & Decoder**: Institutional-grade transaction preview and validation tools to ensure compliant transaction generation.
- **Governance Workflows**: Define approval policies, quorum thresholds, and audit trails for every transaction.
- **Auditing & Reporting**: Real-time reporting for compliance, treasury tracking, and validator operations.

## Getting Started

To begin using the Colossus Institutional Hub:

1. **Visit the Website**: Learn more about Colossus and the Institutional Hub at [colossus.digital](https://colossus.digital/).
2. **Explore the Docs**: Review the [Colossus Developer Docs](https://docs.colossus.digital/) to understand how to integrate.
3. **Connect a Custody Provider**: Link your Fireblocks, DFNS, or Ledger Enterprise setup to begin delegation.
4. **Configure Policies**: Define your governance approval rules, transaction initation quorum, and transaction controls.
5. **Start Staking**: Delegate assets to validators across supported networks with full custody security.

## Documentation

For full integration guides, transaction workflows samples, and API references, explore the [Colossus Documentation Portal](https://docs.colossus.life/).

## Use Cases

Colossus Institutional Hub is ideal for:

- **Exchanges**: Offer staking-as-a-service without taking custody risk.
- **Custodians**: Enable delegation and governance services directly from MPC or HSM-based vaults.
- **Funds and Treasuries**: Manage validator positions and governance votes with enterprise controls.
- **Staking Providers**: Connect to a two-sided marketplace to source institutional delegations.

## Conclusion

The Colossus Institutional Hub enables institutions to securely stake and govern assets at scale with full compliance and custody controls. It removes the complexity of managing staking across chains, validators, and wallet providers by unifying everything under a secure, policy-driven architecture. Whether you're an institutional investor, exchange, custodian, or validator, Colossus offers the tools you need to scale digital asset operations securely and efficiently.


# Copper (/integrations/copper)

---
title: Copper
category: Custody
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Copper provides institutional-grade digital asset custody and treasury management solutions with advanced security infrastructure."
logo: /images/copper.webp
developer: Copper
website: https://copper.co/
documentation: https://copper.co/
---

## Overview

Copper is a digital asset custody and treasury management platform designed for institutions, offering secure storage and management of cryptocurrencies and digital assets. With a focus on institutional-grade security and operational efficiency, Copper provides comprehensive solutions for managing digital asset portfolios with advanced security protocols and enterprise-ready infrastructure.

## Features

- **Institutional Custody**: Secure storage solutions designed for institutional asset management.
- **Multi-Party Computation (MPC)**: Advanced cryptographic technology for enhanced security without single points of failure.
- **Treasury Management**: Comprehensive tools for managing digital asset treasuries and portfolios.
- **Trading Integration**: Connect to multiple exchanges and trading venues while maintaining custody.
- **Compliance Tools**: Built-in compliance and governance features for regulatory requirements.
- **Multi-Signature Security**: Flexible approval workflows and multi-signature capabilities.
- **Cold Storage**: Secure offline storage options for long-term asset protection.
- **Insurance Coverage**: Asset protection through comprehensive insurance policies.

## Documentation

For more information, visit the [Copper website](https://copper.co/).

## Use Cases

Copper serves various institutional custody needs:

- **Asset Management**: Secure custody for institutional investment portfolios.
- **Trading Operations**: Maintain custody while executing trades across multiple venues.
- **Corporate Treasury**: Enterprise-grade solutions for corporate digital asset management.
- **Fund Administration**: Custody and management for investment funds and vehicles.
- **Compliance**: Meet regulatory requirements with built-in governance tools.

## Conclusion

Copper provides comprehensive institutional custody solutions for digital assets on Lux, offering advanced security infrastructure and treasury management capabilities designed for enterprises, funds, and institutional investors.



# Core (/integrations/core)

---
title: Core
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Core is the native wallet SDK for the Lux blockchain."
logo: /images/core.svg
developer: Lux Network
website: https://core.app/en/
documentation: https://docs.core.app/
featured: true
---

## Overview

Core is the native wallet SDK developed by Lux Network specifically for the Lux blockchain. It provides developers with the tools needed to integrate wallet functionalities into decentralized applications (dApps) built on Lux. With Core, you can create seamless and secure user experiences, enabling users to manage their assets, interact with smart contracts, and perform transactions directly within your application.

## Features

- **Lux-Native**: Core is designed specifically for the Lux ecosystem, ensuring optimal compatibility and performance with the network.
- **Comprehensive Wallet Functions**: Core enables a wide range of wallet functionalities, including asset management, transaction signing, and interaction with Lux's L1s and smart contracts.
- **User-Friendly Interface**: Core is built to provide a smooth user experience, making it easy for users to navigate and manage their assets.
- **Security**: Core incorporates robust security measures to protect users' private keys and assets, adhering to the best practices in wallet development.
- **Cross-Platform Support**: Core SDK is available for integration across various platforms, including web, mobile, and desktop applications.

## Getting Started

To start using Core in your application, follow these steps:

1. **Visit the Core Website**: Explore the [Core website](https://core.app/en/) to learn more about its features and capabilities.
2. **Access the SDK**: Go to the [Core Documentation](https://docs.core.app/) to download the SDK and access integration guides.
3. **Integrate Wallet Functions**: Follow the integration tutorials in the documentation to add wallet functionalities such as asset management, transaction signing, and smart contract interaction to your dApp.
4. **Test and Deploy**: Test the integrated wallet features in a development environment before deploying your application on the Lux mainnet.

## Documentation

For detailed guides, API references, and integration examples, visit the [Core Documentation](https://docs.core.app/).

## Use Cases

Core can be utilized in a variety of applications within the Lux ecosystem:

- **DeFi Applications**: Enable users to manage their assets, stake tokens, and interact with DeFi protocols on Lux.
- **NFT Marketplaces**: Integrate wallet functionalities that allow users to buy, sell, and manage NFTs on the Lux network.
- **Gaming dApps**: Allow players to securely manage in-game assets, purchase items, and participate in the game economy using the Core wallet.
- **General dApps**: Any decentralized application built on Lux can integrate Core to offer users a native wallet experience for asset management and transactions.

## Conclusion

Core is a powerful and versatile wallet SDK designed for the Lux blockchain, providing developers with the tools needed to create seamless, secure, and user-friendly experiences. Whether you're building a DeFi platform, an NFT marketplace, or any other type of dApp on Lux, Core offers the essential wallet functionalities to help your application succeed.



# Covalent (/integrations/covalent)

---
title: Covalent
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: "Covalent provides comprehensive blockchain data APIs and RPC infrastructure for accessing on-chain data across multiple networks."
logo: /images/covalent.png
developer: Covalent
website: https://www.covalenthq.com/
documentation: https://www.covalenthq.com/docs/
---

## Overview

Covalent is a blockchain data infrastructure provider offering comprehensive APIs and RPC services for accessing structured on-chain data. With coverage across numerous blockchain networks including Lux, Covalent enables developers to access historical and real-time blockchain data through powerful APIs and reliable node infrastructure.

## Features

- **Unified API**: Single API for accessing data across 100+ blockchain networks.
- **Historical Data**: Complete historical blockchain data with no missing records.
- **RPC Infrastructure**: Reliable RPC nodes for direct blockchain access.
- **Real-Time Updates**: Access to current blockchain state and events.
- **Structured Data**: Pre-indexed and structured blockchain data for easy consumption.
- **Token Data**: Comprehensive token balances, transfers, and price information.
- **Transaction History**: Full transaction history for addresses and smart contracts.
- **Multi-Chain Support**: Consistent API across multiple blockchain networks.

## Documentation

For detailed guides and API documentation, visit the [Covalent Documentation](https://www.covalenthq.com/docs/).

## Use Cases

Covalent serves various blockchain development needs:

- **Wallet Applications**: Access token balances and transaction histories.
- **Analytics Platforms**: Comprehensive on-chain data for analysis and reporting.
- **DeFi Applications**: Real-time and historical DeFi protocol data.
- **Portfolio Trackers**: Multi-chain portfolio tracking and management.
- **NFT Platforms**: Access to NFT metadata and ownership information.

## Conclusion

Covalent provides robust blockchain data infrastructure and RPC services for Lux applications, offering comprehensive APIs and reliable node access for developers building data-intensive blockchain applications.



# Crossmint (/integrations/crossmint)

---
title: Crossmint
category: Enterprise Solutions
available: ["LUExchange-Chain"]
description: Crossmint is an enterprise blockchain platform providing APIs for seamless on-chain applications, supporting wallets, NFT minting, verifiable credentials, and NFT checkout with multiple payment methods.
logo: /images/crossmint.jpeg
developer: Crossmint
website: https://crossmint.com/
documentation: https://docs.crossmint.com/
---

## Overview

Crossmint is an enterprise-grade blockchain platform trusted by over 30,000 enterprises and developers. It provides all the tools and infrastructure needed to build and deploy on-chain applications quickly and efficiently. With a comprehensive set of APIs, Crossmint enables wallet creation, NFT minting, credential management, and seamless checkout processes for NFTs.

## Features

- **Wallets**: Create embedded wallets with secure enterprise-grade Multi-Party Computation (MPC). These wallets are embeddable into your website and fully interoperable.
- **NFT Minting**: Mint, distribute, edit, and burn NFTs with ease. Airdrop NFTs directly into wallets or via email using simple API calls, no-code tools, QR codes, or NFC chips.
- **Verifiable Credentials**: Issue and manage verifiable credentials at scale, ensuring anyone can easily verify them on-chain.
- **NFT Checkout**: Sell NFTs using any payment method, including credit cards, Apple Pay, Google Pay, and cross-chain tokens.

## Getting Started

To start using Crossmint, follow these steps:

1. **Sign Up**: Visit [Crossmint](https://crossmint.com/) and create an account.
2. **Set Up Your Project**: Set up wallets, NFT minting tools, and verifiable credentials for your project in the Crossmint dashboard.
3. **Get API Key**: Obtain your API key to authenticate requests and integrate Crossmint's services into your application.
4. **Integration**: Use Crossmint's APIs or no-code tools to enable wallets, NFT checkout, and credential management in your app or website.

## Documentation

For detailed setup instructions, API references, and more, visit the [Crossmint Documentation](https://docs.crossmint.com/).

## Use Cases

Crossmint is ideal for:

- **NFT Marketplaces**: Easily mint, sell, and manage NFTs using multiple payment methods, including credit cards and cross-chain tokens.
- **Enterprises**: Manage and issue verifiable on-chain credentials at scale.
- **Developers**: Seamlessly integrate secure wallets, NFT minting, and checkout features into your applications.

## Conclusion

Crossmint simplifies blockchain development for enterprises and developers with its fully integrated suite of APIs. Whether you're looking to create NFTs, manage wallets, or sell NFTs with fiat payments, Crossmint provides all the infrastructure you need to build robust on-chain applications in minutes.

# Cubist (/integrations/cubist)

---
title: Cubist
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: Low-latency API for generating keys and signing transactions inside secure hardware.
logo: /images/cubist.svg
developer: Cubist
website: https://cubist.dev/
documentation: https://cubist.dev/ 
---

## Overview

Cubist is a high-performance wallet SDK that provides a low-latency API for generating cryptographic keys and signing blockchain transactions within secure hardware environments. Designed for developers who require enhanced security and efficiency, Cubist leverages hardware security modules (HSMs) and secure enclaves to protect private keys and ensure that sensitive operations are performed within a trusted execution environment. This makes Cubist an ideal solution for building secure decentralized applications (dApps) and blockchain platforms.

## Features

- **Hardware Security**: Cubist ensures that all key generation and transaction signing are performed within secure hardware, such as HSMs or secure enclaves, providing robust protection against attacks.
- **Low-Latency API**: The API is optimized for speed, offering low-latency interactions with secure hardware, which is crucial for performance-sensitive applications.
- **Flexible Integration**: Cubist supports multiple blockchain networks and can be integrated into various platforms, including web, mobile, and desktop applications.
- **Scalability**: Designed to handle high transaction volumes, Cubist is suitable for applications that require both security and scalability.
- **Compliance**: The use of secure hardware ensures that your application meets stringent security and compliance requirements, making Cubist ideal for enterprise-grade solutions.

## Getting Started

To get started with Cubist, follow these steps:

1. **Visit the Cubist Website**: Explore the [Cubist website](https://cubist.dev/) to understand its offerings, architecture, access the SDK, and find the latest documentation.
2. **Integrate Secure Key Management**: Use the guides and documentation found on the Cubist website to integrate Cubist's key management and transaction signing capabilities into your application, ensuring all operations are conducted within secure hardware.
3. **Optimize for Performance**: Leverage Cubist's low-latency API to ensure your application maintains high performance, even when handling large volumes of transactions.
4. **Test and Deploy**: After integrating and testing the SDK in a development environment, deploy your application with confidence, knowing that it meets high-security standards.

## Documentation

For detailed guides, API references, and step-by-step integration tutorials, please visit the main [Cubist website](https://cubist.dev/) and navigate to their documentation section.

## Use Cases

Cubist can be utilized in a variety of applications that require secure key management and transaction signing:

- **Enterprise Blockchain Applications**: Protect sensitive operations in enterprise blockchain solutions by leveraging secure hardware for key management.
- **DeFi Platforms**: Enhance the security of decentralized finance (DeFi) applications by ensuring that all transaction signing occurs within a secure enclave.
- **Cryptocurrency Wallets**: Build secure cryptocurrency wallets that offer users peace of mind by protecting their private keys within hardware security modules.
- **Regulated Industries**: Meet regulatory requirements in industries such as finance and healthcare by integrating Cubist's secure transaction signing and key management.

## Conclusion

Cubist offers a robust and secure solution for developers looking to integrate low-latency, hardware-based key management and transaction signing into their applications. With its focus on security, performance, and scalability


# DeFi Llama (/integrations/defilama)

---
title: DeFi Llama
category: Analytics & Data
available: ["LUExchange-Chain", "All Lux L1s"]
description: "DeFi Llama is a transparent and open-source DeFi analytics platform providing comprehensive data for Lux protocols and tokens."
logo: /images/defilama.jpeg
developer: DeFi Llama
website: https://defillama.com/
documentation: https://docs.llama.fi/
---

## Overview

DeFi Llama is the largest TVL (Total Value Locked) aggregator for DeFi protocols, providing transparent and comprehensive data for the Lux ecosystem. It offers real-time analytics, tracking TVL, yields, stablecoin data, and protocol metrics across multiple chains, with a particular focus on accuracy and transparency.

## Features

- **TVL Tracking**: Real-time monitoring of Total Value Locked across Lux protocols.
- **Yield Analytics**: Comprehensive yield farming opportunities tracking on Lux.
- **Protocol Insights**: Detailed metrics for individual protocols and their performance.
- **Stablecoin Data**: Track stablecoin circulation and usage across Lux.
- **Open Source**: Transparent methodology with community-driven updates.
- **API Access**: Free and comprehensive API for developers and analysts.
- **DEX Analytics**: Track volume, liquidity, and other metrics for Lux DEXs.

## Getting Started

To use DeFi Llama for Lux analytics:

1. **Visit Platform**: Go to [DeFi Llama](https://defillama.com/).
2. **Explore Lux**: Navigate to the Lux chain section for ecosystem-specific data.
3. **Track Protocols**: Monitor your favorite Lux protocols' performance and TVL.
4. **Access APIs**: For developers, integrate DeFi Llama's data using their comprehensive API.

## Documentation

For detailed API documentation and integration guides, visit the [DeFi Llama Documentation](https://docs.llama.fi/).

## Use Cases

DeFi Llama serves various analytical needs:

- **Market Research**: Track protocol growth and market trends on Lux.
- **Investment Analysis**: Compare yields and TVL across different protocols.
- **Risk Assessment**: Monitor protocol health and market dynamics.
- **Development**: Integrate DeFi analytics into your applications via API.
- **Protocol Comparison**: Compare performance across different chains and protocols.

## Conclusion

DeFi Llama provides essential analytics and insights for the Lux ecosystem, offering transparent and comprehensive data crucial for users, developers, and analysts. Whether you're tracking TVL, researching yields, or analyzing protocol performance, DeFi Llama delivers reliable and up-to-date information for the Lux DeFi landscape.


# DexGuru (/integrations/dexguru)

---
title: DexGuru
category: Explorers
available: ["LUExchange-Chain"]
description: "DexGuru is a DeFi analytics platform providing real-time trading data, token analysis, and transaction exploration across DEXs."
logo: /images/dexguru.png
developer: DexGuru
website: https://dex.guru/
documentation: https://docs.dex.guru/
---

## Overview

DexGuru is a comprehensive DeFi analytics and trading platform that combines block explorer functionality with real-time DEX trading data. Providing insights across multiple chains including Lux, DexGuru enables traders and analysts to track tokens, analyze trading patterns, and explore on-chain DeFi activity through an intuitive interface.

## Features

- **DEX Analytics**: Real-time trading data across decentralized exchanges
- **Token Explorer**: Comprehensive token information and metrics
- **Wallet Tracking**: Monitor wallet activity and holdings
- **Trading Interface**: Execute trades directly through the platform
- **Price Charts**: Advanced charting with technical analysis tools
- **Multi-Chain Support**: Analytics across Lux and other networks

## Getting Started

To use DexGuru:

1. **Visit DexGuru**: Access [DexGuru](https://dex.guru/)
2. **Select Lux**: Choose Lux network from supported chains
3. **Explore Tokens**: Search for tokens and view analytics
4. **Track Wallets**: Add wallets to track activity
5. **Trade**: Execute trades through integrated DEX aggregation

## Documentation

For platform guides, visit [DexGuru Documentation](https://docs.dex.guru/).

## Use Cases

- **Token Analysis**: Research tokens with comprehensive on-chain data
- **Trading**: Access DEX trading with real-time analytics
- **Wallet Monitoring**: Track whale and notable wallet activity
- **Market Research**: Analyze DeFi trading patterns and trends

## Conclusion

DexGuru provides powerful DeFi exploration and analytics for Lux, combining block explorer features with real-time trading data and analysis capabilities.


# DEX Screener (/integrations/dexscreener)

---
title: DEX Screener
category: Token Aggregators
available: ["LUExchange-Chain", "All Lux L1s"]
description: "DEX Screener provides real-time analytics and trading data for decentralized exchanges on Lux, offering comprehensive market insights and trading pair analysis."
logo: /images/dexscreener.png
developer: DEX Screener
website: https://dexscreener.com/
documentation: https://docs.dexscreener.com/
---

## Overview

DEX Screener is a powerful analytics platform that provides real-time data and insights for decentralized exchanges on Lux. It offers comprehensive trading pair analysis, price charts, liquidity information, and market metrics, making it an essential tool for traders and investors in the Lux ecosystem.

## Features

- **Real-Time Charts**: Live price and volume charts for all trading pairs on Lux DEXs.
- **Multi-DEX Support**: Track pairs across multiple Lux DEXs simultaneously.
- **Price Alerts**: Set custom alerts for price movements and trading volume.
- **Liquidity Analysis**: Deep insights into liquidity pools and movements.
- **Trading Pair Analytics**: Detailed metrics including volume, liquidity, and price changes.
- **Market Sentiment**: Track social metrics and trading patterns.
- **API Access**: Professional-grade API for developers and traders.

## Getting Started

To begin using DEX Screener:

1. **Access Platform**: Visit [DEX Screener](https://dexscreener.com/).
2. **Select Network**: Choose Lux to view LUExchange-Chain pairs.
3. **Analyze Pairs**: 
   - Search for specific trading pairs
   - View real-time charts and metrics
   - Set up custom watchlists
4. **Configure Alerts**: Set up price and volume notifications for tracked pairs.

## Documentation

For API documentation and integration guides, visit the [DEX Screener Documentation](https://docs.dexscreener.com/).

## Use Cases

DEX Screener serves various analytical needs:

- **Trading Analysis**: Real-time market analysis and trading pair monitoring.
- **Liquidity Tracking**: Monitor liquidity depths and movements across DEXs.
- **Market Research**: Analyze new tokens and trading pairs on Lux.
- **Portfolio Management**: Track multiple pairs and set alerts for price movements.
- **Development Integration**: Build trading tools using the DEX Screener API.

## Conclusion

DEX Screener provides essential trading analytics and market insights for the Lux DeFi ecosystem. With its comprehensive feature set and real-time data across multiple DEXs, it serves as a crucial tool for traders, investors, and developers operating in the Lux marketplace.


# DIA (/integrations/dia)

---
title: DIA
category: Oracles
available: ["LUExchange-Chain"]
description: DIA is an open-source oracle platform that provides transparent, crowd-verified price oracles for DeFi applications.
logo: /images/DIA.png
developer: DIA
website: https://diadata.org/
documentation: https://docs.diadata.org/
---

## Overview

DIA (Decentralized Information Asset) is an open-source oracle platform designed to deliver transparent, crowd-verified data feeds for decentralized finance (DeFi) applications. By leveraging community-driven data collection and validation, DIA ensures that its price oracles are accurate, reliable, and tamper-resistant. This makes DIA an essential tool for developers looking to integrate secure and trustworthy data into their DeFi protocols and smart contracts.

## Features

- **Open-Source Platform**: DIA's data feeds and infrastructure are fully open-source, allowing developers to inspect, contribute to, and customize the platform according to their needs.
- **Crowd-Verified Data**: Data is sourced, validated, and verified by the community, ensuring transparency and reducing the risk of manipulation.
- **Multi-Chain Support**: DIA provides oracles that are compatible with multiple blockchain networks, including Ethereum, Binance Smart Chain, and more.
- **Customizable Oracles**: Developers can create custom data feeds tailored to specific use cases, ensuring that the data meets their exact requirements.
- **DeFi Focused**: DIA's oracles are specifically designed for DeFi applications, providing accurate price feeds and other financial data essential for the operation of decentralized financial products.

## Getting Started

To integrate DIA into your DeFi application, follow these steps:

1. **Explore DIA**: Visit the [DIA website](https://diadata.org/) to learn more about the platform and its offerings.
2. **Access the Documentation**: Refer to the [DIA Documentation](https://docs.diadata.org/) to get started with the integration process, including API usage and custom oracle creation.
3. **Set Up Data Feeds**: Follow the documentation to integrate DIA's price oracles into your DeFi application, ensuring reliable and transparent data inputs.
4. **Customize Oracles**: Use DIA's tools to create custom oracles that meet the specific needs of your application, whether it's a unique price feed or another type of financial data.
5. **Deploy and Monitor**: After integration, deploy your application and continuously monitor the performance and accuracy of the data feeds provided by DIA.

## Documentation

For detailed integration guides, API references, and customization options, visit the [DIA Documentation](https://docs.diadata.org/).

## Use Cases

DIA is particularly suited for a wide range of DeFi applications that require reliable and transparent data:

- **Lending and Borrowing Platforms**: Use DIA's price oracles to provide accurate asset valuations, ensuring fair lending and borrowing conditions.
- **Decentralized Exchanges (DEXs)**: Integrate DIA to power your DEX with real-time, crowd-verified price feeds, enhancing trade accuracy.
- **Stablecoins**: Utilize DIA's oracles to maintain accurate price pegs by feeding reliable data into the smart contracts governing stablecoins.
- **Derivatives Markets**: DIA can be used to provide the necessary financial data for creating and managing decentralized derivatives products.

## Conclusion

DIA is a powerful tool for DeFi developers, offering transparent, reliable, and customizable oracles that are essential for the integrity and success of decentralized financial applications. Whether you're building a lending platform, a DEX, or any other type of DeFi product, DIA provides the data infrastructure you need to ensure your application operates smoothly and securely.



# Dinari (/integrations/dinari)

---
title: Dinari
category: Tokenization Platforms
available: ["LUExchange-Chain"]
description: Dinari provides tokenized access to U.S. public equities for non-U.S. retail investors through a B2B2C model, partnering with neobanks and fintech platforms to offer regulated blockchain-based stock exposure.
logo: /images/dinari.svg
developer: Dinari
website: https://www.dinari.com/
documentation: https://www.dinari.com/how-it-works
---

## Overview

Dinari is building the infrastructure to provide non-U.S. retail investors with tokenized access to U.S. public equities through blockchain technology. Operating through a B2B2C (business-to-business-to-consumer) model, Dinari partners with neobanks, fintech applications, and embedded finance platforms that want to offer their customers regulated exposure to U.S. stocks using blockchain-based infrastructure.

By tokenizing shares of U.S. public companies, Dinari enables international investors to gain access to American stock markets through their local platforms without the complexity and cost barriers of traditional cross-border brokerage. Each token represents economic exposure to actual shares held in custody, providing users with the investment performance of U.S. equities combined with the efficiency, programmability, and 24/7 availability of blockchain technology.

## Features

- **Tokenized U.S. Equities**: Access to major U.S. public stocks as blockchain-based tokens.
- **B2B2C Distribution**: Partner with local platforms rather than directly serving end consumers.
- **Non-U.S. Focus**: Specifically designed for international retail investors outside the United States.
- **Regulatory Compliance**: Fully compliant structure for offering U.S. equity exposure across jurisdictions.
- **Real Share Backing**: Tokens represent economic rights to actual shares held in regulated custody.
- **Fractional Ownership**: Enable fractional share purchases through tokenization.
- **24/7 Trading**: Potential for around-the-clock trading depending on partner platform implementation.
- **Blockchain Efficiency**: Leverage blockchain for instant settlement, programmability, and reduced costs.
- **White-Label Integration**: Platform partners can offer tokens under their own brand.
- **Multi-Chain Support**: Deploy tokens across multiple blockchain networks.
- **API Integration**: Comprehensive APIs for platform partners to integrate equity tokens.
- **Corporate Actions**: Automatic handling of dividends, splits, and other corporate actions.
- **Transparent Pricing**: Clear fee structure for token purchase, holdings, and redemptions.
- **Custody and Safety**: Underlying shares held by regulated custodians.

## Getting Started

### For Platform Partners (Neobanks, Fintechs, Embedded Finance):

1. **Partnership Discussion**: Contact Dinari to explore partnership opportunities for your platform.

2. **Platform Assessment**: Evaluate fit for your user base:
   - Confirm your users are primarily non-U.S. residents
   - Assess demand for U.S. equity exposure
   - Review regulatory requirements in your operating jurisdictions
   - Determine integration approach and timeline

3. **Legal and Compliance**: Work with Dinari on legal structure:
   - Establish compliant offering structure for your markets
   - Navigate local securities regulations
   - Set up necessary licensing or partnerships
   - Implement KYC/AML procedures

4. **Technical Integration**: Integrate Dinari's technology:
   - Connect to Dinari's APIs for token issuance and redemption
   - Integrate with your platform's wallet infrastructure
   - Implement user interfaces for equity token trading
   - Test in sandbox environment
   - Ensure corporate actions handling

5. **Launch**: Go live with tokenized U.S. equities:
   - Offer selected U.S. stocks as tokens to your users
   - Enable users to buy, hold, and sell equity tokens
   - Provide transparent reporting on holdings and performance
   - Handle customer support with Dinari's assistance

### For Investors:

1. Access Dinari-powered equity tokens through partner platforms in your region
2. Complete KYC with your platform
3. Fund your account through local payment methods
4. Purchase tokenized U.S. stocks available on the platform
5. Hold tokens in your wallet or custody solution
6. Receive dividends and benefits of underlying shares
7. Sell or redeem tokens as needed

## Lux Support

Dinari's multi-chain architecture supports deployment across various blockchain networks. As an EVM-compatible platform, Lux LUExchange-Chain provides an excellent environment for Dinari's tokenized equities, offering high throughput, low transaction costs, and fast finality—ideal characteristics for equity token trading and settlement.

## Supported Equities

Dinari provides tokenized access to major U.S. public companies:

- **Technology Stocks**: Leading tech companies like Apple, Microsoft, Google, Amazon, Meta, Tesla
- **Financial Services**: Major banks and financial institutions
- **Healthcare**: Pharmaceutical and healthcare companies
- **Consumer**: Consumer goods and retail companies
- **Industrial**: Manufacturing and industrial companies
- **Energy**: Energy and resource companies

The specific list of available tokenized equities may vary by platform partner and jurisdiction.

## Use Cases

Dinari's infrastructure serves multiple platform types:

**Neobanks**: Digital banks can offer customers investment capabilities in U.S. stocks without building brokerage infrastructure.

**Fintech Apps**: Consumer fintech applications can add U.S. equity investing as a feature.

**Crypto Exchanges**: Cryptocurrency exchanges can expand offerings to include tokenized stocks.

**Embedded Finance Platforms**: Platforms offering embedded financial services can integrate equity investing.

**Wealth Management Apps**: Digital wealth managers can provide U.S. market exposure to international clients.

**Investment Platforms**: International investment platforms can offer U.S. stocks to their user base.

## Platform Partner Benefits

**Turnkey Solution**: Dinari handles legal structure, custody, corporate actions, and blockchain infrastructure.

**Regulatory Compliance**: Compliant framework reduces regulatory burden on platform partners.

**Market Expansion**: Add popular U.S. stocks to platform offerings without brokerage licensing.

**Revenue Opportunity**: Share in revenue from user trading and holdings.

**Quick Integration**: API-based integration enables faster time to market.

**White-Label**: Offer equity tokens under your own brand and user experience.

**No Custody Burden**: Dinari manages underlying share custody and corporate actions.

**Blockchain Benefits**: Leverage blockchain efficiency while offering traditional assets.

## Investment Benefits for End Users

**Access to U.S. Markets**: Invest in American companies from anywhere in the world.

**Lower Barriers**: Reduced minimum investments through fractional tokenization.

**Local Platform**: Access through familiar local platforms in local languages.

**Blockchain Efficiency**: Faster settlement and potentially lower costs than traditional brokers.

**Fractional Shares**: Buy small portions of expensive stocks.

**Transparent Ownership**: Clear blockchain-based record of token holdings.

**Potential 24/7 Trading**: Ability to trade outside traditional market hours (platform dependent).

## Legal and Compliance Structure

Dinari maintains comprehensive compliance:

- **Securities Compliance**: Tokens structured as compliant securities or derivatives
- **Multi-Jurisdictional**: Frameworks adaptable to different international regulations
- **U.S. Securities Laws**: Proper structure for exposure to U.S. equities
- **Custody Regulations**: Underlying shares held by regulated custodians
- **AML/KYC**: Integrated compliance processes through platform partners
- **Corporate Actions**: Legally compliant handling of dividends, splits, and proxy voting
- **Regular Audits**: Third-party audits of share backing and operations

## Technology Infrastructure

Dinari provides comprehensive technology:

- **Token Issuance**: Smart contracts for minting and burning equity tokens
- **APIs**: RESTful APIs for platform integration
- **Multi-Chain**: Deploy tokens across multiple blockchains
- **Oracle Integration**: Price feeds for accurate token valuations
- **Corporate Actions Engine**: Automated handling of dividends and other events
- **Custody Interface**: Connection to regulated custodians holding underlying shares
- **Compliance Layer**: Smart contract-based restrictions for regulatory compliance
- **Reporting**: Tools for transparency and regulatory reporting

## Pricing

Dinari offers competitive pricing for platform partners:

- **Partnership Fees**: Revenue sharing arrangements with platform partners
- **Token Fees**: Fees on token issuance and redemptions
- **Management Fees**: Potential annual fees on tokenized holdings
- **Platform Integration**: Setup and ongoing platform access fees
- **Custom Structures**: Tailored pricing for large partners

Contact Dinari for specific pricing based on your platform and expected volumes.

## Backing and Trust

**Regulated Custody**: Underlying U.S. shares held by regulated custodians.

**Real Share Backing**: Each token economically represents actual shares, not derivatives or synthetic exposure.

**Transparent Operations**: Regular attestations and disclosures of share backing.

**Experienced Team**: Leadership with backgrounds in traditional finance, fintech, and blockchain.

**Compliance First**: Regulatory compliance built into the model from inception.

## Competitive Advantages

**International Focus**: Purpose-built for non-U.S. investors, not U.S. retail market.

**B2B2C Model**: Partner with existing platforms rather than competing with them.

**Regulatory Expertise**: Navigated complex cross-border securities regulations.

**Blockchain-Native**: Built for blockchain from the ground up, not adapting legacy systems.

**Fractional Access**: Tokenization enables fractional ownership of any U.S. stock.

**Corporate Actions**: Automated handling reduces operational complexity for partners.

**Multi-Chain**: Flexibility to deploy where partner platforms operate.

## Conclusion

Dinari is democratizing access to U.S. public equities for international investors by combining the power of tokenization with a B2B2C distribution model. By partnering with neobanks, fintech platforms, and embedded finance providers, Dinari enables millions of non-U.S. investors to gain exposure to American stocks through local platforms they already trust and use. With proper regulatory structures, real share backing, and blockchain efficiency, Dinari provides the infrastructure that bridges traditional U.S. equity markets with the global digital economy. Platform partners on networks like Lux can leverage Dinari's technology to offer their users a differentiated investment product that was previously difficult or impossible to provide, creating new revenue opportunities while serving customer demand for U.S. market access.



# DipDup (/integrations/dipdup)

---
title: DipDup
category: Indexers
available: ["LUExchange-Chain"]
description: DipDup is a Python framework for building smart contract indexers. It helps developers focus on business logic instead of writing boilerplate code to store and serve data.
logo: /images/dipdup.png
developer: DipDup
website: https://dipdup.io/
documentation: https://dipdup.io/docs
---

## Overview

DipDup is a Python-based framework specifically designed for building smart contract indexers. It simplifies the development process by allowing developers to concentrate on business logic without needing to write extensive boilerplate code for data storage and retrieval. DipDup is ideal for creating scalable and efficient indexers on the Lux LUExchange-Chain.

## Features

- **Python Framework**: Leverage the power and simplicity of Python to build custom smart contract indexers quickly.
- **Focus on Business Logic**: DipDup handles the heavy lifting of data storage and serving, enabling developers to focus on implementing their specific business logic.
- **Scalable Indexing**: Easily scale your indexing solutions to handle increasing data and transaction volumes.
- **Customizability**: DipDup offers flexibility, allowing developers to customize their indexers to meet specific project needs.

## Getting Started

To start using DipDup:

1. **Visit the DipDup Website**: Explore the [DipDup website](https://dipdup.io/) to learn more about the framework.
2. **Access the Documentation**: Refer to the [DipDup Documentation](https://dipdup.io/docs) for step-by-step guides on setting up and using DipDup.
3. **Set Up Your Indexer**: Follow the documentation to set up a custom smart contract indexer using DipDup.
4. **Implement Business Logic**: Focus on implementing your specific business logic while DipDup handles the data management.
5. **Deploy on LUExchange-Chain**: Utilize DipDup to deploy and manage your indexer on the Lux LUExchange-Chain.

## Documentation

For comprehensive guides and tutorials, visit the [DipDup Documentation](https://dipdup.io/docs).

## Use Cases

DipDup is suitable for:

- **Blockchain Developers**: Build efficient and scalable smart contract indexers on the Lux LUExchange-Chain.
- **Data-Intensive Applications**: Simplify the indexing process for applications that require robust data storage and retrieval mechanisms.
- **Custom Indexer Development**: Tailor your indexers to meet the unique requirements of your blockchain projects.

## Conclusion

DipDup is a powerful and flexible Python framework that streamlines the creation of smart contract indexers. By handling the complexities of data storage and serving, DipDup allows developers to focus on building and deploying business logic, making it an essential tool for projects on the Lux LUExchange-Chain.



# dKiT API/SDK (/integrations/dkit)

---
title: dKiT API/SDK
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: "dKit is a production-ready cross-chain DEX aggregation API/SDK that enables native swaps across 15+ blockchains including Lux by routing liquidity through THORChain, Chainflip, Maya, Jupiter, Garden and 1inch."
logo: /images/dkit.png
developer: dKit Team
website: https://dkit.xyz/
documentation: https://docs.dkit.xyz/
---

## Overview

dKiT is a unified cross-chain DEX aggregation layer that lets dApps execute **native** token swaps across 19+ blockchains including Lux’s LUExchange-Chain—via a single API/SDK. It abstracts multiple protocols and aggregators behind one interface, providing best-price discovery, non-custodial execution, and real-time tracking.

## Features

- **Native Cross-Chain Swaps**: Swap native assets (e.g. BTC ↔ LUX).  
- **Smart Routing**: Finds optimal routes across multiple protocols and DEX aggregators. 
- **Streaming Swaps**: Splits large trades to reduce price impact. 
- **One-Transaction UX**: “One-signature” Cross-Chain Swaps.  
- **Revenue & Fee Streaming**: Add custom affiliate fees and automatically stream them to your wallets.  
- **Broad Wallet Support**: Easily integrate 20+ wallets (EVM, Solana, Cosmos, hardware, and WalletConnect). 
- **Lux Support**: Support for Lux (LUExchange-Chain) cross-chain swaps.

## Getting Started

1. **Review the Docs**  
   Browse the [dKit Documentation](https://docs.dkit.xyz/) to understand concepts, endpoints, and workflows.

2. **Get an API Key**  
   Request API keys on [dkit.xyz](https://dkit.xyz/get-api-key) → **Get API Key**.

3. **Install & Configure**  
   - Use the SDK (e.g., `@doritokit/sdk`) or call the REST API directly.  
   - Provide any required API keys (e.g., EVM explorers or UTXO helpers).  
   - Enable Lux (LUExchange-Chain) within your chain list.

4. **Quote → Execute → Track**  
   - Call `/v1/quote` to get the best route and expected output.  
   - Execute the transaction 
   - Poll `/v1/track` to monitor progress, including streaming status.

5. **Monetize**  
   Configure **affiliate fees** so a share of volume routed via your app is streamed to your addresses.

## Documentation

- **Introduction & Concepts**: [docs.dkit.xyz](https://docs.dkit.xyz/)  
- **API Reference / Swagger**: [api.dkit.xyz](https://api.dkit.xyz)  
- **Quick Start**: End-to-end example for quoting, executing, and tracking swaps  
- **Revenue Generation**: [docs.dkit.xyz/revenue-generation](https://docs.dkit.xyz/revenue-generation)  
- **Status Page**: [dkit.instatus.com](https://dkit.instatus.com)

## Supported Protocols & Aggregators

- **THORChain** 
- **Chainflip**   
- **MayaChain**   
- **Jupiter**  
- **1inch**  
- **Garden Finance** 

## Use Cases

- **Cross-Chain Swaps in Any dApp**: Add native BTC ↔ EVM/Solana/Cosmos swaps to wallets and DEXs. 
- **Cross-Chain DEX / Router**: Power a trading interface with best-price discovery and cross-chain support.  
- **Bridgeless Asset Migration**: Let users move assets across ecosystems without using wrapped tokens or CEXs.    
- **Affiliate Monetization**: Stream fees on every swaps.

## Conclusion

dKit delivers a reliable, developer-friendly cross-chain aggregation layer for Lux’s LUExchange-Chain and beyond. With native swaps, smart routing and fee monetization, it’s a fast way to ship a seamless cross-chain experience in production.


# Dreamspace (/integrations/dreamspace)

---
title: Dreamspace
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: Dreamspace is a drag and drop vibe coding canvas that lets anyone build apps and deploy smart contracts on any EVM-compatible chain. 
logo: /images/dreamspace.jpg
developer: Dreamspace
website: https://dreamspace.xyz
documentation: https://docs.makeinfinite.com/docs/getting-started
---

## Overview
Dreamspace is redefining the way decentralized applications (dApps) are built by merging AI-powered development tools with no-code accessibility. As a leading vibe coding studio, it empowers creators, developers, and entrepreneurs to transform ideas into fully functional Web3 applications without the steep learning curve of traditional coding. Whether you’re building DeFi protocols, NFT platforms, DAOs, or blockchain analytics dashboards, Dreamspace provides the tools to go from concept to deployment seamlessly.

## Key Features

- **AI-Powered Smart Contract Generation**: Build and deploy secure contracts for DeFi, NFTs, or DAOs without writing code.
- **Prompt-to-SQL Queries**: Query indexed blockchain data in natural language, unlocking real-time analytics and data-driven dApps with minimal effort.
- **Visual Drag-and-Drop Builder**: Assemble contracts, queries, and UI components in an intuitive canvas to create full-stack dApps.
- **Native Data Integration**:  Powered by Space and Time’s ZK-proven data warehouse, enabling advanced data visualization and interaction for onchain apps.
- **No-Code Accessibility**: Lowers barriers for creators of all skill levels, making blockchain development more inclusive.

## Getting Started:

1. **Launch Your Project**: Start from a blank project or describe your app idea, then click “Start Creating” on the homepage.

2. **Select a Component**: – Click the element you want to edit; it will be highlighted with a pink border and shown as Selected in the chatbot.

3. **Edit with AI**: In canvas edit mode, type a request (e.g., “change the background to blue”) into the chatbot and press enter. Wait for Dreamspace AI to apply changes.

4. **Refine & Adjust**: Use undo/redo, resize, or move components directly in the canvas.

5. **Style Your App**: Customize colors, fonts, and layouts under the “Themes” tab in the chatbot.

6. **Enhance with Data & Integrations**: Add SQL queries, charts, third-party APIs, or connect smart contracts to bring your dApp to life.

## Documentation:

For detailed documentation on how to get started, visit [here](https://docs.makeinfinite.com/docs/getting-started)

## Use Cases

Dreamspace is ideal for; 

- **DeFi Protocols**: Launch staking platforms, lending apps, or liquidity pools without deep blockchain coding.

- **NFT Platforms**: Build marketplaces, rarity trackers, or minting sites powered by AI-generated contracts.

- **DAOs**: Create governance tools, voting systems, and treasury management apps with ease.

- **Blockchain Analytics Dashboards** Query and visualize onchain data using natural language (Prompt-to-SQL).

- **Rapid dApp Prototyping**: Turn ideas into functional applications quickly with drag-and-drop editing and AI-powered customization.

 ## Conclusion

With Dreamspace, anyone can seamlessly build and deploy apps on EVM chains—including Lux—without writing a single line of code.

  


# DSRV (/integrations/dsrv)

---
title: DSRV
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "DSRV is a blockchain infrastructure company providing institutional-grade validator services and Web3 development tools."
logo: /images/dsrv.png
developer: DSRV
website: https://www.dsrvlabs.com/
---

## Overview

DSRV is a leading blockchain infrastructure company providing institutional-grade validator services, staking solutions, and Web3 development tools. As one of the most trusted infrastructure providers in Asia, DSRV operates validators across 40+ blockchain networks including Lux, serving institutional clients and the broader Web3 ecosystem with reliable, secure infrastructure.

## Features

- **Professional Validation**: Institutional-grade validator operations for Lux
- **WELLDONE Studio**: Comprehensive Web3 development IDE and tools
- **Multi-Chain Expertise**: Deep experience across 40+ blockchain networks
- **High Reliability**: Enterprise-grade infrastructure with high availability
- **Security Focus**: Robust security practices for institutional requirements
- **Developer Tools**: Tools and services for Web3 application development

## Getting Started

To use DSRV's services:

1. **Visit DSRV**: Explore services at [DSRV Labs](https://www.dsrvlabs.com/)
2. **Choose Service**: Select validator, staking, or developer tools
3. **Contact Team**: Reach out for institutional services or enterprise needs
4. **Integration**: Implement DSRV's services in your operations
5. **Operations**: Manage through DSRV's platform and dashboards

## Use Cases

- **Institutional Validation**: Run professional Lux validators
- **Staking Services**: Provide staking solutions for institutions
- **Developer Infrastructure**: Use WELLDONE tools for Web3 development
- **L1 Validation**: Validate Lux L1 networks

## Conclusion

DSRV provides institutional-grade blockchain infrastructure with deep multi-chain expertise, enabling professional participation in Lux network validation and Web3 development.


# Due (/integrations/due)

---
title: Due
category: Payments
available: ["LUExchange-Chain"]
description: Due is a blockchain-based payment network enabling instant, low-cost peer-to-peer and business payments with cryptocurrency and stablecoin support.
logo: /images/due.png
developer: Due Network
website: https://due.network/
documentation: https://due.network/docs
---

## Overview

Due is an innovative blockchain-based payment network designed to facilitate instant, low-cost transactions for both peer-to-peer and business payments. By leveraging blockchain technology and supporting cryptocurrencies and stablecoins, Due provides an alternative to traditional payment networks with faster settlement, lower fees, and global accessibility without the need for traditional banking infrastructure.

The platform enables users and businesses to send and receive payments instantly across borders, accept payments in multiple currencies including stablecoins, and access financial services without the friction and costs associated with conventional payment systems.

## Features

- **Instant Payments**: Real-time payment processing and settlement.
- **Low Transaction Costs**: Minimal fees compared to traditional payment processors.
- **Cryptocurrency Support**: Accept and send payments in multiple cryptocurrencies.
- **Stablecoin Integration**: Use stablecoins for price-stable transactions.
- **Cross-Border Payments**: Send money internationally without traditional banking delays.
- **Peer-to-Peer Transfers**: Direct user-to-user payments without intermediaries.
- **Business Payments**: Tools for merchants to accept crypto payments.
- **Multi-Chain Support**: Compatible with multiple blockchain networks including Lux.
- **No Chargebacks**: Blockchain-based finality eliminates chargeback fraud.
- **Global Accessibility**: Access financial services from anywhere with internet connection.
- **Simple Integration**: APIs and tools for easy merchant integration.
- **Mobile-Friendly**: Mobile-optimized payment experience.

## Getting Started

To use or integrate Due:

1. **Create Account**: Sign up on the Due platform.

2. **For Individual Users**:
   - Set up your payment wallet
   - Fund account with cryptocurrency or stablecoins
   - Send and receive payments instantly
   - Manage your transaction history

3. **For Businesses**:
   - Register as a merchant
   - Integrate payment acceptance tools
   - Configure payment methods and currencies
   - Start accepting crypto payments from customers

4. **Integration**:
   - Access Due's APIs for custom integrations
   - Implement payment widgets or checkout flows
   - Test in sandbox environment
   - Go live with crypto payment acceptance

## Lux Support

Due's multi-chain architecture includes support for Lux LUExchange-Chain, enabling users and businesses to leverage Lux's high-performance infrastructure for fast, low-cost payments with LUX and Lux-based stablecoins.

## Use Cases

**E-Commerce**: Accept crypto payments for online stores with instant settlement.

**Freelancer Payments**: Pay freelancers and contractors globally without high fees.

**Remittances**: Send money internationally with lower costs than traditional services.

**Peer-to-Peer**: Transfer funds directly between users instantly.

**Business Services**: Accept payments for services in cryptocurrency.

**Digital Goods**: Sell digital products with crypto payment options.

## Conclusion

Due provides a blockchain-based payment network that offers faster, cheaper alternative to traditional payment systems, supporting both peer-to-peer and business use cases with cryptocurrency and stablecoin integration on networks like Lux.



# Dynamic (/integrations/dynamic)

---
title: Dynamic
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: Dynamic simplifies the creation of multi-chain experiences with its customizable suite of tools, offering onboarding, embedded wallets, efficient authentication, and scalable user management.
logo: /images/dynamic.png
developer: Dynamic
website: https://www.dynamic.xyz/
documentation: https://docs.dynamic.xyz/
---

## Overview

Dynamic provides the simplest way for developers to onboard their users to their apps, whether they are a crypto enthusiast or newcomer to the space. Dynamic achieves this through offering a growing suite of tools catered to embedded wallets, authentication, multi-chain experiences, and user management.

## Features

- Embedded Wallets: Spin up flexible, non-custodial embedded wallets, and focus on building experiences that matter. Abstract the complexity of crypto away from users, and onboard them with familiar and customizable UX.
- Authentication: Dynamic provides secure and seamless authentication, with the ability for end-users to protect their wallets further with Passkeys, MFA, one-time codes, and more.
- Multi-Chain Wallet Adaptor: Through Dynamic, end-users can connect hundreds of different wallets across EVM, Solana, Bitcoin, Starknet, and more. We support more chains and wallets than any other Web3 auth provider. Additionally, users can get started with SMS, email, or familiar social login options.
- User Management Solution: Dynamic allows developers to assign their end-users roles & permissions, present custom onboarding flows, and manage everything through a robust dashboard.

And much more - try it all out for yourself in [Dynamic's live demo](https://demo.dynamic.xyz/)!

## Getting Started

1. Access our Documentation: Our [best-in-class docs](https://docs.dynamic.xyz/) provide all of the information developers need to get started building with Dynamic.
2. Get started on your own: Create a free account [here](https://app.dynamic.xyz) to explore Dynamic’s powerful developer dashboard and capabilities.
3. Talk with our team: Set up a time to [meet with our team](https://www.dynamic.xyz/talk-to-us) and discuss what’s possible with Dynamic.
4. Try out our live demo: Through [our demo environment](https://demo.dynamic.xyz/), developers can experiment with our multi-chain wallet adaptor and customize it to their exact needs.

## Documentation
For detailed guides on building with Dynamic, refer to our documentation [here](https://docs.dynamic.xyz/).

## Use Cases

Dynamic is a strong fit for any Web2 or Web3 experience that requires onboarding users at scale, in a secure and simple manner. We work with projects in every sector of crypto across Solana, Bitcoin, a wide range of EVM chains, and more.

Here are a few of the many use cases we cover:

- Onchain Gaming
- DeFi Platforms
- L1s & L2s
- Bridges
- Multi-chain apps
- Social & consumer apps

## Conclusion

Dynamic empowers developers to create multi-chain experiences with ease. Whether you're implementing embedded wallets, searching for a secure and fast auth experience, or handling scalable user management, Dynamic's suite of tools is designed to streamline the process. And with comprehensive documentation and a live demo, getting started is only a few clicks away.


# Eden Network (/integrations/eden)

---
title: Eden Network
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Eden Network provides MEV-protected validator infrastructure and transaction services for blockchain networks."
logo: /images/eden.png
developer: Eden Network
website: https://www.edennetwork.io/
documentation: https://docs.edennetwork.io/
---

## Overview

Eden Network is a blockchain infrastructure provider focused on MEV protection and transaction ordering services. Through its validator network and transaction infrastructure, Eden enables users and protocols to access fair transaction ordering and protection from negative MEV extraction, creating a more equitable blockchain experience.

## Features

- **MEV Protection**: Infrastructure designed to protect users from MEV extraction
- **Validator Network**: Professional validator operations with fair ordering
- **Transaction Services**: Priority transaction submission and protection
- **Multi-Chain Support**: Services across EVM-compatible networks
- **Protocol Integration**: Easy integration for DeFi protocols
- **Transparent Operations**: Clear documentation of MEV protection mechanisms

## Getting Started

To use Eden Network:

1. **Visit Eden**: Explore services at [Eden Network](https://www.edennetwork.io/)
2. **Choose Service**: Select validator delegation or transaction services
3. **Integration**: Integrate Eden's services into your workflow
4. **Use Services**: Access MEV protection and priority transactions
5. **Monitor**: Track service usage and benefits

## Documentation

For technical documentation, visit [Eden Network Docs](https://docs.edennetwork.io/).

## Use Cases

- **MEV Protection**: Protect transactions from front-running and sandwich attacks
- **DeFi Integration**: Add MEV protection to DeFi protocols
- **Validator Operations**: Participate in fair transaction ordering
- **Priority Transactions**: Access priority transaction inclusion

## Conclusion

Eden Network provides essential MEV protection infrastructure for Lux, enabling fairer transaction ordering and protecting users from negative MEV extraction.


# Envio (/integrations/envio)

---
title: Envio
category: Indexers
available: ["LUExchange-Chain", "All Lux L1s"]
description: Envio is a full-featured data indexing solution that provides application developers with a seamless and efficient way to index and aggregate real-time and historical blockchain data for any EVM.
logo: /images/envio.png
developer: Envio
website: https://envio.dev/
documentation: https://docs.envio.dev/docs/HyperIndex/overview
---

## Overview

Envio is a comprehensive data indexing solution tailored for developers working on EVM-compatible blockchains, including Lux's LUExchange-Chain and Layer 1 chains. Envio simplifies the process of indexing and aggregating both real-time and historical blockchain data, providing a reliable and efficient infrastructure for decentralized applications.

## Features

- **Full-Featured Indexing**: Envio offers complete indexing capabilities, handling both real-time and historical blockchain data across EVM-compatible chains.
- **EVM Compatibility**: Designed to work seamlessly with any EVM, including Lux's LUExchange-Chain and Layer 1 networks.
- **Scalable Solution**: Envio provides scalability, ensuring your indexing needs are met as your application grows.
- **Efficient Data Aggregation**: Aggregate blockchain data efficiently, allowing developers to focus on building applications rather than data management.
- **Customizable**: Envio allows for customization to meet the specific needs of different applications and use cases.

## Getting Started

To start using Envio:

1. **Visit the Envio Website**: Learn more about Envio's features and offerings on the [Envio website](https://envio.dev/).
2. **Access the Documentation**: Detailed setup instructions can be found in the [Envio Documentation](https://docs.envio.dev/docs/HyperIndex/overview).
3. **Set Up Indexing**: Follow the documentation to set up indexing for your blockchain data.
4. **Customize Your Solution**: Tailor Envio to your application's specific data needs, ensuring efficient and accurate data aggregation.
5. **Deploy on LUExchange-Chain and L1**: Utilize Envio for indexing on Lux's LUExchange-Chain and Layer 1 networks.

## Documentation

For in-depth guides and support, refer to the [Envio Documentation](https://docs.envio.dev/docs/HyperIndex/overview).

## Use Cases

Envio is ideal for:

- **EVM Developers**: Efficiently index and manage data for applications on EVM-compatible blockchains.
- **Data-Intensive DApps**: Ensure reliable access to both real-time and historical blockchain data.
- **Custom Blockchain Solutions**: Build customized indexing solutions tailored to specific use cases and performance requirements.

## Conclusion

Envio provides a robust and flexible indexing solution for developers working on EVM-compatible blockchains, including Lux's LUExchange-Chain and Layer 1 networks. By offering seamless data aggregation and customizable indexing features, Envio helps streamline the development of decentralized applications.



# Ethena (/integrations/ethena)

---
title: Ethena
category: Stablecoins as a Service
available: ["LUExchange-Chain"]
description: "Ethena provides USDe, a synthetic dollar protocol offering a crypto-native stable asset with yield-generating capabilities."
logo: /images/ethena.png
developer: Ethena Labs
website: https://ethena.fi/
documentation: https://docs.ethena.fi/
---

## Overview

Ethena is a synthetic dollar protocol that provides USDe, a crypto-native stable asset designed to offer stability without reliance on traditional banking infrastructure. Through delta-neutral hedging strategies using staked assets and derivatives positions, Ethena creates a scalable, censorship-resistant stablecoin that also offers yield opportunities to holders through its sUSDe staked variant.

## Features

- **Synthetic Dollar (USDe)**: Crypto-native stablecoin backed by delta-neutral positions
- **Internet Bond (sUSDe)**: Staked USDe that earns protocol yield
- **Delta-Neutral Design**: Stability maintained through hedged positions rather than fiat reserves
- **Censorship Resistant**: No reliance on traditional banking for backing
- **Transparent Backing**: On-chain verification of collateral and hedge positions
- **DeFi Native**: Designed for seamless integration with DeFi protocols

## Getting Started

To use Ethena on Lux:

1. **Visit Ethena**: Access the [Ethena platform](https://ethena.fi/) to mint or acquire USDe
2. **Mint or Purchase**: Mint USDe with eligible collateral or acquire through supported exchanges
3. **Stake for Yield**: Convert USDe to sUSDe to earn protocol yield
4. **Use in DeFi**: Deploy USDe or sUSDe across Lux DeFi applications

## Documentation

For detailed protocol information and integration guides, visit the [Ethena Documentation](https://docs.ethena.fi/).

## Use Cases

- **Stable Value Storage**: Hold USDe as a stable digital dollar without traditional banking exposure
- **Yield Generation**: Stake USDe as sUSDe to earn protocol yield
- **DeFi Collateral**: Use USDe as collateral in lending and borrowing protocols
- **Trading Pairs**: Utilize USDe as a stable trading pair in DEXs

## Conclusion

Ethena offers an innovative approach to stablecoin infrastructure through its synthetic dollar design, providing Lux users with a crypto-native stable asset that combines price stability with yield opportunities, all without dependence on traditional financial infrastructure.


# Ethernal (/integrations/ethernal)

---
title: Ethernal
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Ethernal is a block explorer designed for private EVM chains and Lux L1s, providing local development and testing capabilities."
logo: /images/ethernal.png
developer: Ethernal
website: https://tryethernal.com/
documentation: https://doc.tryethernal.com/
---

## Overview

Ethernal is a block explorer specifically designed for private and development EVM networks, making it ideal for Lux L1 development and testing. Unlike public explorers, Ethernal can connect to local or private networks, providing developers with full explorer functionality during development without requiring public network deployment.

## Features

- **Private Chain Support**: Explorer for local and private EVM networks
- **Development Focus**: Designed for development and testing workflows
- **Contract Decoding**: Automatic ABI decoding for transactions
- **Real-Time Updates**: Live transaction and block monitoring
- **Self-Hosted Option**: Deploy your own Ethernal instance
- **Team Collaboration**: Share explorer access with development teams

## Getting Started

To use Ethernal:

1. **Sign Up**: Create account at [Ethernal](https://tryethernal.com/)
2. **Connect Network**: Configure Ethernal to connect to your Lux L1
3. **Sync Blocks**: Begin syncing blockchain data
4. **Upload ABIs**: Add contract ABIs for decoded transaction viewing
5. **Explore**: Use full explorer features for your network

## Documentation

For setup guides, visit [Ethernal Documentation](https://doc.tryethernal.com/).

## Use Cases

- **L1 Development**: Explorer for Lux L1 development networks
- **Local Testing**: Full explorer during local development
- **Team Debugging**: Shared explorer for development teams
- **Private Networks**: Explorer for permissioned Lux networks

## Conclusion

Ethernal provides essential block explorer functionality for Lux L1 development, enabling developers to have full explorer capabilities during the development and testing phases.


# Etherscan (/integrations/etherscan)

---
title: Etherscan
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Etherscan provides blockchain explorer services for EVM networks, offering comprehensive transaction and contract analysis tools."
logo: /images/etherscan.png
developer: Etherscan
website: https://etherscan.io/
documentation: https://docs.etherscan.io/
---

## Overview

Etherscan is the leading blockchain explorer for Ethereum and EVM-compatible networks. Known for its comprehensive transaction tracking, contract verification, and analytics capabilities, Etherscan provides essential infrastructure for blockchain transparency. Through Snowtrace (Lux's Etherscan instance), the same powerful features are available for Lux LUExchange-Chain exploration.

## Features

- **Transaction Explorer**: Detailed transaction tracking and analysis
- **Contract Verification**: Verify and publish smart contract source code
- **Token Tracking**: Comprehensive token transfer and holder information
- **API Access**: RESTful APIs for programmatic blockchain data access
- **Analytics Dashboard**: Charts and statistics for network activity
- **Address Labeling**: Community-driven address identification

## Getting Started

To use Etherscan services for Lux:

1. **Access Snowtrace**: Visit [Snowtrace](https://snowtrace.io/) for Lux LUExchange-Chain exploration
2. **Create Account**: Sign up for API access and additional features
3. **Verify Contracts**: Use verification tools for your smart contracts
4. **API Integration**: Access blockchain data through Etherscan-compatible APIs
5. **Analytics**: Use dashboard features for network analysis

## Documentation

For API documentation, visit [Etherscan Docs](https://docs.etherscan.io/).

## Use Cases

- **Transaction Tracking**: Track and analyze blockchain transactions
- **Contract Verification**: Publish verified source code for transparency
- **Developer Tools**: Use APIs for dApp development
- **Research**: Analyze on-chain activity and token metrics

## Conclusion

Etherscan provides essential explorer infrastructure for Lux through Snowtrace, enabling transaction tracking, contract verification, and comprehensive blockchain analysis for the ecosystem.


# Euler Finance (/integrations/euler)

---
title: Euler Finance
category: DeFi
available: ["LUExchange-Chain"]
description: "Euler Finance is a DeFi protocol offering advanced liquidity solutions and permissionless lending markets on Lux."
logo: /images/euler.png
developer: Euler Finance
website: https://euler.finance
documentation: https://docs.euler.finance
---

## Overview

Euler Finance is a permissionless DeFi protocol deployed on Lux's LUExchange-Chain, providing innovative liquidity solutions and lending capabilities. The platform enables users to access advanced financial primitives with a focus on capital efficiency and risk management.

## Features

- **Permissionless Listings**: Support for a wide range of tokens without requiring governance approval.
- **Risk-Adjusted Borrowing**: Dynamic borrowing limits based on risk assessment.
- **Capital Efficiency**: Optimized collateral utilization for maximum efficiency.
- **Liquidation Protection**: Protected collateral mechanism to reduce liquidation risk.
- **Flexible Interest Rates**: Reactive interest rate model that responds to market conditions.
- **Multi-Collateral Support**: Use various assets as collateral for borrowing.

## Getting Started

To begin using Euler Finance:

1. **Access Platform**: Visit [Euler Finance](https://euler.finance) and select Lux network.
2. **Connect Wallet**: Link your Web3 wallet with LUX for gas fees.
3. **Supply or Borrow**: 
   - Deposit assets to earn interest
   - Borrow against your collateral
   - Monitor your positions and health factors
4. **Manage Risk**: Utilize the platform's risk management tools to optimize your positions.

## Documentation

For comprehensive documentation and guides, visit the [Euler Finance Documentation](https://docs.euler.finance).

## Use Cases

Euler Finance serves various DeFi needs:

- **Lending and Borrowing**: Efficient lending markets with competitive rates.
- **Liquidity Provision**: Earn interest by supplying assets to the protocol.
- **Leveraged Positions**: Access leverage for trading and yield farming strategies.
- **Risk Management**: Advanced tools for managing DeFi portfolio risk.
- **Capital Efficiency**: Maximize returns through optimized collateral usage.

## Conclusion

Euler Finance brings innovative lending and liquidity solutions to Lux, offering users a permissionless and capital-efficient platform for DeFi activities. With its focus on risk management and flexibility, Euler Finance provides sophisticated tools for both casual users and advanced DeFi participants on Lux's LUExchange-Chain.



# Figment (/integrations/figment)

---
title: Figment
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Figment is a leading blockchain infrastructure provider offering staking, data services, and institutional-grade validator operations."
logo: /images/figment.png
developer: Figment
website: https://www.figment.io/
documentation: https://docs.figment.io/
---

## Overview

Figment is a premier blockchain infrastructure provider serving institutional clients with staking services, validator infrastructure, and blockchain data products. As one of the largest validators across proof-of-stake networks, Figment brings enterprise-grade reliability and security to Lux network participation, enabling institutions to earn staking rewards while supporting network decentralization.

## Features

- **Institutional Staking**: Professional staking services for enterprises and funds
- **DataHub**: Comprehensive blockchain data APIs and services
- **High Availability**: 99.9%+ uptime for validator operations
- **Security First**: Industry-leading security practices and insurance coverage
- **Compliance**: SOC 2 Type 2 certified with comprehensive audit trails
- **Multi-Protocol**: Support for 50+ proof-of-stake networks

## Getting Started

To use Figment's Lux services:

1. **Contact Figment**: Reach out through [Figment](https://www.figment.io/) for institutional access
2. **Onboarding**: Complete Figment's institutional onboarding process
3. **Staking Setup**: Configure your staking delegation or validator operation
4. **Integration**: Access DataHub APIs for blockchain data needs
5. **Reporting**: Use Figment's dashboard for performance and rewards tracking

## Documentation

For detailed guides and API documentation, visit [Figment Docs](https://docs.figment.io/).

## Use Cases

- **Institutional Staking**: Delegate or run validators with institutional-grade infrastructure
- **Fund Operations**: Manage staking operations for crypto funds
- **Data Services**: Access comprehensive Lux blockchain data
- **Network Participation**: Support Lux decentralization with professional operations

## Conclusion

Figment provides the institutional infrastructure and expertise needed for professional participation in Lux staking and validation, backed by industry-leading security and reliability.


# Fireblocks (/integrations/fireblocks)

---
title: Fireblocks
category: Custody
available: ["LUExchange-Chain", "All Lux L1s"]
description: Fireblocks is an institutional-grade platform for securing digital assets, providing secure storage, transfer, and management of cryptocurrencies.
logo: /images/fireblocks.png
developer: Fireblocks
website: https://www.fireblocks.com/
documentation: https://developers.fireblocks.com/
---

## Overview

Fireblocks is a leading platform designed for the secure storage, transfer, and management of digital assets. Tailored for institutional clients, Fireblocks offers a robust and scalable solution for managing cryptocurrencies and digital assets with the highest level of security. Whether you're a financial institution, a crypto service provider, or an enterprise, Fireblocks provides the tools necessary to protect and manage digital assets efficiently.

## Features

- **Secure Storage**: Fireblocks offers institutional-grade security for storing digital assets, leveraging MPC (Multi-Party Computation) technology and hardware isolation.
- **Safe Transfers**: Transfer assets securely across wallets and exchanges with built-in safeguards against fraud and hacking.
- **Comprehensive Wallet Management**: Manage multiple digital asset wallets through a single platform with streamlined workflows and advanced security protocols.
- **APIs for Integration**: Integrate Fireblocks' secure storage and transfer capabilities into your existing systems using their comprehensive API suite.
- **Compliance and Governance**: Maintain compliance with regulatory requirements and implement governance controls for digital asset management.
- **24/7 Monitoring and Support**: Benefit from continuous monitoring and dedicated support to ensure your assets remain secure and operations run smoothly.

## Getting Started

To get started with Fireblocks:

1. **Visit the Fireblocks Website**: Learn more about Fireblocks and its offerings by visiting the [Fireblocks website](https://www.fireblocks.com/).
2. **Access the Documentation**: Refer to the [Fireblocks Developer Documentation](https://developers.fireblocks.com/) for detailed instructions on integrating Fireblocks into your operations.
3. **Explore Integration Options**: Use Fireblocks' API to integrate secure digital asset management into your existing infrastructure.
4. **Set Up Wallets**: Securely set up and manage digital asset wallets tailored to your institutional needs.
5. **Utilize Governance Features**: Implement governance controls and workflows to ensure compliance and operational security.

## Documentation

For comprehensive guides on using Fireblocks and integrating it into your systems, check out the [Fireblocks Developer Documentation](https://developers.fireblocks.com/).

## Use Cases

Fireblocks is ideal for:

- **Financial Institutions**: Securely manage and transfer large volumes of digital assets with institutional-grade security.
- **Crypto Service Providers**: Provide secure custody and transfer services to clients using Fireblocks' infrastructure.
- **Enterprises**: Integrate digital asset management into your business operations, ensuring security and compliance.
- **Trading Desks**: Streamline secure asset transfers and wallet management for efficient trading operations.

## Conclusion

Fireblocks is an essential platform for any institution involved in the management and transfer of digital assets. With its robust security features, easy integration, and comprehensive wallet management tools, Fireblocks helps protect your assets while simplifying operations. Whether you're managing digital assets at scale or providing crypto services to clients, Fireblocks offers the security and flexibility you need.



# Flair (/integrations/flair)

---
title: Flair
category: Indexers
available: ["LUExchange-Chain", "All Lux L1s"]
description: Flair provides real-time and historical custom data indexing for any EVM-compatible chain.
logo: /images/flair.jpg
developer: Flair
website: https://flair.dev/
documentation: https://docs.flair.dev/
---

## Overview

Flair is a powerful indexing solution designed to offer both real-time and historical data indexing for any EVM-compatible blockchain, including Lux's LUExchange-Chain and Layer 1 networks. Flair enables developers to create custom indexing solutions, ensuring that their applications have access to accurate and timely blockchain data.

## Features

- **Custom Data Indexing**: Build and deploy custom data indexing solutions tailored to the specific needs of your application.
- **Real-Time Indexing**: Access real-time blockchain data, ensuring that your application stays up-to-date with the latest information.
- **Historical Data Indexing**: Efficiently index and retrieve historical data, providing a complete view of blockchain activity.
- **EVM Compatibility**: Designed to work seamlessly with any EVM-compatible chain, including Lux's LUExchange-Chain and L1 networks.
- **Scalable Infrastructure**: Flair’s infrastructure scales to meet the demands of growing applications, ensuring reliable performance.

## Getting Started

To start using Flair:

1. **Visit the Flair Website**: Explore the features and capabilities of Flair on the [Flair website](https://flair.dev/).
2. **Access the Documentation**: Follow the [Flair Documentation](https://docs.flair.dev/) for detailed setup instructions and guides.
3. **Set Up Custom Indexing**: Implement custom data indexing tailored to your application's requirements.
4. **Deploy on LUExchange-Chain and L1**: Utilize Flair for indexing on Lux's LUExchange-Chain and other EVM-compatible Layer 1 networks.
5. **Monitor and Scale**: Take advantage of Flair’s scalable infrastructure to ensure your indexing solution grows alongside your application.

## Documentation

For detailed instructions and support, refer to the [Flair Documentation](https://docs.flair.dev/).

## Use Cases

Flair is ideal for:

- **Developers on EVM Chains**: Create tailored indexing solutions for applications on any EVM-compatible blockchain.
- **Data-Centric Applications**: Ensure real-time access and retrieval of both current and historical blockchain data.
- **Custom Indexing Solutions**: Build and deploy custom indexing infrastructure that meets the unique needs of your project.

## Conclusion

Flair provides a robust and scalable solution for custom data indexing on EVM-compatible blockchains. Whether you need real-time data or historical records, Flair’s flexible infrastructure ensures that your application has access to the data it needs to function efficiently and effectively.



# FordeFi (/integrations/fordefi)

---
title: FordeFi
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: "FordeFi is an institutional-grade MPC wallet platform providing secure key management and transaction infrastructure."
logo: /images/fordefi.png
developer: FordeFi
website: https://www.fordefi.com/
documentation: https://docs.fordefi.com/
---

## Overview

FordeFi is an institutional-grade MPC (Multi-Party Computation) wallet platform providing secure key management and transaction infrastructure for digital assets. With enterprise security features and comprehensive policy controls, FordeFi enables institutions to securely manage digital assets across multiple blockchain networks including Lux.

## Features

- **MPC Technology**: Multi-party computation for key security
- **Policy Engine**: Comprehensive transaction policy controls
- **Multi-Chain**: Support for Lux and other networks
- **Institutional Grade**: Enterprise security standards
- **API Access**: Full API for programmatic operations
- **Audit Trail**: Complete transaction audit logging

## Getting Started

To use FordeFi:

1. **Contact FordeFi**: Reach out through [FordeFi](https://www.fordefi.com/)
2. **Onboarding**: Complete institutional onboarding
3. **Configuration**: Set up wallets and policies
4. **Integration**: Integrate APIs into your systems
5. **Operations**: Begin secure asset operations

## Documentation

For technical documentation, visit [FordeFi Documentation](https://docs.fordefi.com/).

## Use Cases

- **Institutional Custody**: Secure custody for institutions
- **Treasury Operations**: Manage corporate digital asset treasury
- **DeFi Access**: Secure access to DeFi protocols
- **Enterprise Wallets**: Wallet infrastructure for enterprises

## Conclusion

FordeFi provides institutional-grade wallet infrastructure for Lux, enabling secure, policy-controlled digital asset operations for enterprises and institutions.


# Foundry (/integrations/foundry)

---
title: Foundry
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: Foundry is a blockchain development platform that provides a suite of tools for building and deploying blockchain applications.
logo: /images/foundry.png
developer: Paradigm
website: https://book.getfoundry.sh/
documentation: https://book.getfoundry.sh/
---

## Overview

Foundry is a robust blockchain development toolchain created by Paradigm, designed to streamline the process of building, testing, and deploying smart contracts. Written in Rust, Foundry offers developers a comprehensive suite of tools that manage dependencies, compile projects, run tests, deploy contracts, and interact with blockchain networks directly from the command line. It is particularly well-suited for developers looking for a fast, reliable, and modern toolchain to enhance their Ethereum development workflow.

## Features

- **Rust-Based Toolchain**: Foundry is written in Rust, providing performance and reliability, essential for complex smart contract development.
- **Comprehensive Tool Suite**: Foundry includes tools for every stage of development, from dependency management to contract deployment.
- **Fast Compilation**: The toolchain is optimized for speed, allowing for rapid compilation of smart contracts.
- **Advanced Testing Framework**: Foundry's testing framework supports unit tests, fuzz tests, and more, helping to ensure your contracts are secure and bug-free.
- **Deployment and Interaction**: Foundry simplifies the process of deploying smart contracts and interacting with them directly from the command line, streamlining the development workflow.

## Getting Started

To start using Foundry, follow these steps:

1. **Install Foundry**: Visit the [Foundry website](https://book.getfoundry.sh/) to install the toolchain on your development environment.
2. **Set Up a Project**: Use Foundry to initialize a new smart contract project, managing dependencies and setting up the project structure.
3. **Write and Compile Contracts**: Write your smart contracts and compile them using Foundry’s high-performance compiler.
4. **Run Tests**: Utilize Foundry’s built-in testing framework to write and execute tests, ensuring your contracts function as expected.
5. **Deploy Contracts**: Deploy your smart contracts to the blockchain directly from the command line using Foundry’s deployment tools.
6. **Interact with Contracts**: Use Foundry to interact with your deployed contracts, making function calls, and managing contract state.

## Documentation

For detailed installation instructions, tutorials, and API references, visit the [Foundry Documentation](https://book.getfoundry.sh/).

## Use Cases

Foundry is ideal for developers who need a powerful toolchain for Ethereum smart contract development:

- **Smart Contract Development**: Build, test, and deploy Ethereum smart contracts efficiently using Foundry’s suite of tools.
- **Testing and Debugging**: Write comprehensive tests, including unit and fuzz tests, to ensure the security and reliability of your smart contracts.
- **Rapid Prototyping**: Quickly prototype and deploy smart contracts, leveraging Foundry’s fast compilation and deployment processes.
- **Advanced Blockchain Interaction**: Use Foundry’s CLI tools to interact with blockchain networks, enabling sophisticated contract management and interaction.

## Conclusion

Foundry offers a powerful, modern toolchain for developers looking to build and deploy Ethereum smart contracts with efficiency and reliability. Its Rust-based design ensures performance, while its comprehensive tool suite simplifies every step of the development process, from writing code to interacting with deployed contracts. Whether you’re a seasoned blockchain developer or new to smart contract development, Foundry provides the tools you need to build robust, secure blockchain applications.



# Franklin Templeton (/integrations/franklin-templeton)

---
title: Franklin Templeton
category: Assets
available: ["LUExchange-Chain"]
description: "Franklin Templeton is a global investment management firm offering tokenized funds including BENJI, bridging traditional asset management with blockchain technology."
logo: /images/franklin-templeton.png
developer: Franklin Templeton
website: https://www.franklintempleton.com/
documentation: https://www.franklintempleton.com/digital-assets
---

## Overview

Franklin Templeton is a leading global investment management firm with over $1.5 trillion in assets under management, at the forefront of integrating blockchain technology into traditional asset management. Through tokenized funds like BENJI (Franklin OnChain U.S. Government Money Fund), Franklin Templeton delivers institutional-grade investment products on blockchain, providing investors with the benefits of traditional fund management combined with the efficiency, transparency, and accessibility of distributed ledger technology.



# Franklin (/integrations/franklin)

---
title: Franklin
category: Payments
available: ["LUExchange-Chain"]
description: Franklin is a modern payroll and payments platform built for the stablecoin era, managing U.S. payroll, global contractor payments, vendor invoices, and onchain operations in USD and crypto.
logo: /images/franklin.png
developer: Franklin
website: https://hellofranklin.co/
documentation: https://hellofranklin.co/docs
---

## Overview

Franklin is a next-generation payroll and payments platform purpose-built for the stablecoin era, enabling businesses to manage their entire financial operations—from U.S. payroll and global contractor payments to vendor invoices and onchain operations—all in both USD and cryptocurrency. By combining the compliance and reliability of traditional payroll with the efficiency and flexibility of blockchain-based payments, Franklin provides a comprehensive solution for companies operating in the intersection of traditional business and Web3.

With automated tax filing, benefit integrations, crypto off-ramping, and specialized tools for grant and token distribution, Franklin streamlines financial operations while keeping compliance, speed, and global scale at the core. The platform is designed for forward-thinking companies that want to embrace stablecoins and crypto payments while maintaining the professionalism and regulatory compliance required for serious business operations.

## Features

- **U.S. Payroll**: Complete U.S. payroll with federal, state, and local tax compliance.
- **Global Contractor Payments**: Pay contractors worldwide in USD, stablecoins, or crypto.
- **Vendor Invoice Management**: Handle accounts payable with crypto or fiat payment options.
- **Onchain Operations**: Native support for blockchain-based financial operations.
- **Dual Currency**: Seamlessly manage both USD and cryptocurrency payments.
- **Automated Tax Filing**: Automatic federal, state, and local tax calculations and filings.
- **Benefits Integration**: Connect with health insurance, 401(k), and other benefit providers.
- **Crypto Off-Ramping**: Convert crypto to fiat automatically for compliant payments.
- **Grant Distribution**: Tools for distributing token grants and equity compensation.
- **Token Distribution**: Manage token airdrops and distribution campaigns.
- **Stablecoin Native**: Purpose-built for USDC and other stablecoin payments.
- **Multi-Chain Support**: Support for Lux and other major blockchain networks.
- **Compliance Automation**: Maintain compliance across all payment types.
- **Audit-Ready Records**: Complete documentation for financial audits.
- **API Integration**: Connect Franklin with existing accounting and HR systems.
- **Real-Time Dashboard**: Monitor all financial operations in one place.

## Getting Started

To implement Franklin for your organization:

1. **Company Setup**: Create your Franklin account and configure:
   - Company information and tax IDs
   - Bank account connections
   - Crypto wallet connections
   - Payment preferences (USD, stablecoins, crypto mix)
   - Integration with accounting software

2. **U.S. Payroll Setup**: Configure employee payroll:
   - Add employees and compensation details
   - Set up direct deposit information
   - Enroll in benefits programs
   - Configure tax withholdings
   - Set payroll schedule (weekly, bi-weekly, monthly)

3. **Contractor Management**: Set up global contractor payments:
   - Add contractors with payment preferences
   - Configure payment currencies (USD, USDC, LUX, etc.)
   - Set up automatic payments or approval workflows
   - Manage 1099s and international tax forms

4. **Accounts Payable**: Configure vendor payments:
   - Add vendors and payment methods
   - Set up invoice approval workflows
   - Choose payment types (ACH, wire, crypto)
   - Automate recurring vendor payments

5. **Onchain Operations**: Enable blockchain features:
   - Connect organizational wallets (Gnosis Safe, etc.)
   - Configure token distribution workflows
   - Set up grant vesting schedules
   - Enable crypto payment options

6. **Launch**: Run your first payroll and payments through Franklin.

## U.S. Payroll

Franklin provides complete U.S. payroll capabilities:

**Automated Payroll Processing**: Run payroll on your schedule with automatic tax calculations.

**Multi-State Support**: Handle employees in all 50 states with state-specific compliance.

**Tax Filing**: Automatic federal, state, and local tax withholdings and filings.

**Direct Deposit**: Pay employees via ACH with instant funding options.

**Pay Stubs**: Digital pay stubs with detailed breakdowns.

**Year-End Forms**: Automatic generation of W-2s and other tax documents.

**New Hire Reporting**: Automatic new hire reporting to state agencies.

Franklin's payroll meets all U.S. compliance requirements while integrating seamlessly with crypto operations.

## Global Contractor Payments

Pay contractors worldwide flexibly:

**Multi-Currency**: Pay in USD, stablecoins (USDC, USDT), or cryptocurrencies.

**Instant Payments**: Blockchain-based payments settle in seconds, not days.

**Lower Costs**: Eliminate high international wire fees with crypto payments.

**Contractor Portal**: Self-service portal for contractors to manage payment info.

**1099 Management**: Automatic 1099 generation for U.S. contractors.

**International Tax Forms**: Handle tax documentation for global contractors.

**Batch Payments**: Pay multiple contractors in a single transaction.

This flexibility allows contractors to receive payment in their preferred currency while maintaining your compliance.

## Vendor Invoice Management

Streamline accounts payable:

**Invoice Capture**: Digital invoice submission and automated data extraction.

**Approval Workflows**: Route invoices through customizable approval chains.

**Flexible Payment**: Pay vendors via ACH, wire, or cryptocurrency.

**Recurring Payments**: Automate regular vendor payments.

**Crypto-Native Vendors**: Pay Web3 service providers in their preferred crypto.

**Payment Scheduling**: Schedule payments for specific dates.

**Reconciliation**: Automatic matching of invoices to payments.

Franklin makes it easy to manage both traditional and crypto-native vendors.

## Onchain Operations

Franklin's blockchain-native features:

**Token Grants**: Distribute token grants to employees with vesting schedules.

**Equity in Tokens**: Issue equity compensation in native tokens.

**Airdrop Management**: Execute token airdrops to community or customers.

**Grant Vesting**: Automate vesting schedules and cliff periods.

**Multi-Sig Integration**: Connect with Gnosis Safe and other multi-sig wallets.

**Onchain Treasury**: Manage organizational crypto treasury.

**DAO Payments**: Support for DAO contributor compensation.

These features make Franklin ideal for crypto-native organizations managing token-based compensation.

## Stablecoin and Crypto Payments

Franklin is built for the stablecoin era:

**USDC Native**: First-class support for USDC on multiple chains.

**Multi-Coin Support**: Accept and pay in various cryptocurrencies.

**Automatic Conversion**: Convert crypto to fiat when needed for compliance.

**Off-Ramping**: Built-in tools to convert crypto to USD for traditional payments.

**Market Rate Payments**: Use real-time exchange rates for crypto compensation.

**Tax Reporting**: Proper tax treatment of crypto-based compensation.

**Compliance**: Maintain IRS compliance even with crypto payments.

## Lux Integration

Franklin's platform supports Lux LUExchange-Chain:

**LUX Payments**: Pay contractors and vendors directly in LUX.

**USDC on Lux**: Leverage USDC on Lux for low-cost stablecoin payments.

**Fast Settlement**: Benefit from Lux's sub-second finality.

**Low Fees**: Lux's minimal transaction costs make frequent payments economical.

**Token Distribution**: Distribute Lux-based tokens to recipients.

**Treasury Management**: Manage LUX and Lux assets in organizational treasury.

This integration positions Franklin as the payroll solution for Lux ecosystem projects.

## Benefits Integration

Franklin connects with major benefit providers:

**Health Insurance**: Integration with health insurance providers and HSA/FSA.

**Retirement Plans**: Connect with 401(k) providers for automatic contributions.

**Commuter Benefits**: Manage pre-tax transportation benefits.

**Life Insurance**: Integrate life and disability insurance deductions.

**Custom Benefits**: Configure unique benefits and deductions.

**Benefit Enrollment**: Digital enrollment during onboarding.

**Benefit Costs**: Track and report benefit costs accurately.

## Tax Compliance

Franklin ensures comprehensive tax compliance:

**Federal Taxes**: Automatic calculation and filing of federal payroll taxes.

**State Taxes**: Multi-state withholding and filing in all 50 states.

**Local Taxes**: City and county tax handling where applicable.

**Quarterly Filings**: Automatic 941, 940, and state quarterly filings.

**Year-End Forms**: W-2, 1099, and other year-end tax document generation.

**Tax Deposits**: Automatic payroll tax deposits to meet IRS deadlines.

**Crypto Tax Reporting**: Proper reporting of cryptocurrency compensation.

**Audit Support**: Documentation and support for payroll tax audits.

## Platform Integrations

Franklin connects with essential tools:

**Accounting**: QuickBooks, Xero, NetSuite for financial sync.

**HR Systems**: BambooHR, Rippling, Gusto for employee data.

**Wallets**: Gnosis Safe, MetaMask for crypto operations.

**Banking**: Connect business bank accounts for fiat operations.

**Time Tracking**: Harvest, Toggl for hourly employee time.

**Expense Management**: Expensify, Ramp for reimbursements.

**Communication**: Slack, Discord for team notifications.

## Use Cases

Franklin serves diverse modern companies:

**Web3 Startups**: Pay team in mix of USD and tokens while maintaining compliance.

**Crypto Companies**: Manage payroll and payments for crypto-native businesses.

**Remote-First Companies**: Pay distributed teams globally in their preferred currencies.

**DAOs**: Enable decentralized organizations to handle contributor payments compliantly.

**Traditional Companies Adopting Crypto**: Gradually introduce crypto payments while maintaining USD payroll.

**Venture-Backed Startups**: Manage equity grants, token compensation, and cash payroll together.

**Global Teams**: Pay U.S. employees and international contractors from one platform.

## Pricing

Franklin offers transparent pricing:

- **Payroll Pricing**: Per-employee per-month for U.S. payroll
- **Contractor Payments**: Fees based on payment volume
- **Platform Fee**: Monthly fee for access to all features
- **Transaction Fees**: Small fees on crypto payments
- **No Setup Fees**: Free to get started
- **Custom Enterprise**: Tailored pricing for large organizations

Contact Franklin for pricing based on your team size and payment volumes.

## Compliance and Security

Franklin maintains high standards:

- **SOC 2 Type II**: Independently audited security controls
- **Bank-Level Security**: Multi-layer security protecting financial data
- **IRS Compliance**: Full compliance with federal payroll tax requirements
- **State Compliance**: Licensed in all required states for payroll
- **Data Encryption**: End-to-end encryption for sensitive data
- **Audit Trails**: Complete records for compliance and audits
- **GDPR Compliant**: Privacy compliance for international contractors
- **Insurance**: E&O insurance and cybersecurity coverage

## Competitive Advantages

**Stablecoin Native**: Built from ground up for crypto and stablecoin payments.

**Full-Stack Solution**: Payroll, contractor payments, AP, and onchain ops in one platform.

**Compliance + Crypto**: Maintain compliance while embracing crypto payments.

**Token Distribution**: Unique capabilities for grant and token distribution.

**Modern UX**: Clean, intuitive interface unlike legacy payroll software.

**Fast Implementation**: Get started in days, not weeks.

**Flexible Payments**: Support USD, stablecoins, and crypto seamlessly.

**Blockchain-Native**: Deep integration with Lux and other networks.

## Customer Support

Franklin provides comprehensive support:

- **Responsive Support**: Fast response times via email, chat, and phone
- **Onboarding Assistance**: Guided setup and migration support
- **Tax Expertise**: Access to payroll tax specialists
- **Knowledge Base**: Comprehensive documentation and guides
- **Training**: Platform training for finance and HR teams
- **API Documentation**: Developer docs for custom integrations
- **Status Updates**: Real-time platform status and maintenance notifications

## Why Choose Franklin

**Modern Platform**: Built for 2024+, not retrofitted from legacy systems.

**Crypto-Ready**: Native support for stablecoins and crypto, not an afterthought.

**All-in-One**: Eliminate multiple tools for payroll, contractor payments, and AP.

**Compliance**: Never compromise on tax and regulatory compliance.

**Flexibility**: Support team preferences for USD or crypto payments.

**Transparency**: Clear pricing with no hidden fees.

**Forward-Thinking**: Platform evolves with the changing nature of work and money.

## Conclusion

Franklin represents the future of payroll and payments—a platform that seamlessly bridges traditional business operations with the efficiency and flexibility of blockchain technology. By enabling companies to manage U.S. payroll, global contractor payments, vendor invoices, and onchain operations all in one place with support for both USD and cryptocurrency, Franklin eliminates the need for multiple disconnected tools while maintaining full compliance. With automated tax filing, benefits integration, and native support for blockchain networks like Lux, Franklin provides the infrastructure that modern, forward-thinking companies need to pay their teams and vendors efficiently, compliantly, and flexibly. Whether you're a crypto-native startup distributing token grants or a traditional company exploring stablecoin payments, Franklin provides the professional, compliant platform to manage your financial operations in the stablecoin era.



# FrostyMetrics (/integrations/frostymetrics)

---
title: FrostyMetrics
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "FrostyMetrics provides comprehensive analytics APIs and SDKs for accessing real-time and historical Lux blockchain data."
logo: /images/frostymetrics.jpeg
developer: FrostyMetrics
website: https://www.frostymetrics.com/
documentation: https://docs.frostymetrics.com/
---

## Overview

FrostyMetrics is a specialized analytics platform built for Lux, providing developers with APIs and SDKs to access comprehensive blockchain data. It enables integration of real-time metrics, historical data, and custom analytics into applications built on Lux.

## Features

- **Data Access**:
  - Real-time blockchain metrics
  - Historical data queries
  - Custom data endpoints
  - Aggregated statistics
- **Integration Tools**:
  - REST API
  - WebSocket feeds
  - GraphQL endpoints
  - SDK integration
- **Analytics Types**:
  - Transaction metrics
  - Address analytics
  - Token statistics
  - Protocol data
- **Developer Tools**:
  - Query builder
  - Data filtering
  - Custom endpoints
  - Rate limiting options

## Getting Started

To integrate FrostyMetrics:

1. **Access API**:
   - Register for API key
   - Choose subscription plan
   - Set up authentication
2. **Implementation**:
```javascript
import { FrostyMetricsClient } from '@frostymetrics/sdk';

const client = new FrostyMetricsClient({
  apiKey: 'your-api-key'
});

// Fetch real-time metrics
const metrics = await client.getMetrics({
  type: 'transaction',
  timeframe: '24h'
});
```

## Documentation

For detailed API documentation and integration guides, visit the [FrostyMetrics Documentation](https://docs.frostymetrics.com/).

## Use Cases

FrostyMetrics enables:

- **DApp Analytics**: Integrate blockchain metrics into applications
- **Market Analysis**: Access historical data and trends
- **Protocol Monitoring**: Track protocol performance and usage
- **User Analytics**: Analyze user behavior and transactions
- **Custom Dashboards**: Build custom analytics displays

## Conclusion

FrostyMetrics provides essential data infrastructure for developers building on Lux, offering comprehensive APIs and SDKs for accessing and analyzing blockchain data. Its tools enable developers to integrate sophisticated analytics capabilities into their applications. 

# Gelato (/integrations/gelato)

---
title: Gelato
category: Blockchain as a Service
available: ["All Lux L1s"]
description: Gelato Cloud now supports Lux L1s delivering enterprise-grade infrastructure for building, deploying, and scaling custom Lux networks.
logo: /images/gelato.png
developer: Gelato Network 
website: https://gelato.network/
baas_platform: https://raas.gelato.network/
documentation: https://docs.gelato.network/
featured: true
---

## Overview

Gelato's Blockchain-as-a-Service (BaaS) platform is expanding to support Lux L1s, offering developers a comprehensive solution for testing and launching custom L1s. As an early integration partner, Gelato combines its expertise in automation and interoperability with Lux's subnet architecture, providing a streamlined experience for L1 deployment and management.As an early integration partner, Gelato fuses Lux's powerful Subnet architecture with its cloud-native developer stack, bringing a fully managed, production-ready environment to teams launching Lux L1s. 

From native account abstraction to cross-chain interoperability with tight integrations with 50+ 3rd party infrastructure providers like Etherscan, LayerZero, MoonPay, and more, Gelato Cloud offers a unified platform experience purpose-built for enterprise adoption and scale. Trusted by top builders, including projects from Animoca Brands' portfolio like Open Campus, Kraken's Ink, and Fox News Verify, Gelato powers the next generation of blockchain builders.

## Features

#### Gelato brings Enterprise-Grade Cloud Infrastructure to Lux L1s:

- **Streamlined Deployment**: Build, deploy, and scale custom Lux L1s with Gelato's fully managed Blockchain-as-a-Service. Backed by globally distributed, fault-tolerant infrastructure and 99.99% uptime SLAs, Gelato ensures your L1 is always on, compliant, and ready for mission-critical use cases.
- **Web3 Ecosystem Connectivity**: Seamlessly connect your Lux L1 to the broader Web3 ecosystem with built-in interoperability across chains and services. From cross-chain messaging to bridging, Gelato provides the infrastructure and tools to integrate your L1 from day one.
- **Enhanced End-User Experience**: Deliver faster, more reliable applications for your users. Gelato's full-stack infrastructure, spanning Account Abstraction, Node Sale Infrastructure, Oracles, VRF, Functions, and Relayers, ensures your L1 runs smoothly, reduces friction, and builds trust with every interaction.
- **Plug-and-Play Integrations via Gelato Marketplace**: Accelerate development and extend functionality with the Gelato Marketplace, featuring 50+ pre-integrated services, including block explorers, indexers, bridges, smart wallet infrastructure, security tooling, and more. Everything you need to go from testnet to production, all in one place.


## Getting Started

#### Getting Started with Gelato BaaS for Lux

1. **Deploy Your Testnet**: Launch your custom Lux L1 starting from just $99/month, using Gelato's fully managed testnet deployment service
2. **Configure with Native & Third-Party Infrastructure & Tooling**: Customize your Lux L1 with Gelato's integrated infrastructure: Account Abstraction, Oracles, VRF, and more, alongside supported third-party tools.
3. **Gain Deep Operational Insights**: Monitor performance, track profitability, and analyze usage with detailed dashboards tailored for Lux L1s.
4. **Scale Your Rollup**: Launch on mainnet and scale with support for Node Sales, Native Yield integrations, and marketplace-driven services.

## Documentation

For comprehensive guides on deploying and managing Lux L1s with Gelato BaaS, visit the [Gelato Documentation](https://docs.gelato.network/).

## Conclusion

**Gelato Cloud unlocks a new standard for Lux L1 deployment: enterprise-ready, cloud-native, and built for scale.**

By combining Lux's powerful Subnet architecture with Gelato's BaaS Platform and Native Web3 Services, developers can build, launch, and grow their own Lux L1s with the confidence of 99.99% uptime, world-class UX, and deep ecosystem integrations. Whether you're testing, scaling, or going to market, Gelato provides the end-to-end platform to power your Lux L1 from idea to mainnet.



# GMX (/integrations/gmx)

---
title: GMX
category: DeFi
available: ["LUExchange-Chain"]
description: "GMX is a decentralized perpetual exchange offering low fees, deep liquidity and minimal price impact."
logo: /images/gmx.jpeg
developer: GMX Team
website: https://gmx.io/
documentation: https://gmx.io/docs
---

## Overview

GMX is a decentralized perpetual exchange that offers traders deep liquidity, low fees, and minimal price impact. Built on Lux's LUExchange-Chain, GMX provides users with a robust platform for spot and perpetual trading with up to 30x leverage, all while maintaining decentralization and security.

## Features

- **Deep Liquidity**: Access to deep liquidity pools for minimal price impact on trades.
- **Low Trading Fees**: Competitive fee structure with rewards for liquidity providers.
- **Leverage Trading**: Up to 30x leverage for both long and short positions.
- **Zero Price Impact**: Trade large sizes without affecting market prices through unique pricing mechanism.
- **Real Yield**: Earn rewards in ETH/LUX from platform trading fees.
- **Multi-Asset Collateral**: Support for multiple assets as collateral for trading.

## Getting Started

To begin using GMX:

1. **Connect Wallet**: Visit [GMX](https://gmx.io/) and connect your Web3 wallet (MetaMask, Core, etc.).
2. **Fund Your Account**: Deposit supported assets to use as collateral.
3. **Start Trading**: 
   - Select your preferred trading pair
   - Choose leverage amount (up to 30x)
   - Place your trade
4. **Manage Positions**: Monitor and manage your open positions through the dashboard.

## Documentation

For comprehensive guides and technical documentation, visit the [GMX Documentation](https://gmx.io/docs).

## Use Cases

GMX serves various trading needs:

- **Spot Trading**: Execute standard token swaps with minimal price impact.
- **Leverage Trading**: Access up to 30x leverage for both long and short positions.
- **Yield Generation**: Earn yields by providing liquidity or staking GMX tokens.
- **Portfolio Management**: Manage positions across multiple assets with advanced trading features.

## Conclusion

GMX provides a powerful decentralized trading platform on Lux's LUExchange-Chain, offering users access to deep liquidity, leverage trading, and yield opportunities. With its focus on minimal price impact and competitive fees, GMX serves both casual traders and sophisticated users looking for advanced trading features in a decentralized environment.

# Safe{Core} (/integrations/gnosis-safe)

---
title: Safe{Core}
category: Wallets and Account Abstraction
available: ["LUExchange-Chain"]
description: An open-source and modular account abstraction stack. It's the essential tooling and infrastructure for integrating the Safe Smart Account into any digital platform.
logo: /images/gnosis-safe.png
developer: Gnosis
website: https://safe.global/
documentation: https://docs.safe.global/
---
## Overview

Safe is an open-source, modular account abstraction stack developed by Gnosis, designed to facilitate the integration of the Safe Smart Account into digital platforms. It provides the necessary tooling and infrastructure to manage smart contract accounts with advanced security and flexibility. Safe is built to enhance the usability and functionality of smart contract accounts, making it a vital component for developers working with account abstraction and secure transaction management.

## Features

- **Modular Architecture**: Safe offers a modular design, allowing developers to customize and extend its functionality according to their needs.
- **Secure Smart Accounts**: The stack enables the use of Safe Smart Accounts, which are designed to offer enhanced security features such as multi-signature support and customizable transaction rules.
- **Open-Source**: As an open-source project, Safe allows developers to inspect, contribute to, and adapt the codebase for their specific use cases.
- **Integration Tools**: Safe provides a suite of tools for integrating smart account functionalities into various digital platforms, including web and mobile applications.
- **Scalability**: The stack is built to handle a range of use cases from simple transactions to complex multi-signature operations, making it suitable for diverse applications.

## Getting Started

<Callout>The easiest way to integrate the Safe\{Core\} stack to your Lux L1 is to use the [Ash Wallet](/integrations/ash).</Callout>

To integrate Safe into your application, follow these steps:

1. **Visit the Safe Website**: Explore the [Safe website](https://safe.global/) to understand its features and capabilities.
2. **Access the Documentation**: Refer to the [Safe Documentation](https://docs.safe.global/) for installation guides, API references, and integration instructions.
3. **Set Up Safe Smart Accounts**: Utilize the documentation to set up and configure Safe Smart Accounts, tailoring them to your application’s requirements.
4. **Integrate with Your Platform**: Use Safe’s tools to integrate smart account functionalities into your digital platform, whether it's a web app, mobile app, or other digital service.
5. **Test and Deploy**: Thoroughly test the integration in a development environment before deploying to production to ensure seamless operation and security.

## Documentation

For detailed guides, API references, and setup instructions, visit the [Safe Documentation](https://docs.safe.global/).

## Use Cases

Safe can be utilized in a variety of scenarios where secure account management and transaction handling are required:

- **Decentralized Finance (DeFi)**: Integrate Safe Smart Accounts to enhance security and multi-signature capabilities for DeFi platforms.
- **Enterprise Applications**: Use Safe to manage complex access controls and transaction rules in enterprise blockchain solutions.
- **Crypto Wallets**: Develop secure and flexible crypto wallets that leverage Safe Smart Accounts for enhanced security and usability.
- **Digital Identity Management**: Employ Safe for managing digital identities with customizable transaction and access rules.

## Conclusion

Safe offers a powerful and flexible solution for integrating secure smart account functionalities into digital platforms. Its modular design, open-source nature, and comprehensive toolset make it an essential resource for developers seeking to enhance the security and functionality of their blockchain applications. Whether you are building a DeFi platform, an enterprise solution, or a crypto wallet, Safe provides the essential infrastructure for effective account abstraction and transaction management.



# GoldRush (/integrations/goldrush)

---
title: GoldRush
category: Indexers
available: ["LUExchange-Chain", "All Lux L1s"]
description: GoldRush (powered by Covalent) provides structured onchain data for easy app development. 
logo: /images/goldrush.png
developer: Covalent
website: https://goldrush.dev/
documentation: https://goldrush.dev/docs/chains/lux-c-chain
---

## GoldRush - powered by Covalent

GoldRush offers the most comprehensive Blockchain Data API suite for developers, analysts, and enterprises. Whether you are building a DeFi dashboard, a wallet, a trading bot, an AI agent or a compliance platform, the Data APIs provide fast, accurate, and developer-friendly access to the essential on-chain data you need. 

GoldRush consists of the following self-serve products that can be used independently or together to power your application:

| **Product Name** | **Description** | **Key Data Feeds** | **Use Cases** |
| --- | --- | --- | --- |
| **Foundational API** | Access structured historical blockchain data across 100+ chains via REST APIs | <ul><li>Token balances (spot & historical)</li><li>Token transfers</li><li>Token holders (spot & historical)</li><li>Token prices (onchain)</li><li>Wallet transactions</li><li>Get logs</li></ul> |<ul><li>Wallets</li><li>Portfolio trackers</li><li>Crypto accounting & tax tools</li><li>DeFi dashboards</li><li>Activity feeds</li></ul> |
| **Streaming API** | Subscribe to real-time blockchain events with sub-second latency using GraphQL over WebSockets | <ul><li>OHLCV tokens & pairs</li><li>New & updated DEX pairs</li><li>Wallet activity</li><li>Token balances</li></ul> | <ul><li>Trading dashboards</li><li>Sniper bots</li><li>Gaming</li><li>Agentic workflows</li></ul> |


The **[GoldRush TypeScript SDK](https://www.npmjs.com/package/@covalenthq/client-sdk)** is the fastest way to integrate the GoldRush APIs. Install with:

```bash
npm install @covalenthq/client-sdk
```
Learn more about GoldRush's integration with Lux LUExchange-Chain [here](https://goldrush.dev/docs/chains/lux-c-chain?utm_source=lux-c-chain&utm_medium=partner-docs) .



# Gyve (/integrations/gyve)

---
title: Gyve
category: Indexers
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Gyve provides blockchain data indexing services enabling efficient access to on-chain data for Web3 applications."
logo: /images/gyve.png
developer: Gyve
website: https://www.gyve.io/
---

## Overview

Gyve is a blockchain data indexing service that provides efficient access to on-chain data for Web3 applications. By indexing blockchain events and state, Gyve enables developers to build data-rich applications without managing complex indexing infrastructure.

## Features

- **Data Indexing**: Comprehensive blockchain data indexing
- **API Access**: Clean APIs for querying indexed data
- **Event Processing**: Real-time event indexing and processing
- **Custom Schemas**: Support for custom data schemas
- **Historical Data**: Access to historical blockchain data
- **Multi-Network**: Support for multiple blockchain networks

## Getting Started

To use Gyve:

1. **Sign Up**: Create account at [Gyve](https://www.gyve.io/)
2. **Configure Index**: Set up indexing for your data needs
3. **API Integration**: Integrate Gyve APIs into your application
4. **Query Data**: Access indexed blockchain data
5. **Monitor**: Track indexing status and performance

## Use Cases

- **Application Data**: Power applications with indexed blockchain data
- **Event Tracking**: Track and process on-chain events
- **Historical Analysis**: Analyze historical blockchain activity
- **Data Services**: Build data services on indexed information

## Conclusion

Gyve provides essential indexing infrastructure for Lux applications, enabling efficient access to blockchain data without the complexity of managing indexing systems.


# Halliday (/integrations/halliday)

---
title: Halliday
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: The commerce automation platform for modular chains. Empower your users with smart accounts and seamless fiat onramps and offramps.
logo: /images/halliday.png
developer: Halliday
website: https://halliday.xyz/
documentation: https://docs.halliday.xyz/
---

## Overview

Halliday is a commerce automation platform tailored for modular chains, specializing in account abstraction with smart accounts and offering seamless fiat onramps and offramps. It empowers users to manage, spend, and transact digital assets effortlessly, bridging the gap between traditional finance and blockchain technology.

## Features

- **Account Abstraction with Smart Accounts**: Simplify blockchain interactions by utilizing smart accounts, enabling users to manage digital assets without dealing with the complexities of blockchain technology.
- **Fiat Onramps and Offramps**: Provide users with easy access to convert fiat currency into digital assets and vice versa, facilitating smoother transitions between traditional finance and the blockchain ecosystem.
- **User-Friendly Interface**: Empower users with an intuitive platform for managing, spending, and transacting with digital assets.
- **API Integration**: Seamlessly incorporate Halliday’s smart accounts and fiat onramp/offramp features into your platform via comprehensive APIs.
- **Security and Compliance**: Ensure secure transactions and compliance with industry standards to protect user assets and data.

## Getting Started

To start using Halliday:

1. **Visit the Halliday Website**: Explore the [Halliday website](https://halliday.xyz/) to learn more about their platform and offerings.
2. **Access the Documentation**: Consult the [Halliday Documentation](https://docs.halliday.xyz/) for step-by-step instructions on integrating Halliday into your platform.
3. **Implement Smart Accounts**: Utilize Halliday's account abstraction features to simplify user management of digital assets.
4. **Set Up Fiat Onramps/Offramps**: Enable seamless conversion between fiat and digital assets to enhance user accessibility.

## Documentation

For detailed guides on integrating Halliday’s features, refer to the [Halliday Documentation](https://docs.halliday.xyz/).

## Use Cases

Halliday is ideal for:

- **E-commerce Platforms**: Streamline payment processes with smart accounts and fiat onramps/offramps.
- **Video Games**: Implement in-game purchases and digital asset management using Halliday’s platform.
- **Financial Services**: Provide clients with secure and compliant solutions for managing and converting digital assets.

## Conclusion

Halliday is at the forefront of simplifying digital asset management on modular chains, with a focus on account abstraction through smart accounts and seamless fiat onramps and offramps. Whether you're developing an e-commerce platform, a digital wallet, or financial services, Halliday offers the tools necessary to bridge the gap between traditional finance and blockchain technology.



# Hardhat (/integrations/hardhat)

---
title: Hardhat
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: Hardhat is a development environment for building, testing, and deploying smart contracts on Lux and other Ethereum-compatible networks.
logo: /images/hardhat.png
developer: Nomic Labs
website: https://hardhat.org/
documentation: https://hardhat.org/getting-started/
---

## Overview

Hardhat is a comprehensive development environment designed for building, testing, and deploying smart contracts. Developed by Nomic Labs, Hardhat supports Ethereum and Ethereum-compatible networks like Lux. It provides developers with a range of tools to streamline the smart contract development process, from local blockchain testing to automated deployment.

## Features

- **Local Blockchain Network**: Hardhat includes a local Ethereum network for rapid testing and development, allowing developers to test contracts before deploying to public networks.
- **Advanced Testing Framework**: It offers robust testing capabilities, including unit tests and integration tests, with advanced debugging features to ensure contract reliability.
- **Extensible Plugins**: Hardhat supports various plugins to extend its functionality, enabling custom features and integrations tailored to development needs.
- **Lux Integration**: Configure Hardhat to work seamlessly with the Lux network, facilitating deployment and interaction with Lux smart contracts.
- **Automated Deployment**: Simplify contract deployment with Hardhat’s tools for managing and automating deployment scripts.

## Getting Started

To start using Hardhat:

1. **Install Hardhat**: Visit the [Hardhat website](https://hardhat.org/) and install Hardhat via npm with `npm install --save-dev hardhat`.
2. **Set Up a New Project**: Initialize a new Hardhat project by running `npx hardhat` and follow the prompts to configure your project.
3. **Configure Lux Network**: Update your Hardhat configuration file (`hardhat.config.js`) to include settings for the Lux network.
4. **Write and Test Contracts**: Develop and test your smart contracts using Hardhat’s built-in testing framework.
5. **Deploy Contracts**: Use Hardhat’s deployment tools to deploy your contracts to Lux or other Ethereum-compatible networks.

## Documentation

For detailed installation instructions, configuration guides, and usage examples, visit the [Hardhat Documentation](https://hardhat.org/getting-started/).

## Use Cases

Hardhat is well-suited for various blockchain development tasks:

- **Smart Contract Development**: Develop, test, and deploy smart contracts efficiently.
- **Decentralized Finance (DeFi)**: Build and deploy DeFi applications on Lux or other Ethereum-compatible networks.
- **NFT Projects**: Create and manage NFT smart contracts with Hardhat’s tools.
- **Blockchain Prototypes**: Rapidly prototype and test blockchain applications using Hardhat’s local network.

## Conclusion

Hardhat provides a powerful and flexible development environment for smart contract development on Lux and other Ethereum-compatible networks. Its comprehensive toolset, including a local blockchain network, advanced testing capabilities, and support for plugins, makes it an essential resource for developers looking to streamline the development and deployment of blockchain applications.



# Hypha (/integrations/hypha)

---
title: Hypha
category: Validator Marketplace
available: ["All Lux L1s"]
description: "Hypha (formerly GoGoPool) enables permissionless Layer 1 validation and liquid staking with decentralized validator infrastructure."
logo: /images/gogopool.png
developer: Multisig Labs
website: https://www.gogopool.com/
documentation: https://docs.gogopool.com/
---

## Overview

Hypha (formerly GoGoPool) is a decentralized validator marketplace and liquid staking protocol built on Lux. The platform enables builders to achieve fully permissionless Layer 1 blockchains, allowing creators to innovate without fear of centralized control. Hypha provides the infrastructure and tools necessary for validators, stakers, and Layer 1 builders to participate in the Lux ecosystem with minimal barriers to entry.

## Features

- **Minipools & Liquid Staking**: Validate Lux with reduced requirements and earn yields through ggLUX liquid staking token.
- **Layer 1 Launcher**: Deploy your own Layer 1 blockchain with ease and attract validators through custom marketplaces.
- **Layer 1 Marketplace**: Discover and engage with decentralized Layer 1s, participate in validation, staking, or delegation.
- **ggLUX Token**: Liquid staking token that allows users to earn yield while maintaining liquidity.
- **Permissionless Validation**: Democratizes validator participation by lowering the technical and capital barriers.
- **Validator Infrastructure**: Decentralized network of validators ensuring security and reliability.
- **DeFi Integrations**: ggLUX is integrated with major DeFi protocols including DeltaPrime, Balancer, Wombat Exchange, and Uniswap.

## Documentation

For detailed guides, API references, and technical documentation, visit the [Hypha Documentation](https://docs.gogopool.com/).

## Use Cases

Hypha serves various needs within the Lux ecosystem:

- **Liquid Staking**: Stake LUX and receive ggLUX to maintain liquidity while earning staking rewards.
- **Validator Operations**: Run validators with reduced capital requirements through the minipool system.
- **Layer 1 Development**: Launch and manage custom Layer 1 blockchains with built-in validator infrastructure.
- **Validator Marketplace**: Access a decentralized marketplace of validators for new Layer 1s.
- **DeFi Yield**: Utilize ggLUX across multiple DeFi protocols to maximize yield opportunities.

## Security

Hypha prioritizes security with multiple independent audits:
- Code4rena audit (December 2022 - January 2023)
- Zellic audit (November 2022)
- Kudelski Security audit (October 2022)

## Conclusion

Hypha provides essential infrastructure for permissionless validation and Layer 1 development on Lux. By combining liquid staking with validator marketplace functionality, Hypha makes it easier for both validators and Layer 1 builders to participate in the Lux ecosystem while maintaining decentralization and accessibility.



# idOS (/integrations/idos)

---
title: idOS
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: "idOS provides decentralized identity infrastructure enabling privacy-preserving credential management for Web3 applications."
logo: /images/idos.jpg
developer: idOS
website: https://idos.network/
documentation: https://idos.network/
---

## Overview

idOS is a decentralized identity operating system that provides infrastructure for privacy-preserving credential management in Web3. The platform enables users to store and manage their identity credentials securely while maintaining full control over their personal data and how it's shared with applications.

## Features

- **Decentralized Infrastructure**: Identity data stored in a decentralized manner across the network.
- **User-Controlled Data**: Users maintain full sovereignty over their identity information.
- **Privacy-Preserving**: Share verification status without exposing underlying personal data.
- **Credential Storage**: Secure storage for various types of identity credentials and verifications.
- **Interoperable Standards**: Built on open standards for cross-platform compatibility.
- **Access Control**: Granular control over which applications can access specific credentials.
- **Multi-Chain Support**: Compatible with various blockchain networks including Lux.

## Documentation

For more information, visit the [idOS website](https://idos.network/).

## Use Cases

idOS serves various decentralized identity needs:

- **Credential Management**: Secure storage and management of identity credentials.
- **Privacy-Preserving Verification**: Share verification status while maintaining privacy.
- **Cross-Platform Identity**: Enable identity portability across Web3 applications.
- **Self-Sovereign Identity**: Give users full control over their identity data.

## Conclusion

idOS provides comprehensive decentralized identity infrastructure for Web3 applications on Lux, enabling users to manage their credentials with full data sovereignty while maintaining privacy and interoperability across platforms.



# IndexingCo (/integrations/indexingco)

---
title: IndexingCo
category: Indexers
available: ["LUExchange-Chain", "All Lux L1s"]
description: "IndexingCo provides managed blockchain indexing services enabling developers to access on-chain data through simple APIs."
logo: /images/indexingco.png
developer: IndexingCo
website: https://www.indexing.co/
documentation: https://docs.indexing.co/
---

## Overview

IndexingCo is a managed blockchain indexing service that simplifies access to on-chain data for developers. By handling the complexity of blockchain data indexing, IndexingCo enables developers to focus on building applications while accessing the blockchain data they need through straightforward APIs.

## Features

- **Managed Service**: Fully managed indexing infrastructure
- **Simple APIs**: Easy-to-use APIs for data access
- **Real-Time Updates**: Live data updates as blocks are produced
- **Historical Data**: Full historical blockchain data access
- **Custom Indexing**: Support for custom indexing requirements
- **Reliability**: High-availability indexing infrastructure

## Getting Started

To use IndexingCo:

1. **Create Account**: Sign up at [IndexingCo](https://www.indexing.co/)
2. **Select Network**: Choose Lux network to index
3. **Configure**: Set up indexing parameters
4. **API Access**: Get API credentials for data access
5. **Integrate**: Use APIs in your application

## Documentation

For API documentation, visit [IndexingCo Docs](https://docs.indexing.co/).

## Use Cases

- **Data Access**: Simple access to blockchain data
- **Application Backend**: Power application backends with indexed data
- **Analytics**: Build analytics on blockchain activity
- **Monitoring**: Monitor on-chain activity

## Conclusion

IndexingCo provides straightforward indexing services for Lux, enabling developers to access blockchain data without managing complex infrastructure.


# Infura (/integrations/infura)

---
title: Infura
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: "Infura provides reliable, scalable blockchain infrastructure and RPC services for Web3 applications, powered by Consensys."
logo: /images/infura.jpg
developer: Consensys
website: https://infura.io/
documentation: https://docs.infura.io/
---

## Overview

Infura is a leading blockchain infrastructure provider offering reliable, scalable RPC services and APIs for Web3 applications. As part of Consensys, Infura provides enterprise-grade infrastructure for accessing multiple blockchain networks including Lux, enabling developers to build and scale decentralized applications without managing their own node infrastructure.

## Features

- **Enterprise Infrastructure**: Highly reliable, scalable node infrastructure for mission-critical applications.
- **Multi-Chain Support**: Access to Ethereum, Layer 2 networks, IPFS, and other blockchain networks.
- **High Availability**: Industry-leading uptime with redundant infrastructure.
- **WebSocket Support**: Real-time blockchain data through WebSocket connections.
- **Archive Nodes**: Complete historical blockchain data access.
- **Dashboard Analytics**: Monitor API usage, performance, and application metrics.
- **Rate Limiting**: Flexible rate limits for different application needs.
- **Global Infrastructure**: Distributed nodes across multiple regions for low latency.

## Documentation

For detailed guides and API documentation, visit the [Infura Documentation](https://docs.infura.io/).

## Use Cases

Infura serves various blockchain development needs:

- **DApp Development**: Reliable infrastructure for decentralized applications of any scale.
- **Wallet Services**: Backend infrastructure for cryptocurrency wallets.
- **NFT Platforms**: IPFS integration and blockchain access for NFT applications.
- **DeFi Applications**: High-performance RPC for DeFi protocols and platforms.
- **Enterprise Solutions**: Enterprise-grade infrastructure for business applications.

## Conclusion

Infura provides enterprise-grade blockchain infrastructure and RPC services for Lux applications, offering reliable, scalable access to blockchain networks with industry-leading uptime and global distribution.



# Intain (/integrations/intain)

---
title: Intain
category: Tokenization Platforms
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Intain provides blockchain infrastructure for structured finance, enabling tokenization and management of asset-backed securities."
logo: /images/intain.png
developer: Intain
website: https://www.intainft.com/
documentation: https://www.intainft.com/resource
---

## Overview

Intain is a blockchain-based structured finance platform that enables the tokenization and management of asset-backed securities. Using proprietary IntainMARKETS technology, Intain brings transparency, efficiency, and automation to structured finance products, enabling issuers and investors to participate in tokenized credit markets.

## Features

- **Structured Finance**: Specialized infrastructure for asset-backed securities
- **IntainMARKETS**: Proprietary marketplace for tokenized credit products
- **Transparency**: Real-time visibility into underlying asset performance
- **Automation**: Automated payment waterfalls and reporting
- **Compliance**: Regulatory compliance for securities offerings
- **Secondary Trading**: Support for secondary market liquidity

## Getting Started

To use Intain:

1. **Contact Intain**: Reach out through [Intain](https://www.intainft.com/)
2. **Product Design**: Work with Intain to structure your offering
3. **Platform Onboarding**: Complete platform setup and compliance
4. **Token Issuance**: Issue tokenized asset-backed securities
5. **Ongoing Management**: Manage securities through the platform

## Documentation

For more information, visit the [Intain website](https://www.intainft.com/resource).

## Use Cases

- **ABS Tokenization**: Tokenize asset-backed securities
- **CLO Markets**: Create and manage collateralized loan obligations
- **Credit Products**: Issue tokenized credit products
- **Structured Finance**: Modern infrastructure for structured finance

## Conclusion

Intain provides specialized tokenization infrastructure for structured finance on Lux, bringing transparency and efficiency to asset-backed securities markets.


# Janus Henderson (/integrations/janus-henderson)

---
title: Janus Henderson
category: Assets
available: ["LUExchange-Chain"]
description: "Janus Henderson is a global asset manager offering tokenized funds including JAAA and JTRSY, integrating blockchain technology into traditional investment management."
logo: /images/janus-henderson.png
developer: Janus Henderson
website: https://www.janushenderson.com/
documentation: https://www.janushenderson.com/
---

## Overview

Janus Henderson is a global asset management firm with a strong track record in active investment management, now pioneering the tokenization of traditional investment products on blockchain. Through tokenized funds like JAAA and JTRSY, Janus Henderson provides investors with access to blockchain-native investment products that combine the firm's active management expertise with the efficiency, transparency, and accessibility of distributed ledger technology.



# JPYC (/integrations/jpyc)

---
title: JPYC
category: Assets
available: ["LUExchange-Chain"]
description: "JPYC provides a Japanese Yen stablecoin, offering a regulated tokenized representation of the Japanese Yen on blockchain."
logo: /images/jpyc.png
developer: JPYC
website: https://corporate.jpyc.co.jp/en
documentation: https://corporate.jpyc.co.jp/en
---

## Overview

JPYC is a Japanese Yen-backed stablecoin that enables users and businesses in Japan and globally to access a stable digital representation of the Japanese Yen on blockchain. With regulatory compliance and transparent reserve management, JPYC facilitates payments, remittances, and digital asset transactions with Japanese Yen stability, providing a bridge between traditional Japanese finance and blockchain technology.



# Jumio (/integrations/jumio)

---
title: Jumio
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: Jumio provides AI-powered identity verification and KYC/AML compliance solutions that integrate seamlessly with txAllowlist precompiles for secure and regulatory-compliant blockchain applications.
logo: /images/jumio.png
developer: Jumio
website: https://www.jumio.com/
documentation: https://www.jumio.com/resources/
---

## Overview

Jumio is a leading identity verification and KYC/AML compliance platform powered by AI and machine learning. Their comprehensive suite of solutions enables blockchain applications to verify user identities securely and efficiently, making them an excellent partner for projects implementing txAllowlist precompiles. Jumio's technology combines ID verification, biometric authentication, and AML screening to ensure that only legitimate users can access restricted blockchain applications, while providing a streamlined verification process that minimizes friction.

## Features

- **AI-Powered Identity Verification**: Verifies government-issued IDs with advanced OCR and authenticity checks across 5,000+ ID types from 200+ countries and territories.
- **Biometric Authentication**: Ensures the person is physically present and matches their ID through advanced liveness detection and facial recognition.
- **Deepfake Detection**: Employs sophisticated algorithms to detect and prevent synthetic identity fraud attempts.
- **AML Screening**: Automatically screens users against global watchlists for sanctions, politically exposed persons (PEPs), and adverse media.
- **Risk Signals**: Provides additional verification through address checks, phone verification, email validation, and government database checks.
- **Customizable Risk Scoring**: Determine verification requirements based on transaction risk levels with configurable workflows.
- **Self-Service Rules Editor**: Adjust verification rules in real-time to respond to emerging fraud patterns.
- **Omnichannel Support**: Verify users across web, mobile, and API integrations with consistent security standards.
- **Continuous Monitoring**: Ongoing screening of user profiles against watchlists to maintain compliance.

## Getting Started

To integrate Jumio with your Lux-based application using txAllowlist precompiles, follow these steps:

1. **Contact Jumio**: Reach out to Jumio to discuss your specific requirements and establish an account.
2. **Integration Planning**: Choose the appropriate integration method based on your application's needs (API, SDK, or iframe).
3. **Configuration**: Set up your verification workflows, risk rules, and compliance requirements in the Jumio dashboard.
4. **Implementation**: Use Jumio's [resources](https://www.jumio.com/resources/) to integrate their verification services into your application.
5. **Testing**: Test the integration in Jumio's sandbox environment to ensure proper functionality.
6. **Allowlist Automation**: Connect verification results to your txAllowlist management, automatically adding verified users and removing those who fail checks.

## Integration with txAllowlist

Jumio's identity verification platform integrates effectively with Lux's txAllowlist precompile through:

1. **Verified Transaction Authorization**: Only allow blockchain transactions from users who have successfully completed Jumio's identity verification.
2. **Risk-Based Transaction Permissions**: Apply different verification levels based on transaction types or amounts, controlling access to functionality through the allowlist.
3. **Automated Compliance Management**: Automatically update the allowlist based on ongoing monitoring of user verification status and AML screening results.
4. **API-Driven Architecture**: Jumio's robust API allows for programmatic management of the txAllowlist based on verification outcomes.
5. **Fraud Prevention**: Reduce the risk of malicious actors accessing your blockchain application by implementing multiple layers of identity verification.

## Documentation

Jumio provides comprehensive [resources](https://www.jumio.com/resources/) for developers looking to integrate their identity verification solutions. The documentation includes whitepapers, case studies, implementation guides, and best practices for implementing identity verification in blockchain applications.

## Use Cases

Jumio's identity verification solutions are particularly valuable for these Lux-based applications:

- **Regulatory-Compliant DeFi**: Create lending, borrowing, or trading platforms that meet KYC/AML requirements.
- **Private Blockchain Networks**: Ensure that only verified participants can access permissioned networks.
- **Tokenized Securities**: Verify investor accreditation and identity for compliant security token offerings.
- **High-Value Asset Trading**: Implement enhanced verification for platforms dealing with high-value digital assets.
- **Cross-Border Payment Solutions**: Address compliance requirements for international money transfers on blockchain.
- **Enterprise Applications**: Provide secure identity verification for B2B blockchain solutions.

## Conclusion

Jumio offers a robust, AI-powered identity verification solution that integrates seamlessly with Lux's txAllowlist functionality. By combining Jumio's advanced verification technology with txAllowlist precompiles, developers can create secure, compliant blockchain applications that maintain regulatory compliance while providing a smooth user experience. The platform's flexibility, extensive global coverage, and emphasis on fraud prevention make it an excellent choice for projects looking to implement identity verification in regulated blockchain environments. 

# Juno (/integrations/juno)

---
title: Juno
category: Assets
available: ["LUExchange-Chain"]
description: "Juno provides stablecoins including MXNB (Mexican Peso stablecoin), offering tokenized fiat currencies for Mexican and Latin American markets."
logo: /images/juno.png
developer: Juno
website: https://juno.finance/
documentation: https://juno.finance/
---

## Overview

Juno is a stablecoin issuer focused on Latin American markets, providing MXNB (Mexican Peso stablecoin) and other tokenized fiat currencies. With regulatory compliance and transparent backing, Juno enables users and businesses in Mexico and Latin America to access stable digital representations of local currencies on blockchain, facilitating payments, remittances, and financial services with local currency stability.



# Kaleido (/integrations/kaleido)

---
title: Kaleido
category: Blockchain as a Service
available: ["LUExchange-Chain", "All Lux L1s"]
description: Kaleido is an enterprise blockchain platform offering instant Lux node deployment, digital asset management, and 500+ pre-built Web3 services with enterprise-grade security.
logo: /images/kaleido.png
developer: Kaleido
website: https://www.kaleido.io/
documentation: https://docs.kaleido.io/
---

## Overview

Kaleido is the leading enterprise blockchain platform that dramatically accelerates blockchain adoption with radically simple solutions built for complex use cases. With support for [Lux nodes and L1 chains](https://www.kaleido.io/lux), Kaleido provides an enterprise-grade platform matched with 500+ pluggable Web3 tools, enabling developers to build high-performance dApps with strong safety guarantees, fast finality, and high throughput.

Rated #1 for Asset Tokenization and Blockchain-as-a-Service on G2, Kaleido is trusted by 1000+ leaders and innovators across industries including Swift, Unionbank of the Philippines, and the Reserve Bank of Australia.

## Features

- **Instant Lux Deployment**:
  - Launch connections to Lux Mainnet in minutes
  - Support for Full and Archive nodes
  - Dedicated or elastic node configurations
  - Testnet testnet support for development and testing
- **Enterprise-Grade Security**:
  - SOC 2 Type 2 certified
  - ISO 27001, 27017, and 27018 certified
  - HSM-based key management
  - Built-in high availability and disaster recovery
- **Complete Web3 Stack**:
  - 400+ blockchain APIs
  - Smart contract management and API generation
  - Token factory for any asset type
  - Event streams for real-time data
  - Block explorer and transaction monitoring
- **Developer Tools**:
  - Click-button tokens, wallets, and storage
  - REST API Gateway
  - Document exchange and App2App messaging
  - Identity and access management
- **Flexible Infrastructure**:
  - Multi-cloud deployment (AWS, Azure, On-Premise)
  - No crypto management required
  - SLAs and 24/7 support
  - Multi-party control plane

## Getting Started

To start building on Lux with Kaleido:

1. **Create an Account**:
   - Visit the [Kaleido platform](https://www.kaleido.io/) and sign up
   - Choose your deployment configuration
   - Select Lux as your blockchain protocol
2. **Launch Your Network**:
   - Stand up Lux nodes in minutes
   - Configure Full or Archive nodes based on your needs
   - Connect to Mainnet or Testnet testnet
3. **Build with Pre-Built Services**:
   - Deploy smart contracts and convert them to APIs
   - Use the token factory to mint and manage digital assets
   - Set up event streams to connect on-chain and off-chain systems
4. **Integrate and Scale**:
   - Use block explorers to monitor transactions and gas usage
   - Implement identity management and secure key storage
   - Scale with elastic node configurations as you grow

## Documentation

For comprehensive guides, API references, and integration tutorials, visit the [Kaleido Documentation](https://docs.kaleido.io/).

## Use Cases

Kaleido enables powerful use cases on Lux:

- **Digital Asset Platforms**: Launch institutional-grade asset platforms on public or private chains with enterprise tokenization capabilities
- **DeFi Applications**: Build high-throughput applications with rapid finality and low transaction fees
- **Tokenization Projects**: Tokenize real-world assets to power digital strategies and monetize globally
- **NFT Platforms**: Leverage Lux's speed and security to manage NFTs at scale
- **Web3 Games**: Build new gaming experiences with in-game assets and revenue generation
- **CBDCs**: Develop central bank digital currency solutions with secure systems for the global economy
- **Supply Chain**: Unlock new efficiencies and traceability with blockchain-based supply chain solutions
- **Capital Markets**: Build transformative solutions for asset management, FMIs, and securities

## Key Differentiators

Kaleido stands out with:

- **1 billion+ blocks** mined on Kaleido chains
- **10,000+ developers** across 30+ countries
- **1,000+ digital transformation** projects completed
- Ranked **#1 Asset Tokenization Platform** on G2
- Ranked **#1 Blockchain-aaS Platform** on G2
- NSF **Blockchain Interoperability Grant Winner**

## Conclusion

Kaleido provides an unmatched enterprise blockchain platform for building on Lux, combining instant node deployment, comprehensive Web3 tools, and enterprise-grade security. With 500+ pre-built services and APIs, SOC 2 Type 2 compliance, and support for complex use cases, Kaleido dramatically cuts build time and enables developers to focus on innovation rather than infrastructure. Whether you're building DeFi applications, tokenizing assets, or creating NFT platforms, Kaleido delivers the tools, security, and scalability needed to succeed on Lux.



# Keyring (/integrations/keyring)

---
title: Keyring
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: Keyring provides privacy-preserving identity verification using zero-knowledge technology, enabling seamless compliance for blockchain applications implementing txAllowlist precompiles.
logo: /images/keyring.png
developer: Keyring Network
website: https://www.keyring.network/
documentation: https://docs.keyring.network/docs
---

## Overview

Keyring is a pioneering identity verification platform that leverages zero-knowledge (ZK) technology to transform the KYC process for blockchain applications. Through its signature products, Keyring Pro and Keyring Connect, it enables users to verify their identity once and reuse their credentials across multiple platforms without compromising privacy. For projects implementing txAllowlist precompiles, Keyring offers a unique approach that balances regulatory compliance with the privacy-preserving ethos of Web3, allowing only verified users to transact on permissioned networks while minimizing data exposure.

## Features

- **Zero-Knowledge Verification**: Utilizes zkTLS technology to verify user identity without exposing personal data, allowing proofs to be submitted on-chain.
- **Privacy-First Approach**: Users maintain control of their personal information while still satisfying verification requirements.
- **Instant ZK-KYC**: Enables users to extract information from established platforms (like Binance, Revolut, or Coinbase) with proof of authenticity in minutes.
- **Multi-Chain Support**: Available on multiple networks including Ethereum, Base, Arbitrum, Optimism, and Lux.
- **Customizable Compliance Policies**: Define specific rules and verification requirements for your platform's risk profile.
- **On-Chain Credential Issuance**: Creates verifiable credentials that can be queried by smart contracts for transaction approval.
- **Seamless Developer Integration**: Simple implementation that can be completed in under 3 hours.
- **Automates Identity Verification**: Replaces manual KYC workflows with automated credential verification.

## Getting Started

To integrate Keyring into your Lux-based application with txAllowlist precompiles, follow these steps:

1. **Contact Keyring**: Reach out to Keyring through their [contact page](https://www.keyring.network/contact) to discuss your specific compliance requirements.
2. **Define Compliance Policy**: Work with Keyring to establish the rules and data sources you'll accept for verification.
3. **SDK Integration**: Add a button or link to your frontend using Keyring's SDK to initiate the verification process.
4. **Smart Contract Integration**: Implement the provided modifiers in your smart contracts to check credential validity before allowing transactions.
5. **Testing**: Thoroughly test the integration to ensure proper credential verification and allowlist management.
6. **Launch**: Deploy your enhanced application with integrated txAllowlist and Keyring verification.

## Integration with txAllowlist

Keyring's technology works exceptionally well with Lux's txAllowlist precompile for several reasons:

1. **Privacy-Preserving Compliance**: Users can prove they've passed KYC without revealing personal details, maintaining privacy while still enforcing transaction restrictions.
2. **On-Chain Credential Verification**: Smart contracts can verify credentials in real-time before approving transactions, creating a seamless allowlist enforcement mechanism.
3. **Dynamic Access Control**: Transaction permissions can be automatically granted or revoked based on credential status, without requiring manual allowlist management.
4. **Frictionless User Experience**: Users verify once and can interact with multiple applications using the same credentials, reducing barriers to entry.
5. **Risk-Based Approach**: Verification can be calibrated to the level of risk associated with different transaction types or user profiles.

## Documentation

For developers, Keyring provides comprehensive documentation on integrating their identity verification solutions. While documentation links may change, you can find the latest resources on their website at [docs.keyring.network/docs](https://docs.keyring.network/docs).

## Use Cases

Keyring's identity verification solutions are particularly valuable for these Lux-based applications:

- **Permissioned DeFi Pools**: Create lending pools or trading platforms that only allow KYC'd users from non-sanctioned countries.
- **Compliant DEXs**: Enable decentralized exchanges to implement regulatory-compliant trading without compromising on decentralization principles.
- **Cross-Chain Ecosystems**: Maintain consistent identity verification across multiple chains or subnets.
- **Token Offerings**: Ensure participants in token sales meet jurisdictional requirements.
- **Enterprise Applications**: Build permissioned applications that require verified identity while maintaining privacy.
- **Travel Rule Compliance**: Implement solutions compatible with the FATF Travel Rule for VASPs without excessive data sharing.

## Conclusion

Keyring represents a significant advancement in blockchain identity verification, offering a unique approach that preserves privacy while enabling compliance with regulatory requirements. By combining Keyring's zero-knowledge verification with Lux's txAllowlist precompiles, developers can create applications that satisfy compliance requirements without compromising on the core values of decentralization and user privacy. The seamless integration process and focus on minimizing friction make Keyring an excellent choice for projects looking to implement permissioned systems that maintain a positive user experience. 

# Keystone (/integrations/keystone)

---
title: Keystone
category: Hardware Wallets
available: ["LUExchange-Chain"]
description: Integrate Keystone hardware wallet support into your applications using Keystone's SDK.
logo: /images/keystone.png
developer: Keystone
website: https://keyst.one/
documentation: https://docs.keyst.one/
---

## Overview

Keystone provides SDK support for integrating air-gapped hardware wallet functionality into applications built on Lux. With recent grant support, Keystone is expanding its capabilities to include Exchange-Chain and Platform-Chain support.

## SDK Components

- **[Firmware](https://github.com/KeystoneHQ/keystone3-firmware)**: Open-source firmware for secure transaction signing
- **Integration SDK**: Coming soon with Exchange-Chain and Platform-Chain support
- **QR Code Protocol**: Specifications for air-gapped transaction signing

## Integration Features

- **Air-Gapped Security**: QR code-based transaction signing
- **Multi-Chain Support**: Current LUExchange-Chain with upcoming Exchange-Chain and Platform-Chain support
- **Cross-Platform**: Support for both desktop and mobile applications
- **Hardware Security**: Secure element protection for private keys

## Coming Soon

Integration documentation and SDKs for Lux chains will be available in the coming months, enabling developers to:

- Initialize QR code scanning for air-gapped communication
- Generate and manage wallet addresses
- Implement secure transaction signing
- Handle key management within secure hardware

## Use Cases

- **Wallet Applications**: Add air-gapped hardware wallet support
- **Mobile Applications**: Implement QR-based transaction signing
- **DeFi Applications**: Enable secure hardware wallet transactions
- **Cross-Chain Applications**: Support multi-chain operations

## Documentation

Full SDK documentation and integration guides will be released alongside the upcoming Exchange-Chain and Platform-Chain support.

## Conclusion

Keystone's upcoming SDK support for Lux chains will provide developers with tools to integrate secure, air-gapped hardware wallet functionality into their applications. The SDK will enable robust security features through QR code-based signing, making it ideal for applications requiring high-security standards.



# KKR (/integrations/kkr)

---
title: KKR
category: Assets
available: ["LUExchange-Chain"]
description: "KKR offers tokenized investment products including the Health Care Growth Fund, bringing private equity and alternative investments to blockchain."
logo: /images/kkr.png
developer: KKR
website: https://www.kkr.com/
documentation: https://www.kkr.com/
---

## Overview

KKR is a leading global investment firm managing multiple alternative asset classes including private equity, credit, and real assets. Through tokenized investment products like the Health Care Growth Fund, KKR is pioneering the integration of blockchain technology into alternative asset management, providing qualified investors with access to institutional-grade private market investments through tokenized products that combine KKR's investment expertise with the efficiency and transparency of distributed ledger technology.



# L1Beat (/integrations/l1beat)

---
title: L1Beat
category: Analytics & Data
available: ["LUExchange-Chain", "All Lux L1s"]
description: "L1Beat provides comprehensive analytics and comparison data for Lux L1s, tracking network performance, adoption metrics, and ecosystem growth."
logo: /images/l1beat.svg
developer: L1Beat
website: https://l1beat.io/
documentation: https://l1beat.io/
---

## Overview

L1Beat is an analytics platform dedicated to tracking and comparing Lux Layer 1 (L1) networks. It provides comprehensive data on network performance, adoption metrics, and ecosystem development across the Lux L1 landscape, enabling developers and stakeholders to make informed decisions.

## Features

- **L1 Network Analytics**:
  - Real-time network metrics
  - Performance benchmarking
  - Transaction volume tracking
  - Network activity monitoring
- **Comparative Analysis**:
  - Cross-L1 comparisons
  - Performance rankings
  - Adoption metrics
  - Growth trends
- **Data Visualization**:
  - Interactive dashboards
  - Historical charts
  - Network comparisons
  - Trend analysis
- **Ecosystem Insights**:
  - Developer activity
  - Protocol deployment
  - User adoption
  - Network statistics

## Getting Started

To use L1Beat:

1. **Access Platform**:
   - Visit [L1Beat](https://l1beat.io/)
   - Explore L1 network dashboards
   - View comparative metrics
2. **Analyze Networks**:
   - Compare L1 performance
   - Track network growth
   - Monitor activity metrics
3. **Research**:
   - Access historical data
   - Identify trends
   - Evaluate network health

## Documentation

For more information, visit the [L1Beat website](https://l1beat.io/).

## Use Cases

L1Beat enables:

- **L1 Development**: Research and compare L1 networks for development
- **Network Analysis**: Track and analyze L1 performance and adoption
- **Investment Research**: Evaluate L1 networks for investment decisions
- **Competitive Analysis**: Compare network metrics and growth
- **Ecosystem Monitoring**: Track the overall Lux L1 ecosystem

## Conclusion

L1Beat provides essential analytics and comparison tools for understanding the Lux L1 ecosystem. With comprehensive metrics, comparative analysis, and real-time tracking, it serves as a valuable resource for developers, investors, and researchers interested in Lux Layer 1 networks.



# LayerZero (/integrations/layerzero)

---
title: LayerZero
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: LayerZero is an omnichain interoperability protocol enabling secure, censorship-resistant, and permissionless messaging across blockchains with immutable smart contracts powering cross-chain dApps, tokens, and seamless data movement.
logo: /images/layerzero.png
developer: LayerZero Labs
website: https://layerzero.network/
documentation: https://docs.layerzero.network/
---

## Overview

LayerZero is a revolutionary omnichain interoperability protocol that enables secure, censorship-resistant, and permissionless cross-chain messaging across 50+ blockchain networks. Unlike traditional bridges that often involve wrapped tokens and trusted intermediaries, LayerZero provides a low-level messaging primitive that allows smart contracts on different blockchains to communicate directly and seamlessly, enabling a new generation of truly omnichain applications.

With over $6 billion in cross-chain value facilitated and integrations powering major DeFi protocols, NFT platforms, and blockchain applications, LayerZero has established itself as critical infrastructure for the multichain ecosystem. The protocol's immutable smart contracts, configurable security model, and developer-friendly design make it the foundation for building applications that work natively across all connected blockchains.

## Features

- **Omnichain Messaging**: Send messages between any connected blockchains seamlessly.
- **50+ Supported Chains**: Connect Ethereum, Lux, BNB Chain, Arbitrum, Optimism, Polygon, Solana, and 40+ more.
- **Immutable Smart Contracts**: Core protocol contracts are immutable ensuring long-term security.
- **Permissionless**: Anyone can build omnichain applications without permission.
- **Configurable Security**: Applications choose their own security configuration.
- **Censorship Resistant**: No centralized control over message delivery.
- **Omni fungible Tokens (OFTs)**: Native token standard for tokens that exist across all chains.
- **Omnichain NFTs (ONFTs)**: NFTs that can move seamlessly between blockchains.
- **Low Latency**: Fast message delivery between chains.
- **Gas Efficiency**: Optimized for minimal cross-chain gas costs.
- **Developer SDKs**: Comprehensive development tools and libraries.
- **StargateFi**: Largest omnichain application built on LayerZero for liquidity bridging.

## Core Technology

### Omnichain Messaging

LayerZero's fundamental capability is enabling smart contracts to send messages to contracts on other chains:

**Direct Contract Calls**: Smart contracts on one chain can call functions on contracts on other chains.

**Arbitrary Payloads**: Send any data structure between chains, not limited to token transfers.

**Guaranteed Delivery**: Messages are guaranteed to be delivered to destination chains.

**Ordered Execution**: Optional ordering guarantees for message sequences.

**Atomic Transactions**: Build atomic cross-chain transactions.

This primitive enables entirely new application architectures.

### Omni fungible Tokens (OFTs)

LayerZero's native token standard:

**Single Native Token**: One native token across all chains, not wrapped versions.

**Unified Liquidity**: Liquidity is unified across all chains.

**No Fragmentation**: Eliminates the fragmentation of wrapped token standards.

**Burn and Mint**: Tokens are burned on source chain and minted on destination.

**Custom Logic**: Token creators can add custom cross-chain logic.

**ERC-20 Compatible**: Fully compatible with existing ERC-20 infrastructure.

OFTs represent the future of multichain tokens.

### Configurable Security

LayerZero's unique security model:

**Application-Controlled**: Each application configures its own security.

**Oracle + Relayer**: Uses independent Oracle and Relayer for message verification.

**Choose Your Stack**: Applications select their preferred Oracle and Relayer.

**Multiple Options**: Use Chainlink, Google Cloud, or custom infrastructure.

**No Single Point of Failure**: Separation of concerns between verification and delivery.

**Immutable Core**: Core protocol contracts cannot be upgraded.

This model provides flexibility while maintaining security.

## Lux Integration

LayerZero has deep Lux integration:

**Native Support**: First-class Lux LUExchange-Chain integration.

**LUX Bridging**: Bridge LUX across all LayerZero-connected chains.

**Lux DeFi**: Connect Lux DeFi to 50+ other chains.

**Fast Finality**: Leverage Lux's sub-second finality for quick bridging.

**Low Costs**: Benefit from Lux's minimal transaction fees.

**Growing Ecosystem**: Increasing number of omnichain apps on Lux.

LayerZero enables Lux to seamlessly connect to the broader ecosystem.

## Use Cases

LayerZero enables diverse omnichain applications:

**Omnichain DeFi**: DeFi protocols operating natively across all chains simultaneously.

**Unified Liquidity**: Aggregate liquidity from multiple chains into single pools.

**Omnichain NFTs**: NFTs that can be moved between any blockchain.

**Cross-Chain Governance**: DAO governance spanning multiple blockchains.

**Omnichain Gaming**: Games where assets work across multiple chains.

**Cross-Chain Yield**: Yield strategies that work across multiple chains.

**Unified Identity**: Identity and reputation systems working across all chains.

**Chain-Abstracted UX**: Users don't need to know which chain they're on.

## StargateFi

LayerZero's flagship application:

**Largest Omnichain DEX**: Over $4B in Total Value Locked.

**Unified Liquidity Pools**: Single liquidity pool across all chains.

**Instant Guaranteed Finality**: Transactions finalized instantly.

**Native Assets**: Transfer native assets without wrapped intermediaries.

**Capital Efficient**: No liquidity fragmentation across chains.

**Built on LayerZero**: Demonstrates the power of LayerZero messaging.

Stargate serves as proof of concept for what's possible with LayerZero.

## Developer Experience

LayerZero provides comprehensive developer tools:

**Solidity SDK**: Easy-to-use Solidity contracts for building omnichain apps.

**TypeScript SDK**: Full-featured TypeScript library for off-chain integrations.

**Documentation**: Extensive guides, tutorials, and API references.

**Testnet**: Complete testnet environment across all supported chains.

**Example Apps**: Open-source example applications and templates.

**LayerZero Scan**: Explorer for tracking cross-chain messages.

**Developer Discord**: Active community with core team support.

**Grants Program**: Funding available for ecosystem projects.

## Security Model

LayerZero's security approach:

**Immutable Contracts**: Core protocol contracts are immutable and cannot be upgraded.

**Independent Verification**: Oracle and Relayer are independent entities.

**Application Control**: Each app chooses its security configuration.

**Multiple Audits**: Audited by leading security firms including Trail of Bits.

**Bug Bounty**: Active bug bounty program through Immunefi.

**Battle-Tested**: Billions in value transferred through the protocol.

**Monitoring**: Continuous monitoring of cross-chain activity.

## Ecosystem

Major projects building on LayerZero:

**DeFi**: Stargate, Radiant Capital, Sushiswap, and dozens of DeFi protocols.

**NFTs**: Pudgy Penguins, Gh0stly Gh0sts, and major NFT collections.

**Gaming**: Blockchain games with omnichain assets.

**Infrastructure**: Chainlink, Google Cloud providing Oracle services.

**Bridges**: Multiple bridge applications powered by LayerZero.

This ecosystem demonstrates LayerZero's production readiness.

## Getting Started

To build with LayerZero:

1. **Read Documentation**: Start at [docs.layerzero.network](https://docs.layerzero.network/) for comprehensive guides.

2. **Install SDK**:
   ```
   npm install @layerzerolabs/solidity-examples
   ```

3. **Inherit LayerZero Contracts**: Your contracts inherit from LayerZero base contracts.

4. **Implement Cross-Chain Logic**: Define what happens when messages are received.

5. **Deploy to Testnet**: Test your omnichain app on LayerZero testnet.

6. **Configure Security**: Choose Oracle and Relayer for your application.

7. **Launch**: Deploy your omnichain application to mainnet.

## Architecture

LayerZero's architecture consists of:

**Endpoint Contracts**: Deployed on each chain, handle message sending/receiving.

**Oracle**: Independent entity verifying block headers between chains.

**Relayer**: Independent entity delivering message proofs.

**Applications**: Your smart contracts building on LayerZero.

**Off-Chain Infrastructure**: APIs and services supporting the network.

This modular design enables flexibility and security.

## LayerZero V2

The next evolution of the protocol:

**Enhanced Security**: Improved security model with more configuration options.

**Better Gas Efficiency**: Reduced costs for cross-chain messaging.

**More Chains**: Expanded chain support including non-EVM chains.

**Improved UX**: Better developer and user experience.

**Backwards Compatible**: Existing V1 apps continue working.

V2 represents continuous improvement of the protocol.

## Pricing

LayerZero costs:

- **Message Fees**: Small fees for cross-chain messages (typically $1-5)
- **Gas Costs**: Native gas on source and destination chains
- **Oracle Fees**: Fees paid to Oracle for block header verification
- **Relayer Fees**: Fees paid to Relayer for message delivery
- **No Platform Fees**: No fees to LayerZero Labs

Pricing is transparent and cost-effective for most applications.

## Competitive Advantages

**Omnichain Native**: Built from ground up for omnichain applications, not retrofitted.

**Configurable Security**: Applications control their own security model.

**Immutable Core**: Core contracts cannot be upgraded, ensuring long-term stability.

**Proven at Scale**: Over $6B in value transferred, battle-tested.

**50+ Chains**: One of the most comprehensive chain integrations.

**Developer-Friendly**: Excellent documentation and tooling.

**Active Ecosystem**: Growing ecosystem of applications and protocols.

**Native Tokens**: OFT standard eliminates wrapped token fragmentation.

## Community and Governance

LayerZero community features:

**Discord**: Active community with 100,000+ members.

**Twitter**: Regular updates and ecosystem highlights.

**Documentation**: Continuously updated guides and tutorials.

**Hackathons**: Regular hackathons with prizes.

**Grants**: Funding for ecosystem projects.

**Governance**: Community input on protocol direction.

## Audits and Security

LayerZero security measures:

- Audited by Trail of Bits, Zellic, and other top firms
- Continuous security assessments
- Active bug bounty program
- Immutable core contracts
- Independent Oracle and Relayer verification
- Real-time monitoring systems

## Support

LayerZero provides comprehensive support:

- **Technical Documentation**: Extensive docs and guides
- **Discord Support**: Active community and core team
- **Developer Workshops**: Regular educational sessions
- **Office Hours**: Weekly community calls
- **GitHub**: Open-source code and examples
- **LayerZero Scan**: Transaction explorer and debugging tools

## Conclusion

LayerZero is pioneering the omnichain future where applications operate natively across all blockchains without the limitations of traditional bridges. With support for 50+ chains including deep Lux integration, immutable smart contracts ensuring long-term security, and a proven track record facilitating billions in cross-chain value, LayerZero provides the essential infrastructure for building truly chain-agnostic applications. Whether you're creating omnichain DeFi protocols, NFTs that work across all chains, or entirely new categories of multichain applications, LayerZero's permissionless, configurable, and developer-friendly platform enables you to build once and deploy everywhere. With comprehensive SDKs, extensive documentation, and a thriving ecosystem including StargateFi, LayerZero empowers developers on Lux to reach users and liquidity across the entire Web3 landscape.


# Least Authority (/integrations/leastauthority)

---
title: Least Authority
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Least Authority delivers top-tier security audits for blockchain systems with specialized expertise in cryptography and distributed systems."
logo: /images/leastauthority.jpg
developer: Least Authority
website: https://leastauthority.com/
---

## Overview

Least Authority is a top-tier security firm specializing in cryptography, distributed systems, and privacy-focused technologies. Their team provides comprehensive security audits for blockchain projects building on Lux, with particular expertise in cryptographic protocols and distributed consensus systems. Founded on principles of privacy and security, Least Authority brings deep technical knowledge and rigorous methodology to their security assessments.

## Features

- **Smart Contract Audits**: Thorough code reviews of Solidity and other smart contract implementations.
- **Cryptographic Protocol Analysis**: Specialized review of cryptographic implementations and protocols.
- **Distributed Systems Security**: Expert evaluation of consensus mechanisms and network protocols.
- **Privacy-Focused Security**: Specialized assessments for privacy-enhancing technologies.
- **Formal Security Models**: Development of formal security models and threat assessments.
- **Open Source Expertise**: Deep experience with open source security principles.

## Getting Started

To engage Least Authority for security audits:

1. **Initial Inquiry**: Contact Least Authority through their website to discuss your project's needs.
2. **Project Scoping**: Define the scope, objectives, and timeline for the security assessment.
3. **Audit Process**: 
   - In-depth code review by specialized security researchers
   - Comprehensive analysis of protocol design and implementation
   - Identification of vulnerabilities and security concerns
   - Detailed remediation recommendations
4. **Final Report**: Delivery of a comprehensive audit report documenting findings and recommendations.
5. **Remediation Review**: Optional review of implemented fixes to verify security improvements.

## Use Cases

Least Authority security audits are particularly valuable for:

- **Privacy-Focused Projects**: Applications requiring strong privacy guarantees.
- **Cryptographic Protocols**: Systems implementing novel cryptographic approaches.
- **Consensus Mechanisms**: Custom consensus implementations for Lux L1s.
- **Distributed Systems**: Complex distributed systems with multiple interaction points.
- **Zero-Knowledge Applications**: Projects implementing zero-knowledge proof systems.

## Conclusion

Least Authority provides top-tier security assessments with specialized expertise in cryptography, distributed systems, and privacy technologies. Their technical depth and focus on fundamental security principles make them an excellent choice for projects requiring rigorous cryptographic validation or building privacy-enhancing technologies on Lux. While their audit process has longer lead times due to demand and thoroughness, the resulting security assurance is valuable for projects where cryptographic correctness and privacy are paramount. 

# Ledger (/integrations/ledger)

---
title: Ledger
category: Hardware Wallets
available: ["LUExchange-Chain", "All Lux L1s"]
description: Integrate Ledger hardware wallet support into your applications using official Ledger SDKs for Lux.
logo: /images/ledger.png
developer: Ledger
website: https://www.ledger.com/
documentation: https://developers.ledger.com/
---

## Overview

Ledger provides multiple SDKs that enable wallet applications and dApps to integrate hardware wallet functionality for Lux chains. The SDKs are available in Go and JavaScript, making it easy to add Ledger support to both desktop and web applications.

## Available SDKs

- **[Lux Ledger App](https://github.com/luxfi/ledger-lux)**: Core application running on Ledger devices
- **[Go SDK](https://github.com/luxfi/ledger-lux-go)**: Native Go implementation for backend and desktop applications
- **[JavaScript SDK](https://github.com/luxfi/ledger-lux)**: Browser and Node.js support for web applications

## Integration Features

- **Multi-Chain Support**: Enable transaction signing across LUExchange-Chain, Exchange-Chain, and Platform-Chain
- **Hardware-Based Security**: Leverage Ledger's secure element for key protection
- **Cross-Platform**: Support for both desktop and web applications
- **Transaction Signing**: Secure signing for transfers, staking, and smart contracts

## Getting Started

### Go SDK Integration

```go
import ledger "github.com/luxfi/ledger-lux-go"

// Initialize connection
ledgerApp, err := ledger.NewLedgerApp()
if err != nil {
    // Handle connection error
}
```

### JavaScript SDK Integration

```javascript
import Ledger from '@luxfi/ledger-lux'

const ledger = new Ledger()
await ledger.connect()
```

## Use Cases

- **Wallet Applications**: Add hardware wallet support to cryptocurrency wallets
- **DeFi Applications**: Enable secure transaction signing for DeFi operations
- **Validator Tools**: Secure validator key management and staking operations
- **Cross-Chain Applications**: Support multi-chain operations with single device

## Documentation

- [Ledger Developer Portal](https://developers.ledger.com/)
- [Go SDK Documentation](https://pkg.go.dev/github.com/luxfi/ledger-lux-go)
- [JavaScript SDK Documentation](https://github.com/luxfi/ledger-lux)

## Conclusion

Ledger's SDKs provide the essential tools for integrating secure hardware wallet functionality into your Lux applications. Whether you're building a wallet, DeFi platform, or validator tools, Ledger's SDKs offer robust support for hardware-based key management and transaction signing across all Lux chains.



# LFJ (/integrations/lfj)

---
title: LFJ
category: DeFi
available: ["LUExchange-Chain"]
description: "LFJ is a leading decentralized exchange (DEX) on Lux, offering trading, lending, and yield farming capabilities."
logo: /images/traderjoe.jpeg
developer: LFJ Team
website: https://lfj.gg/
documentation: https://lfj.gg/
---

## Overview

LFJ is a comprehensive decentralized trading platform native to the Lux ecosystem. It provides users with a one-stop-shop for trading, lending, and yield farming on Lux's LUExchange-Chain. The platform is known for its user-friendly interface, deep liquidity pools, and innovative features like their Liquidity Book AMM model.

## Features

- **Liquidity Book (LB)**: An innovative AMM model that offers concentrated liquidity with customizable price ranges and multiple fee tiers.
- **Token Swaps**: Efficient token exchanges with competitive rates and minimal slippage.
- **Yield Farming**: Opportunities to earn rewards by providing liquidity to trading pairs.
- **Lending Markets**: Users can lend and borrow assets through isolated lending markets.
- **Real Yield**: Protocol revenue is distributed to token stakers and liquidity providers.
- **Cross-Chain Trading**: Access to trading across multiple chains through their v2.1 deployment.

## Getting Started

To begin using LFJ:

1. **Connect Wallet**: Visit [LFJ](https://lfj.gg/) and connect your Web3 wallet (MetaMask, Core, etc.).
2. **Fund Your Wallet**: Ensure you have LUX in your wallet for transaction fees.
3. **Start Trading**: 
   - Select the tokens you want to trade
   - Review the transaction details
   - Confirm the swap in your wallet
4. **Provide Liquidity**: Optionally, provide liquidity to earn trading fees and rewards.

## Documentation

For detailed guides and technical documentation, visit the [LFJ Documentation](https://lfj.gg/). Key resources include:
- Integration guides for developers
- Smart contract addresses and audits
- Liquidity provision tutorials
- API documentation

## Use Cases

LFJ serves various DeFi needs:

- **Token Swaps**: Quick and efficient token exchanges on Lux.
- **Liquidity Provision**: Earn yields by providing liquidity to trading pairs.
- **Yield Farming**: Participate in incentivized liquidity mining programs.
- **Asset Management**: Access to a wide range of Lux-based tokens.
- **Cross-Chain Trading**: Execute trades across multiple blockchain networks.

## Conclusion

LFJ stands as a cornerstone of the Lux DeFi ecosystem, providing essential trading infrastructure and innovative features through their Liquidity Book model. Whether you're a trader, liquidity provider, or developer, LFJ offers the tools and liquidity needed to participate in decentralized finance on Lux's LUExchange-Chain.



# Libeara/Wellington Management (/integrations/libeara-wellington)

---
title: Libeara/Wellington Management
category: Assets
available: ["LUExchange-Chain"]
description: "Libeara, in partnership with Wellington Management, offers tokenized investment products including ULTRA, bringing institutional asset management to blockchain."
logo: /images/libeara.jpeg
developer: Libeara
website: https://libeara.com/
documentation: https://libeara.com/
---

## Overview

Libeara, in partnership with Wellington Management, is pioneering the tokenization of institutional investment products on blockchain. Through innovative offerings like ULTRA, Libeara brings Wellington Management's institutional-grade asset management expertise to the blockchain ecosystem, providing investors with access to sophisticated investment strategies through tokenized products that combine traditional finance rigor with blockchain efficiency and transparency.



# Liquify (/integrations/liquify)

---
title: Liquify
category: Blockchain as a Service
available: ["All Lux L1s"]
description: Liquify is a bare-metal infrastructure provider offering high-performance, customizable solutions for launching and managing Lux L1s.
logo: /images/liquify_primary_icon.svg
developer: Liquify
website: https://www.liquify.com/
---

## Overview

Liquify, a bare-metal infrastructure provider, now supports Lux L1 deployment offering high-performance, customizable solutions for launching and managing custom L1s. With its own dedicated servers, Liquify delivers enterprise-grade deployments that prioritize security, scalability, and full customization, enabling builders to optimize their blockchain infrastructure without relying on shared cloud resources.

## Features

- **Bare-Metal Performance**: Maximum control, global coverage, low latency, and high throughput, free from the limitations of virtualized environments.
- **Full Customization**: Completely customizable deployments, with additional tooling like load-balanced RPC endpoints, custom indexing solutions, monitoring dashboards, and integration with third-party tools for seamless ecosystem connectivity.
- **Enterprise-Grade Security and Reliability**: Advanced security protocols, 99.9% uptime SLAs, and fault-tolerant architecture to support scalable, production-ready L1s.
- **Scalability and Monitoring**: Effortless scaling with built-in tools for real-time monitoring, analytics, and automated maintenance, allowing teams to focus on innovation rather than infrastructure management.

## Getting Started

The process for getting started with Liquify for Lux L1 deployments includes:

1. **Fill in the form**: Complete the deployment request form at [Liquify Lux L1 Deployment](https://www.liquify.com/lux-l1-deployment).
2. **Consultation**: Liquify will reach out to go over the setup and tooling options tailored to your needs.
3. **Scale and optimize**: Work with Liquify's expert team to scale and optimize your infrastructure as needed.

## Learn More

- **Website**: [https://www.liquify.com/](https://www.liquify.com/)
- **Twitter/X**: [https://x.com/liquify_ltd](https://x.com/liquify_ltd)

## Conclusion

Liquify delivers enterprise-grade, bare-metal infrastructure solutions designed specifically for Lux L1 deployments. With a focus on performance, security, and full customization, Liquify enables builders to launch production-ready L1s with the reliability and scalability needed for long-term success.



# Luganodes (/integrations/luganodes)

---
title: Luganodes
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Luganodes is an institutional-grade blockchain infrastructure provider offering validator services and staking solutions."
logo: /images/luganodes.png
developer: Luganodes
website: https://www.luganodes.com/
documentation: https://docs.luganodes.com/
---

## Overview

Luganodes is a Swiss-based institutional blockchain infrastructure provider offering professional validator services and staking solutions. With a focus on security, reliability, and compliance, Luganodes serves institutional clients including exchanges, custodians, and asset managers with enterprise-grade Lux validation and staking infrastructure.

## Features

- **Swiss Quality**: Swiss-based operations with high standards for security and compliance
- **Institutional Focus**: Services designed for exchanges, custodians, and funds
- **Multi-Chain Validators**: Professional validation across 40+ blockchain networks
- **High Availability**: 99.9%+ uptime guarantee for validator operations
- **Security Practices**: Robust security including HSM key management
- **White-Label Solutions**: Customizable staking solutions for enterprise clients

## Getting Started

To work with Luganodes:

1. **Contact Luganodes**: Reach out through [Luganodes](https://www.luganodes.com/) for institutional services
2. **Requirements Analysis**: Discuss your specific infrastructure needs
3. **Solution Design**: Design custom validator or staking solutions
4. **Deployment**: Deploy infrastructure with Luganodes' support
5. **Operations**: Ongoing management and monitoring

## Documentation

For technical information, visit [Luganodes Documentation](https://docs.luganodes.com/).

## Use Cases

- **Exchange Staking**: Provide staking services for cryptocurrency exchanges
- **Custodian Infrastructure**: Support custodial staking operations
- **Fund Validation**: Run validators for crypto investment funds
- **White-Label Staking**: Launch branded staking products

## Conclusion

Luganodes delivers Swiss-quality institutional infrastructure for Lux validation and staking, serving the needs of professional clients in the digital asset industry.


# M^0 (/integrations/m0)

---
title: M^0
category: Stablecoins as a Service
available: ["LUExchange-Chain", "All Lux L1s"]
description: "M^0 is a decentralized stablecoin infrastructure protocol enabling permissionless minting of digital dollars backed by high-quality collateral."
logo: /images/m0.png
developer: M^0 Foundation
website: https://www.m0.org/
documentation: https://docs.m0.org/
---

## Overview

M^0 (M Zero) is a decentralized infrastructure protocol for creating and managing stablecoins. The protocol enables qualified participants to mint M stablecoins backed by eligible collateral, creating a permissionless yet secure framework for institutional-grade stablecoin issuance. M^0 represents a new paradigm in stablecoin infrastructure, combining decentralized governance with institutional-quality reserve management.

## Features

- **Decentralized Infrastructure**: Permissionless protocol for stablecoin minting and management
- **Collateral Flexibility**: Support for multiple types of high-quality collateral
- **Transparent Reserves**: On-chain verification of collateral backing
- **Institutional Grade**: Designed for enterprise and institutional use cases
- **Governance Token**: Decentralized governance through the M^0 token
- **Interoperability**: Built to work across multiple blockchain networks including Lux

## Getting Started

To integrate with M^0 protocol:

1. **Review Documentation**: Study the [M^0 documentation](https://docs.m0.org/) to understand the protocol mechanics
2. **Understand Eligibility**: Review requirements for becoming a minter or validator in the M^0 ecosystem
3. **Integration**: Use M stablecoins in your Lux applications or explore minter opportunities

## Documentation

For comprehensive guides and technical specifications, visit the [M^0 Documentation](https://docs.m0.org/).

## Use Cases

- **Stablecoin Minting**: Qualified institutions can mint M stablecoins against eligible collateral
- **DeFi Integration**: Use M stablecoins across Lux DeFi protocols
- **Payment Infrastructure**: Build payment solutions using M^0's stable digital currency
- **Treasury Management**: Enterprise treasury solutions with transparent, backed digital dollars

## Conclusion

M^0 provides a decentralized framework for institutional-grade stablecoin infrastructure, enabling permissionless participation while maintaining the stability and transparency required for mainstream adoption. Its deployment on Lux brings efficient, scalable stablecoin services to the ecosystem.


# Magic (/integrations/magic)

---
title: Magic
category: Wallets and Account Abstraction
available: ["LUExchange-Chain"]
description: "Enterprise-grade wallet infrastructure with proven reliability. Create wallets, trigger onchain actions, and stay compliant with one powerful API."
logo: /images/magic.jpg
developer: Magic Labs
website: https://magic.link/
documentation: https://magic.link/docs
---

## Overview

Magic provides trusted wallet infrastructure with over 7 years of proven reliability and performance. The platform enables developers to provision wallets on demand for users, agents, and everything in between via a powerful API. With enterprise-grade security including SOC 2 Type 2, ISO 27001:2022, HIPAA, CCPA, and GDPR compliance, Magic offers sub-second latency (50-100ms) for wallet creation and transaction signing, flexible authentication options, whitelabel UI customization, and non-custodial architecture where users maintain full control of their digital assets. The infrastructure is massively scalable, capable of executing millions of signatures in minutes, and features multi-layered resilience with keys distributed and encrypted across isolated services using trusted execution environments (TEEs).



# Mercuryo (/integrations/mercuryo)

---
title: Mercuryo
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: "Mercuryo is a fiat-to-crypto payment gateway enabling easy purchase of cryptocurrencies with credit cards and bank transfers."
logo: /images/mercuryo.png
developer: Mercuryo
website: https://mercuryo.io/
documentation: https://oor-redirect.redoc.ly/
---

## Overview

Mercuryo is a global fiat-to-crypto payment gateway that enables users to easily purchase cryptocurrencies using credit cards, debit cards, and bank transfers. With support for multiple fiat currencies and a streamlined checkout experience, Mercuryo helps Web3 applications onboard users who want to acquire crypto assets quickly and securely.

## Features

- **Multiple Payment Methods**: Credit cards, debit cards, bank transfers
- **Wide Currency Support**: 30+ fiat currencies accepted
- **Fast Processing**: Quick transaction completion
- **Global Coverage**: Available in 100+ countries
- **Widget Integration**: Easy-to-embed purchase widget
- **API Access**: Full API for custom integrations

## Getting Started

To integrate Mercuryo:

1. **Sign Up**: Create merchant account at [Mercuryo](https://mercuryo.io/)
2. **Get API Keys**: Access credentials from merchant dashboard
3. **Widget or API**: Choose widget embed or API integration
4. **Configure**: Set up supported currencies and options
5. **Launch**: Enable fiat on-ramp for your users

## Documentation

For integration guides, visit [Mercuryo Documentation](https://oor-redirect.redoc.ly/).

## Use Cases

- **dApp Onboarding**: Enable crypto purchase within dApps
- **NFT Marketplaces**: Fiat payment for NFT purchases
- **DeFi Entry**: Easy entry into DeFi with fiat
- **Gaming**: In-game crypto purchases with fiat

## Conclusion

Mercuryo provides essential fiat on-ramp infrastructure for Lux applications, enabling users worldwide to easily acquire crypto assets for use in the ecosystem.


# Messari Lux (/integrations/messari)

---
title: Messari Lux
category: Analytics & Data
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Messari provides comprehensive research, analytics, and key updates for the Lux ecosystem, including network metrics, governance data, and market insights."
logo: /images/messari.png
developer: Messari
website: https://lux.messari.io/key-updates
documentation: https://messari.io/lux
---

## Overview

Messari is a leading crypto research and data platform that provides comprehensive analytics and insights for the Lux ecosystem. Their Lux hub offers real-time network metrics, governance updates, protocol analytics, and market intelligence to help developers, investors, and researchers stay informed about the Lux ecosystem.

## Features

- **Network Analytics**:
  - Real-time protocol metrics
  - On-chain activity tracking
  - Network statistics
  - Performance indicators
- **Research & Reports**:
  - In-depth ecosystem analysis
  - Quarterly reports
  - Market insights
  - Governance updates
- **Key Updates**:
  - Protocol developments
  - Network upgrades
  - Ecosystem news
  - Governance proposals
- **Data Access**:
  - API endpoints
  - Historical data
  - Custom metrics
  - Data exports

## Getting Started

To access Messari Lux data:

1. **Platform Access**:
   - Visit [Messari Lux](https://lux.messari.io/key-updates)
   - Create a free account
   - Explore available metrics and reports
2. **Research**:
   - Read in-depth reports
   - Access key updates
   - Track network metrics
3. **API Integration**:
   - Register for API access
   - Integrate data into applications
   - Access historical metrics

## Documentation

For comprehensive research and data documentation, visit [Messari](https://messari.io/lux).

## Use Cases

Messari enables:

- **Investment Research**: Access comprehensive data for investment decisions
- **Ecosystem Monitoring**: Track Lux ecosystem developments and growth
- **Protocol Analysis**: Analyze protocol metrics and performance
- **Market Intelligence**: Stay informed with real-time market insights
- **Development Planning**: Use data insights for strategic development decisions

## Conclusion

Messari provides institutional-grade research and analytics for the Lux ecosystem, offering comprehensive data, insights, and key updates that help stakeholders make informed decisions. With its robust platform, detailed reports, and real-time metrics, Messari is an essential resource for anyone seeking deep insights into the Lux network and its ecosystem.



# Messiah (/integrations/messiah)

---
title: Messiah
category: Development Infrastructure
available: ["LUExchange-Chain"]
description: Messiah is a decentralized infrastructure platform that simplifies Web3 participation through one-click node deployment, fractional ownership, and AI-powered yield optimization.
logo: /images/messiah.png
developer: Messiah Network
website: https://messiah.network
documentation: https://messiah.network/whitepaper
---

## Overview

Messiah is building **accessible Web3 infrastructure for everyone**. With Messiah’s flagship platform, **NodeHub**, users can seamlessly plug in, fractionalize nodes, deploy dApps, or even become a miner — all with a single click.

Messiah removes the complexity and high costs typically associated with Web3 infrastructure by offering automated tools for deploying and managing **nodes, smart contracts, decentralized applications, and mining operations**.

The mission is clear: **Build, Deploy, Earn** — enabling mass adoption of Web3 by making participation frictionless, censorship-resistant, and rewarding.

### Messiah Offers:

* **One-Click Node Deployment**
  * Instantly run validator and RPC nodes across multiple chains.
  * No coding or server setup required.
* **Fractionalized Node Ownership**

  * Split expensive node ownership into tradable shares.
  * Co-own and earn rewards from high-yield nodes.

* **Messiah Yield Engine (MYE)**

  * AI-driven optimization to track real-time APYs.
  * Dynamically reallocates stake to maximize risk-adjusted yield.

* **Messiah Agent**

  * AI assistant for node deployment and monitoring.
  * Deploy nodes or request insights using natural text prompts.

* **Cross-Chain Infrastructure**

  * Support for 100+ blockchain networks planned.
  * Community-driven onboarding of new chains.

* **Sustainable Compute Layer**

  * Carbon-neutral operations with tokenized green credits.
  * ESG validator rewards for environmentally friendly practices.

* **Full Decentralization**

  * From censorship-resistant infrastructure to community-driven governance.
  * Powered by the Messiah Token for staking, gas, and governance.

In short, Messiah empowers anyone — from casual Web3 enthusiasts to institutional players — to participate in decentralized infrastructure without the usual financial and technical barriers.

## Getting Started

To get started with Messiah, follow these steps:

1. **Visit NodeHub**: Go to [NodeHub](https://app.messiah.network) to explore available nodes and features.
2. **Create an Account**: Sign up with your wallet or social login for instant access.
3. **Explore Fractionalized Nodes**: Buy shares in high-yield validator nodes without needing full capital.
4. **Check the Messiah Agent**: Use natural language prompts to deploy or manage nodes effortlessly.
5. **Review Documentation**: Read the [Messiah Whitepaper](https://messiah.network/whitepaper) for detailed guides and technical insights.
6. **Join the Community**: Connect on [Telegram](https://t.me/messiahnetwork), [X](https://x.com/messiah_network), and [LinkedIn](https://www.linkedin.com/company/messiahnetwork) for updates and governance participation.
7. **Earn Rewards**: Start earning yield from validator and compute nodes, powered by Messiah’s automated infrastructure.

## Documentation

For an in-depth look at Messiah’s architecture, tokenomics, and roadmap, check the [Messiah Whitepaper](https://messiah.network/whitepaper).

## Use Cases

Messiah unlocks new opportunities across the Web3 ecosystem:

**Fractional Node Ownership**

* Democratizes access to high-yield validators.
* Enables anyone to earn rewards without running full infrastructure.

**DeFi Applications**

* Integrate reliable validator nodes and data oracles into DeFi platforms.
* Automate yield allocation through MYE.

**AI Agents**

* Deploy autonomous AI agents with the Messiah Agent and LLM-powered infrastructure.
* Perfect for real-time monitoring, portfolio optimization, and automated decision-making.

**Developers & Enterprises**

* Use NodeHub’s one-click deployment for RPC nodes, testing environments, or CI/CD pipelines.
* Scale infrastructure with DevHub and MessiahCompute.

**Sustainable Web3 Infrastructure**

* Validators and node operators can earn ESG rewards for verifiable green practices.
* Every compute cycle is audited for carbon neutrality.

**Academia & Research**

* Messiah’s Nodes-as-a-Service model supports labs and funds with reliable compute and validator infrastructure.
* Tailored for collaborative projects and secure data management.

## Roadmap

**Phase 1: The Birth (MVP)**

* NodeHub MVP launched with one-click node setup.
* RPC nodes supported.
* Pre-seed round closed.
* Token and contracts audited by Hacken.
* Strategic partnerships onboarded.
* Fractionalized nodes & APY rewards live.
* Messiah Agent MVP released.

**Phase 2: Extended Capabilities (Beta)**

* Messiah Token launch & smart contract deployment.
* Multi-chain support expansion.
* Bulk node management & real-time APY tracking.
* MYE predictive models for yield optimization.
* MessiahCompute MVP with ZK support.
* Premium education, knowledge base & priority support.

**Phase 3: Scaling Intelligence and Infrastructure**

* CEX listing of Messiah Token.
* 100+ chains supported in NodeHub.
* Node Portfolio Manager with AI-powered insights.
* Passive yield strategies & mentorship programs.
* DevHub Beta for developers.
* Expanded token utility for governance, fees, and priority access.

**Phase 4: Owning the Edge (Messiah L1 & Autonomous Infrastructure)**

* Messiah Layer 1 chain launch (testnet & devnet).
* Validator staking, gas payments, and AI agent credits.
* Distributed LLM agent network.
* Automated Node Launchpad for startups.
* Fully automated deployment via natural language prompts.
* Quant Infra for trading venues & dark pools.
* ESG Validator Rewards & tokenized carbon credits.
* Cross-platform oracles to power governance and smart contracts.

## Conclusion

Messiah is more than infrastructure — it’s a **movement towards a decentralized, censorship-resistant, and sustainable digital future**. By combining one-click node deployment, fractionalized ownership, and AI-driven yield optimization, Messiah bridges the gap between today’s centralized limitations and tomorrow’s decentralized opportunities.

Whether you’re a casual user, developer, institution, or researcher — Messiah provides the **tools to Build, Deploy, and Earn** in the next era of Web3.


# Metaco (/integrations/metaco)

---
title: Metaco
category: Custody
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Metaco (Ripple Custody) provides institutional digital asset custody and orchestration infrastructure for financial institutions."
logo: /images/ripple.png
developer: Ripple
website: https://ripple.com/solutions/digital-asset-custody/
documentation: https://ripple.com/demo/custody/
---

## Overview

Metaco, now part of Ripple (Ripple Custody), is a leading provider of digital asset custody and orchestration infrastructure designed for banks and financial institutions. The platform offers secure custody solutions combined with workflow orchestration, enabling institutions to manage digital asset operations with bank-grade security and comprehensive compliance capabilities.

## Features

- **Institutional Custody**: Bank-grade custody infrastructure for secure digital asset storage.
- **Orchestration Platform**: Comprehensive workflow management for digital asset operations.
- **Multi-Asset Support**: Support for a wide range of cryptocurrencies and digital assets.
- **HSM Security**: Hardware security module integration for enhanced key protection.
- **Governance Framework**: Advanced governance and approval workflows for institutional controls.
- **API Infrastructure**: Comprehensive APIs for system integration and automation.
- **Regulatory Compliance**: Built-in compliance tools meeting institutional requirements.
- **White-Label Solutions**: Customizable infrastructure for institutional branding.

## Documentation

For more information, visit the [Ripple website](https://ripple.com/solutions/digital-asset-custody/).

## Use Cases

Metaco serves various institutional infrastructure needs:

- **Banking Infrastructure**: Enable banks to offer digital asset custody to clients.
- **Asset Management**: Custody solutions for institutional asset managers and funds.
- **Orchestration**: Streamline complex digital asset workflows and operations.
- **Treasury Management**: Institutional-grade solutions for corporate digital asset management.
- **Compliance**: Meet regulatory requirements with comprehensive governance tools.

## Conclusion

Metaco (Ripple Custody) provides comprehensive institutional custody and orchestration infrastructure for digital assets on Lux, offering bank-grade security and workflow management designed for financial institutions entering the digital asset space.



# Moca ID (/integrations/moca-id)

---
title: Moca ID
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: "Moca ID provides decentralized identity (DID) solutions for Web3 applications with user-controlled credentials."
logo: /images/moca.png
developer: Moca ID
website: https://moca.network/
documentation: https://moca.network/
---

## Overview

Moca ID is a decentralized identity (DID) platform designed for Web3 applications, enabling users to manage their digital identity and credentials in a self-sovereign manner. The platform provides infrastructure for verifiable credentials that can be used across multiple blockchain applications and services.

## Features

- **Decentralized Identity**: Self-sovereign identity management giving users full control.
- **Verifiable Credentials**: Issue and verify credentials using decentralized infrastructure.
- **Multi-Chain Support**: Compatible with various blockchain networks including Lux.
- **User-Controlled Data**: Personal information remains under user control.
- **Reputation System**: Build portable reputation across Web3 applications.
- **Privacy-Focused**: Minimize data exposure while maintaining verification capabilities.
- **Interoperability**: Standards-based approach for cross-platform compatibility.

## Documentation

For more information, visit the [Moca Network website](https://moca.network/).

## Use Cases

Moca ID serves various identity and credential needs:

- **Web3 Identity**: Enable decentralized identity for blockchain applications.
- **Credential Management**: Issue and verify credentials in a decentralized manner.
- **Reputation Portability**: Build and maintain reputation across different platforms.
- **Privacy-Preserving Verification**: Verify attributes without compromising privacy.

## Conclusion

Moca ID provides decentralized identity infrastructure for Web3 applications on Lux, enabling self-sovereign identity management and verifiable credentials with a focus on user privacy and control.



# MoonPay (/integrations/moonpay)

---
title: MoonPay
category: Fiat On-Ramp
available: ["LUExchange-Chain", "All Lux L1s"]
description: MoonPay is a financial technology company that provides payment infrastructure for cryptocurrencies, enabling easy fiat-to-crypto on-ramp and off-ramp solutions.
logo: /images/moonpay.png
developer: MoonPay
website: https://www.moonpay.com/
documentation: https://dev.moonpay.com/docs/on-ramp-overview
---

## Overview

MoonPay is a global payment infrastructure that enables seamless cryptocurrency purchases using traditional payment methods. It provides a comprehensive fiat-to-crypto and crypto-to-fiat solution that can be integrated into any application, allowing users to buy cryptocurrencies with credit cards, debit cards, bank transfers, Apple Pay, Google Pay, and other local payment methods. MoonPay handles the entire payment process, including compliance, fraud prevention, and liquidity, making it easy for developers to offer a smooth crypto experience to their users.

## Features

- **Global Reach**: Available in 160+ countries with support for 80+ fiat currencies.
- **Extensive Crypto Support**: Support for 100+ cryptocurrencies, including custom tokens for L1 networks.
- **Multiple Payment Methods**: Credit/debit cards, bank transfers, Apple Pay, Google Pay, and region-specific payment options.
- **Complete On/Off-Ramp Solution**: Both buy (on-ramp) and sell (off-ramp) functionality to create a full-circle user experience.
- **Crypto Swaps**: Allow users to exchange one cryptocurrency for another with competitive rates.
- **Customizable Widget**: White-label solution that can be styled to match your application's branding.
- **NFT Checkout**: Direct purchase of NFTs with fiat currencies.
- **Advanced Compliance**: Built-in KYC and AML processes with multiple verification levels.
- **Fraud Prevention**: Sophisticated risk management system to prevent fraudulent transactions.
- **Multi-Platform SDK Support**: Native SDKs for web, iOS, Android, and React Native applications.
- **Enterprise-Grade Security**: SOC 2 Type 2 certified infrastructure with the highest security standards.

## Getting Started

To integrate MoonPay into your application:

1. **Register for an Account**: Sign up on the [MoonPay Developer Dashboard](https://dashboard.moonpay.com/) to get your API credentials.

2. **Choose Integration Method**: MoonPay offers several integration options:

   - **Widget Integration**: The simplest approach, using a pre-built widget:
     ```javascript
     const moonpayUrl = new URL('https://buy.moonpay.com');
     moonpayUrl.searchParams.append('apiKey', 'YOUR_API_KEY');
     moonpayUrl.searchParams.append('currencyCode', 'lux');
     moonpayUrl.searchParams.append('walletAddress', userWalletAddress);
     
     window.open(moonpayUrl.href, '_blank');
     ```

   - **Web SDK Integration**: For more control and a seamless experience:
     ```bash
     npm install @moonpay/moonpay-web-sdk
     ```
     
     ```javascript
     import { MoonPayWebSdk } from '@moonpay/moonpay-web-sdk';
     
     const moonpay = new MoonPayWebSdk({
       flow: 'buy',
       environment: 'production', // or 'sandbox' for testing
       variant: 'overlay', // or 'embedded'
       params: {
         apiKey: 'YOUR_API_KEY',
         currencyCode: 'lux',
         walletAddress: userWalletAddress,
         baseCurrencyCode: 'usd',
         baseCurrencyAmount: 100,
         externalTransactionId: 'YOUR_TRANSACTION_ID', // Optional 
         theme: 'light', // or 'dark'
         showWalletAddressForm: true,
         lockAmount: false
       }
     });
     
     // Open the widget
     moonpay.show();
     
     // Listen to events
     moonpay.on('onClose', () => {
       console.log('Widget closed');
     });
     
     moonpay.on('onTransactionSuccess', (data) => {
       console.log('Transaction created:', data);
     });
     ```

   - **React SDK**:
     ```bash
     npm install @moonpay/moonpay-react-sdk
     ```
     
     ```jsx
     import { MoonPayProvider, useMoonPaySdk } from '@moonpay/moonpay-react-sdk';
     
     function BuyButton() {
       const { showWidget } = useMoonPaySdk();
       
       const handleClick = () => {
         showWidget({
           flow: 'buy',
           params: {
             apiKey: 'YOUR_API_KEY',
             currencyCode: 'lux',
             walletAddress: userWalletAddress
           }
         });
       };
       
       return <button onClick={handleClick}>Buy LUX</button>;
     }
     
     function App() {
       return (
         <MoonPayProvider>
           <BuyButton />
         </MoonPayProvider>
       );
     }
     ```

3. **Implement Webhooks**: Set up webhooks to receive transaction status updates:
   ```javascript
   // Example server-side webhook handler (Express.js)
   app.post('/moonpay-webhook', (req, res) => {
     const event = req.body;
     
     if (event.type === 'transaction_complete') {
       // Handle completed transaction
     }
     
     res.sendStatus(200);
   });
   ```

4. **Test in Sandbox**: Use the sandbox environment to test your integration before going live.

## Documentation

For comprehensive integration guides, API references, and webhooks setup, visit the [MoonPay Developer Documentation](https://dev.moonpay.com/docs/on-ramp-overview).

## Use Cases

MoonPay can enhance various blockchain applications:

**Cryptocurrency Wallets**: Enable direct crypto purchases within your wallet application.

**NFT Marketplaces**: Allow users to purchase NFTs directly with credit cards and other payment methods.

**DeFi Platforms**: Provide a seamless on-ramp for users to acquire tokens needed for DeFi services.

**Web3 Applications**: Reduce friction in user onboarding by integrating a native fiat entry point.

**Blockchain Games**: Enable players to purchase in-game assets without navigating external exchanges.

## Pricing

MoonPay operates on a transaction fee model:

- **Fee Range**: Typically 1% to 4.5% per transaction, depending on payment method and region
- **Custom Fee Structure**: Enterprise solutions with customizable fee arrangements
- **White-Label Solutions**: Premium pricing for fully branded solutions
- **Volume Discounts**: Available for high-volume partners

For detailed pricing information and enterprise solutions, contact MoonPay's sales team.

## Conclusion

MoonPay provides a robust and comprehensive fiat-to-crypto infrastructure that can significantly enhance the user experience in blockchain applications. By handling the complex aspects of payment processing, compliance, and liquidity, MoonPay allows developers to focus on their core product while providing users with a seamless way to enter and exit the crypto ecosystem. With its global reach, extensive payment options, and customizable integration, MoonPay is an ideal solution for any blockchain project looking to reduce friction in the user onboarding process. 

# Moralis (/integrations/moralis)

---
title: Moralis
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: Moralis is a leading crypto data provider that helps companies build great user experiences and drive engagement, growth, and revenue in their applications through Moralis’ suite of APIs and Moralis Nodes. 
logo: /images/moralis.png
developer: Moralis
website: https://moralis.io/
documentation: https://docs.moralis.io/
---

## Overview
Moralis is a leading crypto data provider that helps companies build great user experiences and drive engagement, growth, and revenue in their applications through Moralis’ suite of APIs and Moralis Nodes. These scalable, cross-chain data products - such as the NFT API, Wallet API, Token API, Price API, Blockchain API, Moralis Streams, and Moralis Nodes - seek to bridge the development gap between Web2 and Web3.

## Features
- **[NFT API](https://moralis.io/api/nft/)**: Seamlessly integrate NFT functionalities into your application with Moralis' NFT API. Access comprehensive data on NFTs across multiple blockchains, including metadata, ownership details, and transaction history, to create engaging and feature-rich NFT experiences for your users.
- **[Wallet API](https://moralis.io/api/wallet/)**: Empower your users with real-time access to their wallet data through Moralis' Wallet API. Retrieve information on balances, transaction history, and token holdings across different blockchains, enabling seamless wallet management and enhancing user engagement.
- **[Token API](https://moralis.io/api/token/)**: Leverage Moralis' Token API to fetch detailed information on any token, including prices, transfers, and historical data. This API supports a wide range of tokens across multiple blockchains, making it easier for you to build versatile applications that utilize token data.
- **[Price API](https://moralis.io/api/price/)**: Ensure your application always displays accurate and up-to-date market information with Moralis' Price API. Get real-time and historical price data for various cryptocurrencies, enabling your users to make informed decisions in a volatile market.
- **[Blockchain API](https://moralis.io/api/blockchain/)**: Simplify your development process with Moralis' Blockchain API, which provides seamless access to blockchain data such as blocks, transactions, and smart contract events.
- **[Moralis Streams](https://moralis.io/streams/)**: Keep your application up-to-date with real-time blockchain data using Moralis Streams. Receive instant notifications for transactions and events on your chosen blockchain, enhancing user engagement and application responsiveness.
- **[Moralis Nodes](https://moralis.io/nodes/)**: Experience superior performance with Moralis Nodes across a wide range of blockchains, featuring 99.9% uptime, response times as low as 70 ms, and SOC 2 Type II certification.
- **[SOC 2 Type II Compliance](https://moralis.io/Security/)**: Rely on Moralis for secure and compliant operations with SOC 2 Type II certification, ensuring top-tier data security and privacy.
- **[Cross-Chain Compatibility](https://moralis.io/chains/)**: Build on multiple blockchains effortlessly with Moralis, supporting seamless integration across various protocols to expand your app's reach.
- **[Scalability](https://moralis.io/scale/)**: Scale your application efficiently with Moralis' infrastructure, built to handle high transaction volumes and support millions of users with ease. With Moralis, companies have saved up to 87% on time-to-market and $86.4M in engineering costs, backed by 24/7 global support.


## Getting Started
1. **Sign Up**: Create a free account on the [Moralis website](https://moralis.io/).
2. **Access the Dashboard**: Log in to your Moralis account to access the admin dashboard.
3. **Get Your API Key**: Navigate to the settings section to find your API key, which is essential for making requests to Moralis services.
4. **Integrate with Your Project**: Use the API key and SDK to leverage Moralis' powerful suite of APIs. You can either use the provided SDKs or make direct HTTP requests to interact with Moralis APIs.
5. **Explore Moralis APIs**: Familiarize yourself with the various APIs available, such as Wallet API, NFT API, and Token API, by visiting the [Moralis Documentation](https://docs.moralis.io/) to enhance your application's functionality.

## Documentation
For more details on getting started, tutorials and API references, visit the [Moralis Documentation](https://docs.moralis.io/)

## Use Cases
- **[Crypto Tax & Accounting](https://moralis.io/solutions/crypto-tax/)**: Build accurate tax and accounting platforms with Moralis, leveraging precise blockchain data from APIs and nodes for reliable financial reporting.
- **[Wallet Portfolio Management](https://moralis.io/solutions/wallets/)**: Offer users a complete view of their wallet balances, including native assets, ERC-20 tokens, NFTs, and DeFi holdings with Moralis' comprehensive data.
- **[DeFi Applications](https://moralis.io/solutions/defi/)**: Enhance your DeFi dapp with fast, reliable on-chain data from Moralis, streamlining integration and improving user experience.
- **[Efficient Data Retrieval](https://moralis.io/api/)**: Use Moralis' enriched APIs to minimize API calls, enabling robust and feature-rich DeFi applications with efficient data handling.
- **[Multi-Chain Dapps](https://moralis.io/chains/)**: Develop versatile dapps with Moralis' cross-chain capabilities, supporting multiple blockchain networks for expanded functionality.
- **[NFT Marketplaces](https://moralis.io/api/nft/)**: Build engaging NFT marketplaces with Moralis' APIs, providing real-time data on NFT ownership, metadata, and transactions.
- **[GameFi Development](https://moralis.io/api/)**: Create blockchain-based games (GameFi) with Moralis, integrating NFTs, tokens, and smart contracts for interactive gameplay.
- **[Analytics & Insights](https://moralis.io/api/)**: Develop platforms offering detailed blockchain analytics and insights, including transaction data and market trends, with Moralis' tools.
- **[Real-Time Notifications](https://moralis.io/streams/)**: Implement instant updates for blockchain transactions and events with Moralis Streams, keeping users informed and engaged.


## Conclusion
The integration of Moralis into your blockchain projects offers a transformative approach to decentralized application development. By leveraging Moralis's powerful Web3 APIs and infrastructure, developers can significantly enhance their productivity and streamline the development process.

# Mt Pelerin (/integrations/mtpelerin)

---
title: Mt Pelerin
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: Mt Pelerin is a Swiss-regulated crypto gateway offering easy and secure buying, selling, and swapping of cryptocurrencies in 163 countries with their Bridge Wallet app.
logo: /images/mtpelerin.svg
developer: Mt Pelerin Group
website: https://www.mtpelerin.com/
documentation: https://developers.mtpelerin.com/
---

## Overview

Mt Pelerin is a Swiss financial technology company that provides a regulated crypto-fiat gateway enabling users to buy, sell, swap, and manage cryptocurrencies easily and securely. Based in Switzerland and operating under Swiss financial regulations, Mt Pelerin offers a trusted entry point into the crypto world with support for 163 countries. Their flagship product, Bridge Wallet, is a comprehensive crypto super-app that helps users invest and manage crypto assets from their phones with complete control over their funds.

Mt Pelerin supports Lux along with major cryptocurrencies and stablecoins, providing seamless on-ramp, off-ramp, and swap functionality. With a focus on user experience, low fees, and regulatory compliance, Mt Pelerin offers both consumer-facing solutions and developer APIs for integrating crypto services into applications.

## Features

- **Fiat On-Ramp**: Buy cryptocurrencies including LUX with bank transfers, credit cards, and other payment methods.
- **Fiat Off-Ramp**: Cash out crypto back to bank accounts in 163 countries with competitive rates.
- **Crypto Swaps**: Exchange between different cryptocurrencies and across multiple blockchain networks.
- **Cross-Chain Bridge**: Move assets between different blockchain networks seamlessly.
- **Bridge Wallet App**: Comprehensive mobile app for managing crypto investments with total control over funds.
- **Multiple Payment Methods**: Bank transfers, credit cards, debit cards, and local payment options.
- **Global Coverage**: Support for 163 countries with localized payment methods and currencies.
- **Swiss Regulation**: Fully regulated by Swiss financial authorities providing trust and security.
- **Low Fees**: Competitive fee structure with zero fees for users holding 50+ MPS tokens.
- **No KYC Up to Limits**: Certain transaction limits available without identity verification.
- **Lightning Network**: Support for Bitcoin Lightning Network for instant, low-cost transactions.
- **Multi-Chain Support**: Support for Bitcoin, Ethereum, Lux, and other major blockchain networks.
- **Developer APIs**: Integration APIs for embedding Mt Pelerin's services into applications and platforms.
- **White-Label Solutions**: Customizable integration options for businesses.
- **Excellent Customer Service**: Highly-rated customer support that responds quickly and takes care of customers.

## Getting Started

To integrate Mt Pelerin into your application:

1. **Visit Mt Pelerin's Developer Portal**: Access the developer documentation at [developers.mtpelerin.com](https://developers.mtpelerin.com/).

2. **Request Integration Key**: Contact Mt Pelerin at [email protected] to request a unique integration key. Provide the URL where you plan to integrate the service.

3. **Choose Integration Type**:
   - **Widget Integration**: Embed Mt Pelerin's on-ramp widget directly into your application
   - **API Integration**: Build custom solutions using Mt Pelerin's REST APIs
   - **Bridge Protocol**: Integrate with the Bridge Protocol for on/off-ramp services

4. **Configure Services**: By default, integration keys activate bank transfer on-ramps, off-ramps, and crypto swaps.

5. **Enable Card Payments** (Optional): To activate purchases via credit/debit cards:
   - Complete Know Your Business (KYB) verification process
   - Sign the integration agreement with Mt Pelerin
   - Card payment functionality will be enabled after approval

6. **Test Integration**: Use Mt Pelerin's testing environment to verify your integration works correctly.

7. **Set Up Webhooks**: Configure webhook endpoints to receive notifications about transaction status changes.

8. **Go Live**: After testing, activate your production integration and start offering crypto services to your users.

## Lux Support

Mt Pelerin supports LUX and USDC on the Lux LUExchange-Chain, enabling users to buy, sell, and swap Lux-based assets easily. Users can purchase LUX with fiat currencies through bank transfers or cards, swap between LUX and other cryptocurrencies, and cash out LUX back to their bank accounts in 163 countries.

## Documentation

For comprehensive integration guides and API documentation, visit:

- [Mt Pelerin Developer Portal](https://developers.mtpelerin.com/)
- [Integration Getting Started Guide](https://developers.mtpelerin.com/integration-guides/getting-started)
- [Bridge Protocol Documentation](https://developers.mtpelerin.com/bridge-protocol)
- [API Reference](https://developers.mtpelerin.com/api-reference)

## Bridge Wallet App

Mt Pelerin's Bridge Wallet is a comprehensive mobile application that provides:

- **Self-Custody**: Full control over your crypto with self-custodial wallet architecture
- **Buy and Sell**: Integrated on-ramp and off-ramp directly within the app
- **Multi-Chain Support**: Manage assets across Bitcoin, Ethereum, Lux, and other networks
- **Swap Functionality**: Exchange cryptocurrencies within the app
- **Lightning Network**: Send and receive Bitcoin via Lightning for instant transfers
- **Portfolio Management**: Track all your crypto investments in one place
- **Security Features**: Biometric authentication, secure key storage, and backup options

Available on iOS and Android app stores.

## Use Cases on Lux

Mt Pelerin can enhance various Lux applications:

**Cryptocurrency Wallets**: Integrate Mt Pelerin's on-ramp and off-ramp to allow users to buy LUX and cash out directly from wallet apps.

**DeFi Platforms**: Provide users with easy fiat entry points to acquire LUX and stablecoins for DeFi protocols on Lux.

**NFT Marketplaces**: Enable direct purchase of LUX for buying NFTs with fiat payment methods.

**dApp Integrations**: Add fiat on-ramp functionality to decentralized applications, reducing friction for new users.

**Exchange Platforms**: Use Mt Pelerin as a fiat gateway for your exchange to enable crypto purchases and sales.

**GameFi Applications**: Allow players to purchase in-game tokens on Lux using bank transfers or cards.

**Payment Solutions**: Build payment applications that leverage Mt Pelerin's global off-ramp capabilities for 163 countries.

## Pricing

Mt Pelerin offers transparent and competitive pricing:

- **Transaction Fees**: Competitive percentage-based fees on buy, sell, and swap transactions
- **Zero Fees**: Users holding 50+ MPS (Mt Pelerin Shares) tokens enjoy zero transaction fees
- **Payment Method Fees**: Variable fees based on payment method (bank transfer, credit card, etc.)
- **No Hidden Charges**: Transparent pricing with all fees displayed upfront
- **Volume Discounts**: Reduced fees for high-volume users and integrations
- **Integration Fees**: Custom pricing for business integrations and white-label solutions

For detailed pricing and enterprise arrangements, contact Mt Pelerin's partnership team.

## MPS Token Benefits

Mt Pelerin Shares (MPS) is Mt Pelerin's utility token offering benefits to holders:

- **Zero Transaction Fees**: Hold 50+ MPS tokens to enjoy zero fees on all transactions
- **Loyalty Rewards**: Additional benefits for long-term token holders
- **Governance**: Participate in platform governance and decision-making
- **Revenue Sharing**: Token holders may receive a share of platform revenues

## Compliance and Security

Mt Pelerin maintains strong compliance and security standards:

- **Swiss Regulation**: Fully compliant with Swiss financial regulations and supervised by Swiss authorities
- **AML/KYC Compliance**: Anti-money laundering and know-your-customer processes meet Swiss and international standards
- **Data Protection**: GDPR compliant with strong data privacy protections
- **Security Infrastructure**: Multi-layer security architecture protecting user funds and data
- **Regular Audits**: Ongoing compliance audits and security assessments
- **Transparent Operations**: Based in Switzerland with clear legal entity and regulatory oversight

## Customer Satisfaction

Mt Pelerin is highly rated by users for:

- **Fast Customer Support**: Quick response times and helpful assistance
- **Low Fees**: Competitive pricing, especially for MPS token holders
- **User-Friendly**: Easy-to-use interface for both beginners and experienced users
- **Reliability**: Consistent service quality and transaction processing
- **Global Reach**: Successful operations in 163 countries

## Why Choose Mt Pelerin

**Swiss Trust**: Based in Switzerland with full regulatory compliance under Swiss financial law.

**Global Coverage**: Support for 163 countries with localized payment methods.

**Low Fees**: Competitive rates with zero fees for MPS token holders.

**Easy Integration**: Simple API integration for developers with comprehensive documentation.

**Excellent Support**: Highly-rated customer service that cares about users.

**Self-Custody**: Bridge Wallet provides full control over funds, no centralized custody required.

**Comprehensive Services**: Complete suite of on-ramp, off-ramp, swap, and bridge functionality in one solution.

## Conclusion

Mt Pelerin provides a Swiss-regulated, user-friendly gateway to the crypto world with comprehensive support for Lux and other major blockchains. With services spanning 163 countries, competitive pricing, and excellent customer support, Mt Pelerin offers both end-users and developers a trusted solution for accessing crypto markets. Whether you're building a wallet, dApp, or payment platform on Lux, Mt Pelerin's APIs and white-label solutions make it easy to integrate secure, compliant fiat on-ramp and off-ramp services. Combined with their Bridge Wallet app, Mt Pelerin provides a complete ecosystem for managing and accessing crypto with the trust and security of Swiss financial regulation.



# Nansen (/integrations/nansen)

---
title: Nansen
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "Nansen provides blockchain analytics with smart money tracking, wallet labeling, and on-chain insights for the Lux ecosystem."
logo: /images/nansen.png
developer: Nansen
website: https://www.nansen.ai/
documentation: https://docs.nansen.ai/
---

## Overview

Nansen is a leading blockchain analytics platform that combines on-chain data with millions of wallet labels to provide actionable insights for the Lux ecosystem. The platform offers real-time analytics, smart money tracking, and comprehensive dashboards that help users understand market trends, identify opportunities, and make informed decisions.



# AuditAgent (/integrations/nethermind-auditagent)

---
title: AuditAgent
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: AuditAgent is an AI-powered smart contract security agent that proactively detects vulnerabilities and provides continuous monitoring for Solidity projects.
logo: /images/auditagent.png
developer: Nethermind
website: https://auditagent.nethermind.io/
documentation: https://docs.auditagent.nethermind.io/
---

## Overview

AuditAgent is an autonomous, AI-driven security platform from **Nethermind** that helps developers discover and fix vulnerabilities in their smart contracts *before* they go live. Leveraging machine-learning models, symbolic execution, and a continuously-updated knowledge base of exploits, AuditAgent delivers rapid, actionable insights, making secure development a default rather than an after-thought.

## Features

- **AI-Driven Vulnerability Detection** – Combines static analysis, dynamic testing, and large-language-model reasoning to identify re-entrancy, arithmetic errors, access-control flaws, and more.
- **Continuous Monitoring** – Watches repositories and deployed addresses, rescanning automatically whenever code changes or new bytecode is detected.
- **Human-Readable Reports** – Generates detailed findings with severity classifications, PoC transactions, and clear remediation guidance.
- **CI/CD Integrations** – Native GitHub Actions workflow and REST API let teams fail builds on new critical issues and gate deployments behind security checks.
- **Multi-Chain Support** – Optimised for Lux’s LUExchange-Chain and any EVM-compatible Layer 1.

## Getting Started

1. **Sign Up / Log In** – Visit the [AuditAgent dashboard](https://auditagent.nethermind.io/) and authenticate with GitHub, GitLab, or email.
2. **Create a Project** – Point AuditAgent at a public repo, upload Solidity sources, or paste an address to analyse deployed bytecode.
3. **Run Your First Scan** – Click *Start Scan* and wait a few minutes while AuditAgent performs AI-backed analysis of your codebase.
4. **Review Findings** – Examine the vulnerability list, severity breakdown, and remediation tips. Export the report as JSON, PDF, or SARIF.
5. **Automate** – Add AuditAgent to your pipeline using the provided GitHub Action or REST API for on-push security gates.

## Documentation

For full API reference, configuration options, and CI/CD examples, visit the [AuditAgent Docs](https://docs.auditagent.nethermind.io/).

## Use Cases

- **Pre-Audit Preparation** – Catch low-hanging issues early and reduce the cost and turnaround time of formal audits.
- **Ongoing Security Monitoring** – Continuously track contract changes post-deployment to guard against new risks introduced by upgrades or dependencies.
- **Developer Education** – Leverage detailed explanations and code snippets to upskill engineers on secure-coding best practices.
- **Compliance & Reporting** – Export machine-readable SARIF results for governance dashboards and regulatory submissions.

## Conclusion

AuditAgent brings the speed of AI to smart-contract security, giving Lux builders instant feedback and continuous protection across the entire development lifecycle. Integrate it into your workflow to ship faster—confident that your contracts are battle-tested and secure.


# Nethermind (/integrations/nethermind)

---
title: Nethermind
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Nethermind offers good-quality security audits with deep Ethereum expertise and a 20% discount for Lux ecosystem projects."
logo: /images/nethermind.png
developer: Nethermind
website: https://nethermind.io/
---

## Overview

Nethermind is a blockchain development company offering good-quality security audits for projects building on Lux. With deep expertise in Ethereum and EVM-compatible chains, their team provides comprehensive security assessments that leverage their experience as both security researchers and blockchain developers. Lux ecosystem projects can benefit from a 20% discount when working with Nethermind.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **Protocol Security**: Comprehensive analysis of protocol design and implementation.
- **20% Ecosystem Discount**: Referral discount for Lux ecosystem projects.
- **Developer Perspective**: Security insights informed by active blockchain development experience.
- **EVM Expertise**: Deep understanding of EVM internals and security implications.
- **Ethereum Background**: Extensive experience with Ethereum and EVM-compatible chains.
- **Client Implementation Experience**: Unique insights from building Ethereum clients.

## Getting Started

To engage Nethermind for security audits:

1. **Initial Contact**: Reach out through their website to discuss your audit requirements.
2. **Mention Ecosystem**: Reference the Lux ecosystem for the available referral discount.
3. **Audit Process**: 
   - Scope definition and planning
   - Comprehensive code review
   - Vulnerability identification and classification
   - Detailed remediation recommendations
4. **Report Delivery**: Receive a detailed audit report with findings and security guidance.
5. **Implementation Support**: Optional assistance with addressing identified vulnerabilities.

## Use Cases

Nethermind security audits are particularly valuable for:

- **EVM-Based Projects**: Benefit from their deep EVM expertise.
- **Layer 2 Solutions**: Security assessment of layer 2 implementations.
- **Cross-Chain Applications**: Review of bridge and cross-chain mechanisms.
- **DeFi Protocols**: Thorough evaluation of financial smart contracts.
- **Lux Ecosystem Projects**: Access to quality audits with ecosystem discount.

## Conclusion

Nethermind provides good-quality security audits with particular strength in EVM expertise derived from their experience as blockchain developers. Their unique perspective as both security researchers and blockchain implementers offers valuable insights that may not be available from security-only firms. With a 20% discount available for Lux ecosystem projects, Nethermind delivers professional security services with a developer-informed approach to vulnerability assessment and remediation. 

# Nexera (/integrations/nexera)

---
title: Nexera
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: "Nexera provides flexible accreditation and decentralized identity (DID) solutions for compliant blockchain applications."
logo: /images/nexera.jpg
developer: Nexera
website: https://allianceblock.io/
documentation: https://allianceblock.io/
---

## Overview

Nexera (formerly AllianceBlock) offers comprehensive identity and compliance solutions for blockchain applications, including flexible accreditation verification and decentralized identity (DID) management. The platform enables projects to implement customizable compliance frameworks while maintaining user privacy through decentralized identity infrastructure.

## Features

- **Decentralized Identity (DID)**: Self-sovereign identity management giving users control over their credentials.
- **Flexible Accreditation**: Customizable verification frameworks for different investor types and compliance requirements.
- **Credential Management**: Reusable verification credentials that can be shared across platforms.
- **Privacy-Preserving**: Verify accreditation status without exposing sensitive personal information.
- **On-Chain Verification**: Smart contract integration for automated compliance checks.
- **Multi-Jurisdiction Support**: Adaptable to different regulatory frameworks globally.
- **Modular Architecture**: Flexible implementation options for various use cases.

## Documentation

For more information, visit the [Nexera website](https://allianceblock.io/).

## Use Cases

Nexera serves various identity and compliance needs:

- **Token Offerings**: Verify investor accreditation for compliant token sales.
- **DeFi Compliance**: Enable permissioned DeFi with flexible accreditation requirements.
- **Decentralized Identity**: Implement DID solutions for privacy-preserving verification.
- **Institutional Onboarding**: Streamline verification for institutional participants.
- **Cross-Platform Credentials**: Enable reusable identity across multiple applications.

## Conclusion

Nexera provides a flexible, privacy-preserving approach to identity verification and accreditation, offering blockchain applications on Lux customizable compliance solutions with decentralized identity infrastructure.



# Nonco (/integrations/nonco)

---
title: Nonco
category: Payments
available: ["LUExchange-Chain"]
description: Nonco is an institutional digital asset trading firm backed by VanEck that has launched an institutional-grade FX trading protocol on Lux, bringing real-world FX liquidity to stablecoin markets.
logo: /images/nonco.png
developer: Nonco
website: https://www.nonco.com/
documentation: https://www.nonco.com/protocol
---

## Overview

Nonco is a leading institutional digital asset trading firm backed by VanEck that has developed an innovative institutional-grade foreign exchange (FX) trading protocol built on Lux. The protocol aims to bring deep, real-world FX liquidity to stablecoin markets, starting with the USDMXN (US Dollar to Mexican Peso) pair and expanding to additional currency pairs over time.

By using a request-for-quote (RFQ) model, Nonco connects traditional FX liquidity providers with on-chain users, offering competitive pricing, atomic settlement, and seamless integration with banks and stablecoin issuers. This partnership cements Lux's position as the FX-chain of choice for institutions, continuing its momentum as the preferred blockchain infrastructure for regulated financial applications.

## Features

- **Institutional-Grade FX Protocol**: Professional foreign exchange trading infrastructure built on blockchain.
- **Real-World Liquidity**: Access to deep liquidity from traditional FX market makers and banks.
- **Request-for-Quote (RFQ) Model**: Competitive pricing through quote requests to multiple liquidity providers.
- **Atomic Settlement**: Instant, trustless settlement of FX trades on-chain.
- **Bank Integration**: Direct connections to banking partners for fiat settlement.
- **Stablecoin Issuer Partnerships**: Integration with major stablecoin issuers for seamless currency conversion.
- **USDMXN Focus**: Initial launch with Mexican Peso pairs, serving high-demand corridor.
- **Multi-Currency Expansion**: Roadmap to support additional fiat currency pairs.
- **Competitive Pricing**: Institutional-quality pricing competitive with traditional FX markets.
- **Regulatory Compliance**: Built with regulatory requirements and institutional standards in mind.
- **Lux Native**: Purpose-built on Lux for speed, cost-efficiency, and institutional adoption.
- **API Access**: Comprehensive APIs for programmatic trading and integration.
- **Transparent Operations**: On-chain transparency of trades and settlements.
- **VanEck Backed**: Support from leading institutional asset manager VanEck.

## Getting Started

To access Nonco's FX protocol:

1. **Institutional Onboarding**: Contact Nonco to begin institutional onboarding process.

2. **Compliance Verification**: Complete institutional KYC/AML and compliance requirements.

3. **Integration Options**: Choose how to access the protocol:
   - **Direct Protocol Access**: Integrate directly with Nonco's smart contracts
   - **API Integration**: Use Nonco's APIs for programmatic trading
   - **White-Label Solutions**: Embed FX functionality into your platform
   - **Liquidity Provider**: Become a liquidity provider on the protocol

4. **Testing**: Test FX trading in Nonco's sandbox environment on Lux testnet.

5. **Go Live**: Execute live FX trades with real liquidity on Lux mainnet.

## Request-for-Quote (RFQ) Model

Nonco's RFQ model provides institutional-quality execution:

**Quote Request**: Users or applications request quotes for specific FX pairs and amounts.

**Competitive Quotes**: Multiple liquidity providers respond with competitive pricing.

**Best Execution**: User selects best quote based on price, size, and settlement terms.

**Atomic Settlement**: Trade executes instantly on-chain with atomic settlement guaranteeing execution.

**On-Chain Record**: Complete transparency with all trades recorded on Lux blockchain.

This model ensures users receive competitive institutional pricing while maintaining the efficiency and transparency of blockchain settlement.

## Lux Integration

Nonco chose Lux as the foundation for their FX protocol for several key reasons:

**Institutional Adoption**: Lux's growing adoption by regulated financial institutions made it the natural choice.

**High Performance**: Lux's throughput and sub-second finality enable real-time FX trading.

**Low Costs**: Minimal transaction fees make frequent trading economically viable.

**Regulatory Compatibility**: Lux's architecture supports compliance and institutional requirements.

**Subnet Capability**: Potential for dedicated FX subnet with customized parameters.

**Network Effect**: Building where other institutional applications are deployed creates synergies.

This positioning cements Lux as the "FX-chain" for institutional foreign exchange.

## Use Cases

Nonco's FX protocol serves various institutional needs:

**Cross-Border Payments**: Convert between stablecoins and local currencies for international transfers.

**Remittances**: Enable efficient remittance corridors with instant FX conversion.

**Treasury Management**: Corporations managing multi-currency treasuries with stablecoins.

**Exchanges**: Cryptocurrency exchanges offering fiat on/off-ramps with competitive FX rates.

**Payment Processors**: Fintech platforms processing international payments.

**Neobanks**: Digital banks offering multi-currency accounts and FX services.

**DeFi Protocols**: DeFi applications needing access to real-world FX liquidity.

**Market Makers**: Trading firms providing liquidity across fiat and stablecoin markets.

## USDMXN Focus

Nonco's initial focus on the USDMXN pair is strategic:

**High-Demand Corridor**: US-Mexico is one of the world's largest remittance corridors.

**Underserved Market**: Traditional FX markets often have high spreads for MXN.

**Growing Stablecoin Adoption**: Strong demand for stablecoin-based solutions in Latin America.

**Regulatory Clarity**: Increasing regulatory clarity in both jurisdictions.

**Market Opportunity**: Billions in annual transaction volume between USD and MXN.

The success with USDMXN will pave the way for additional currency pairs.

## Liquidity Providers

Nonco connects multiple types of liquidity providers:

**Traditional Banks**: Banking partners providing fiat FX liquidity.

**Market Makers**: Professional trading firms quoting competitive prices.

**Stablecoin Issuers**: Direct integration with stablecoin issuers for minting/redemption.

**Institutional Traders**: Hedge funds and prop trading firms providing liquidity.

**Treasury Operations**: Corporate treasuries participating as liquidity providers.

This diverse liquidity base ensures competitive pricing and deep markets.

## Technology Infrastructure

Nonco provides comprehensive FX trading infrastructure:

- **Smart Contracts**: Audited smart contracts on Lux for trustless execution
- **RFQ Engine**: High-performance quote request and aggregation system
- **Settlement Layer**: Atomic settlement ensuring simultaneous asset exchange
- **Oracle Integration**: Price feeds for reference rates and validation
- **API Gateway**: RESTful APIs for programmatic access
- **WebSocket Feeds**: Real-time market data and quote streams
- **Admin Dashboard**: Interface for managing trades and monitoring activity
- **Compliance Tools**: Built-in tools for transaction monitoring and reporting

## Institutional Standards

Nonco meets institutional requirements:

- **Price Discovery**: Transparent, competitive price discovery through RFQ
- **Best Execution**: Users can select from multiple quotes ensuring best execution
- **Audit Trail**: Complete on-chain audit trail of all transactions
- **Reporting**: Comprehensive reporting for compliance and accounting
- **Custody Integration**: Compatible with institutional custody providers
- **Risk Management**: Tools for managing counterparty and settlement risk
- **SLAs**: Service level agreements for uptime and performance

## VanEck Partnership

VanEck's backing provides significant advantages:

**Institutional Credibility**: VanEck's reputation enhances trust with institutional clients.

**Regulatory Expertise**: Access to VanEck's regulatory knowledge and relationships.

**Network Access**: Connections to VanEck's extensive institutional network.

**Capital Support**: Financial backing for protocol development and growth.

**Strategic Guidance**: Benefit from VanEck's decades of asset management experience.

## Regulatory Approach

Nonco operates with focus on compliance:

- **Institutional KYC**: Comprehensive know-your-customer for all participants
- **Transaction Monitoring**: Real-time monitoring for suspicious activity
- **Sanctions Screening**: Screening against global sanctions lists
- **Reporting**: Regulatory reporting capabilities for relevant jurisdictions
- **Licensing**: Working with necessary licenses for FX and digital asset operations
- **Bank Partnerships**: Collaborating with regulated banking partners

## Competitive Advantages

**Real Liquidity**: Access to traditional FX market liquidity, not just crypto-native sources.

**Institutional-Grade**: Built to institutional standards from day one.

**Lux Native**: Purpose-built on Lux's institutional-focused infrastructure.

**RFQ Model**: Proven trading model from traditional finance adapted for blockchain.

**VanEck Backed**: Credibility and support from leading asset manager.

**Atomic Settlement**: Eliminates settlement risk through blockchain technology.

**Competitive Pricing**: Institutional-quality pricing rivaling traditional FX markets.

## Market Impact

Nonco's protocol advances the Lux ecosystem:

**Institutional Use Case**: Demonstrates Lux's viability for institutional FX trading.

**Liquidity Attraction**: Brings traditional financial liquidity onto Lux.

**Network Effect**: Attracts additional institutional applications to the ecosystem.

**Real-World Utility**: Enables practical, high-volume use cases beyond speculation.

**Regulatory Validation**: Shows regulators blockchain's potential for licensed financial activity.

## Roadmap

Nonco's expansion plans include:

- **Additional Currency Pairs**: Expansion beyond USDMXN to other major pairs
- **Increased Liquidity**: Onboarding additional liquidity providers
- **Enhanced Features**: Advanced trading features for institutional users
- **Geographic Expansion**: Support for additional regional corridors
- **DeFi Integration**: Deeper integration with DeFi protocols
- **Derivative Products**: Potential FX derivatives and hedging instruments

## Pricing

Nonco offers institutional pricing:

- **Competitive Spreads**: Tight bid-ask spreads competitive with traditional FX
- **Transparent Fees**: Clear fee structure for all participants
- **Volume Discounts**: Reduced fees for high-volume traders
- **Liquidity Provider Incentives**: Rewards for liquidity provision
- **Enterprise Solutions**: Custom pricing for large institutional clients

Contact Nonco for specific pricing based on trading volume and requirements.

## Conclusion

Nonco is pioneering the future of institutional FX trading by bringing real-world foreign exchange liquidity to blockchain through their protocol built on Lux. With backing from VanEck, an RFQ model proven in traditional finance, and focus on institutional-grade infrastructure, Nonco provides the bridge between traditional FX markets and the efficiency of blockchain settlement. Starting with the high-demand USDMXN corridor and expanding to additional pairs, Nonco demonstrates Lux's capability to serve as the institutional FX-chain, handling real-world financial flows with the security, transparency, and efficiency of blockchain technology. For institutions needing to convert between fiat currencies and stablecoins at scale, Nonco's protocol on Lux provides the professional-grade solution that meets both business and regulatory requirements.



# Nuggets (/integrations/nuggets)

---
title: Nuggets
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: "Nuggets offers privacy-focused KYC verification with self-sovereign identity management for blockchain applications."
logo: /images/nuggets.png
developer: Nuggets
website: https://nuggets.life/
documentation: https://nuggets.life/
---

## Overview

Nuggets is a self-sovereign identity and payment platform that provides privacy-focused KYC verification services. The platform enables users to verify their identity once and securely store their personal data, which can then be shared with verified businesses without repeated verification processes.

## Features

- **Self-Sovereign Identity**: Users maintain full control over their personal data and credentials.
- **Privacy-Preserving**: Personal data is encrypted and stored securely on the user's device.
- **Biometric Authentication**: Secure access using biometric verification.
- **Reusable Credentials**: Verify once and share credentials with multiple platforms.
- **Zero-Knowledge Proofs**: Share verification status without revealing underlying personal data.
- **Payment Integration**: Combines identity verification with secure payment capabilities.
- **GDPR Compliant**: Built with European data protection regulations in mind.

## Documentation

For more information, visit the [Nuggets website](https://nuggets.life/).

## Use Cases

Nuggets serves various identity and compliance needs:

- **Privacy-Preserving KYC**: Verify user identity while maintaining maximum privacy.
- **Reusable Identity**: Enable users to access multiple platforms with a single verification.
- **Compliance**: Meet regulatory requirements without compromising user privacy.
- **Data Protection**: Ensure user data remains under user control.

## Conclusion

Nuggets provides a privacy-first approach to identity verification, offering blockchain applications on Lux a way to implement KYC compliance while respecting user privacy and data sovereignty.



# Octane (/integrations/octane)

---
title: Octane
category: Security Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: Octane's AI-powered security platform provides continuous vulnerability detection and deep codebase analysis integrated directly into developer workflows.
logo: /images/octane.jpg
developer: Octane
website: https://octane.security/
documentation: https://docs.octane.security/introduction
---

## Overview

Octane is an AI-powered continuous security platform for smart contracts. It integrates directly into developer workflows to analyze code, simulate attack paths, and detect deep logic vulnerabilities before deployment. Designed for high-velocity teams, Octane provides ongoing security coverage without disrupting existing development processes.

## Features

- **AI Code Analysis**: Automatically detects high-impact vulnerabilities in code.
- **Cross-Contract Expertise**: Analyzes interactions across multi-contract systems.
- **Broad Coverage**: 50+ vulnerability classes, including reentrancy, MEV, and oracle risks.
- **Exploit Scenarios**: Describes attacker–victim behavior and how the issue is exploitable.
- **CI/CD Integration**: Automated analysis on every pull request via native GitHub App.
- **Lux-Tuned Models**: Detection tuned using Lux-specific documentation.
- **Octane Security Program**: Eligible teams may receive Octane security credits.

## Getting Started

1. Request access or schedule a demo [here](https://www.octane.security/schedule-demo)
2. Connect your repo with our [quickstart guide](https://www.octane.security/post/how-to-get-the-most-out-of-octane)
3. Run an initial scan to generate findings in minutes
4. Enable CI/CD integration to secure all future PRs automatically
5. Eligible Lux builders may receive Octane credits during onboarding

## Use Cases

- **Continuous Security**: Ongoing analysis to maintain a secure codebase.
- **CI/CD Pipeline Protection**: Automatically review every PR to catch issues in real time.
- **Pre-Deployment Checks**: Run deep analysis before testnet or mainnet releases.
- **Advanced Protocol Analysis**: Suitable for DeFi, stablecoins, gaming, and teams building high-value systems that require institutional-grade security.

## Conclusion

Octane delivers continuous, AI-powered smart contract security for Lux builders. By embedding automated analysis directly into development workflows, teams can identify issues earlier, reduce security risk, and ship safer applications with confidence. Request access [here](https://www.octane.security/schedule-demo) to find out if you qualify for Octane Security Program credits.


# OKX OS (/integrations/okxos)

---
title: OKX OS
category: Wallets and Account Abstraction
available: ["LUExchange-Chain"]
description: A comprehensive onchain infrastructure suite for building and scaling applications.
logo: /images/okx.png
developer: OKX
website: https://www.okx.com/web3/build
documentation: https://www.okx.com/web3/build/docs/waas/okx-waas-what-is-waas
---

## Overview

OKX OS is the most comprehensive onchain infrastructure suite that provides developers with a full set of tools, SDKs, and APIs to build and scale applications across over 100 chains without limitations. It leverages the same technology that powers the OKX Wallet, serving millions of users and processing more than 400 million daily API calls.

## Features

- **One-stop solution**: The most extensive suite of tools and APIs for building complex onchain experiences across any chain, from wallets to games, exchanges, and collections.
- **Multi-chain support and liquidity aggregation**: Access to over 100 chains and aggregate liquidity across multiple networks, DEXs, and major marketplaces for maximum flexibility and faster market entry.
- **Bitcoin-friendly**: Unique tools for Inscriptions, Ordinals, Runes, Fractal Bitcoin, and other emerging Bitcoin-based innovations.
- **Industry-leading security**: Leverages OKX's robust security measures and audited processes, enabling developers to build with confidence.
- **Proven scalability**: Designed for fast-growth applications, as evidenced by OKX's ecosystem serving millions of users and handling over 400 million daily API calls.

## Getting Started

Developers can start using OKX OS for free today by visiting the [OKX Build Portal](https://www.okx.com/web3/build). The platform provides comprehensive tools, SDKs, and APIs to help you quickly build and scale your applications across multiple chains.

## Documentation

For detailed documentation and guides, please visit the [OKX OS Documentation](https://www.okx.com/web3/build).

## Use Cases

- Building multi-chain wallets with seamless transaction management.
- Integrating cross-chain swaps and liquidity aggregation into decentralized applications.
- Creating NFT marketplaces with real-time data and marketplace integrations.
- Developing blockchain games with in-game asset management across 100+ chains.
- Accessing comprehensive onchain data APIs for actionable insights.

### Building an On-Chain Data Dashboard for Lux LUExchange-Chain

This guide walks you through setting up a dashboard to track wallet assets and transactions on the Lux LUExchange-Chain. You'll use OKX OS's Wallet API to fetch and display this data.

#### Prerequisites
- [Node.js](https://nodejs.org/) installed on your system
- Basic understanding of JavaScript and async/await
- An OKX Developer account

#### Setting Up Your Development Environment

1. **Log in to the Developer Portal**: Sign up for an account on the [OKX Developer Portal](https://www.okx.com/web3/build/dev-portal).

2. **Create a New Project**: Click on the `Create new project` button and fill in the required details. Once the project is created, you will receive a `Project ID`. Keep it for future reference.

3. **Generate API Keys**: Once your project is created, click the `Manage` and then `Create API key` buttons to create a new API key. Fill in the required details and click `Create`. You will receive an `API Key` and `API Secret`. Keep your `API Key`, `API Secret`, and `Passphrase` for future use.

> **Note**: Keep your Project ID, API Key, Secret, and Passphrase secure by storing them in environment variables or a secure storage solution. It is recommended to never share these credentials publicly or commit them to your codebase.

4. **Initialize a New Project**:
Run the following commands to create a new directory and initialize a Node.js project with default settings and required dependencies:

```bash
mkdir lux-dashboard
cd lux-dashboard
npm init -y
npm install crypto-js
```

Create three script files:
```bash
touch createAccount.js getAssets.js getTx.js
```

## Create Wallet Account

You'll start by creating an account to track your Lux addresses with a simple Node.js script that interacts with the OKX Wallet API.

In the `createAccount.js` file:
   
```javascript
const CryptoJS = require("crypto-js");

const createWallet = async () => {
    // Generate timestamp in ISO format
    const timestamp = new Date().toISOString();
    const method = "POST";
    const path = "/api/v5/wallet/account/create-wallet-account";

    // Prepare the body first as we need it for signature
    const body = {
        addresses: [
            {
                chainIndex: "43114",
                address: "0x2eFB50e952580f4ff32D8d2122853432bbF2E204",
            },
            // You can add more addresses and chain indexes 
            // {
            //     chainIndex: "1",
            //     address: "0x2eFB50e952580f4ff32D8d2122853432bbF2E204",
            // },
            // {
            //     chainIndex: "43114",
            //     address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            // },
        ],
    };

    // Generate signature
    // timestamp + method + path + body
    const signString = timestamp + method + path + JSON.stringify(body);
    const signature = CryptoJS.enc.Base64.stringify(
        CryptoJS.HmacSHA256(signString, "YOUR API SECRET KEY"),
    );

    const response = await fetch(
        "https://www.okx.com/api/v5/wallet/account/create-wallet-account",
        {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "OK-ACCESS-PROJECT": "YOUR PROJECT ID",
                "OK-ACCESS-KEY": "YOUR API KEY",
                "OK-ACCESS-SIGN": signature,
                "OK-ACCESS-PASSPHRASE": "YOUR API PASSPHRASE",
                "OK-ACCESS-TIMESTAMP": timestamp,
            },
            body: JSON.stringify(body),
        },
    );

    const data = await response.json();
    return data;
};

// Example usage:
createWallet()
    .then((response) => console.log("Success:", response))
    .catch((error) => console.error("Error:", error));
```

Before running the script, replace these placeholder values with your actual credentials:
```javascript
"YOUR API SECRET KEY" → Your API Secret
"YOUR PROJECT ID" → Your Project ID
"YOUR API KEY" → Your API Key
"YOUR API PASSPHRASE" → Your Passphrase
```

Run your script:
```bash
node createAccount.js
```

You should see a success message with the response data if the account is created successfully.

For example,
```bash
Success: { code: '0', message: 'success', data: { accountId : 'Y7489xxxx-xxxx-xxxx-xxxx-xxxxxxaa652c' } }
```

## Check Wallet Assets

Now that we have an account, you can fetch the token balances. This script will show you all tokens held by your tracked addresses.

In your `getAssets.js` file:

1. Copy this code to `getAssets.js`:

```javascript
const CryptoJS = require("crypto-js");

    const getRequestUrl = (baseUrl, path, params = null) => {
        const url = new URL(baseUrl + path);
        if (params) {
            Object.keys(params).forEach((key) =>
                url.searchParams.append(key, params[key]),
            );
        }
        return url.toString();
    };

    const apiBaseUrl = "https://www.okx.com";
    const getAssetsParams = {
        accountId: "ACCOUNT ID FROM PREVIOUS STEP", // Replace with your accountId
    };

    const timestamp = new Date().toISOString();
    const method = "GET";
    const path = "/api/v5/wallet/asset/wallet-all-token-balances";
    const queryString = `?accountId=${getAssetsParams.accountId}`;

    // Generate signature
    const signString = timestamp + method + path + queryString;
    const signature = CryptoJS.enc.Base64.stringify(
        CryptoJS.HmacSHA256(signString, "YOUR API SECRET KEY"),
    );

    const headersParams = {
        "Content-Type": "application/json",
        "OK-ACCESS-PROJECT": "YOUR PROJECT ID",
        "OK-ACCESS-KEY": "YOUR API KEY",
        "OK-ACCESS-SIGN": signature,
        "OK-ACCESS-PASSPHRASE": "YOUR API PASSPHRASE",
        "OK-ACCESS-TIMESTAMP": timestamp,
    };

    const getAssetsData = async () => {
        const apiRequestUrl = getRequestUrl(apiBaseUrl, path, getAssetsParams);

        const response = await fetch(apiRequestUrl, {
            method: "GET",
            headers: headersParams,
        });

        return response.json();
    };

    // Use it
    getAssetsData()
        .then(({ data }) => {
            console.log("\n=== Wallet Assets ===\n");

            data.forEach((wallet) => {
                // Convert timestamp to readable date
                const date = new Date(parseInt(wallet.timeStamp));
                console.log(`Last Updated: ${date.toLocaleString()}\n`);

                console.log("Token Assets:");
                wallet.tokenAssets.forEach((token) => {
                    console.log(`
    Token: ${token.symbol}
    Chain: ${token.chainIndex}
    Balance: ${token.balance}
    -----------------------------`);
                });
            });
        })
        .catch((error) => console.error("Error:", error));
```

Make sure to:
- Update the accountId with the one you received in Step 1
- Replace the API credentials with yours

Run the asset checker:
```bash
node getAssets.js
```

You should see the assets of the wallet account if the request is successful.

For example,
```bash
=== Wallet Assets ===

Last Updated: 10/24/2024, 7:23:20 PM

Token Assets:

Token: LUX
Chain: 43114
Balance: 882338.9729422927
-----------------------------

Token: Sword
Chain: 43114
Balance: 100000
-----------------------------

Token: ERGC
Chain: 43114
Balance: 100000
-----------------------------


Token: MILO
Chain: 43114
Balance: 500000
-----------------------------
```


## View Transaction Details

Finally, you can set up transaction viewing. This script provides detailed information about any transaction on the Lux LUExchange-Chain.

In your `getTx.js` file:


```javascript
const CryptoJS = require("crypto-js");

const getRequestUrl = (baseUrl, path, params = null) => {
    const url = new URL(baseUrl + path);
    if (params) {
        Object.keys(params).forEach((key) =>
            url.searchParams.append(key, params[key]),
        );
    }
    return url.toString();
};

const apiBaseUrl = "https://www.okx.com";
const params = {
    txHash: '0xaf54d1cb2c21bed094095bc503ec76128f80c815db8631fd74c6e49781b94bd1', // Changed from txhash to txHash
    chainIndex: '43114'
};

const timestamp = new Date().toISOString();
const method = "GET";
const path = '/api/v5/wallet/post-transaction/transaction-detail-by-txhash';
const queryString = `?txHash=${params.txHash}&chainIndex=${params.chainIndex}`; // Changed from txhash to txHash

const signString = timestamp + method + path + queryString;
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(signString, "YOUR API SECRET"),
);

const headersParams = {
    "Content-Type": "application/json",
    "OK-ACCESS-PROJECT": "YOUR PROJECT ID",
    "OK-ACCESS-KEY": "YOUR API KEY",
    "OK-ACCESS-SIGN": signature,
    "OK-ACCESS-PASSPHRASE": "YOUR API PASSPHRASE",
    "OK-ACCESS-TIMESTAMP": timestamp,
};

const getTransactionDetailData = async () => {
    const apiRequestUrl = getRequestUrl(apiBaseUrl, path, params);

    const response = await fetch(apiRequestUrl, {
        method: "GET",
        headers: headersParams,
    });

    return response.json();
};

const formatDate = (timestamp) => {
    return new Date(parseInt(timestamp)).toLocaleString();
};

const formatGas = (gas) => {
    return parseFloat(gas).toLocaleString();
};

getTransactionDetailData()
    .then((response) => {
        console.log('\n=== Transaction Details ===\n');

        if (response.code === "0" && response.data && response.data.length > 0) {
            const tx = response.data[0];

            // Transaction Basic Info
            console.log('📝 Basic Information');
            console.log('------------------');
            console.log(`Hash: ${tx.txhash}`);
            console.log(`Status: ${tx.txStatus.toUpperCase()}`);
            console.log(`Block: ${formatGas(tx.height)}`);
            console.log(`Time: ${formatDate(tx.txTime)}`);
            console.log(`Method ID: ${tx.methodId}`);
            console.log(`Chain: ${tx.chainIndex} (${tx.symbol})`);

            // Gas Info
            console.log('\n⛽ Gas Information');
            console.log('----------------');
            console.log(`Gas Limit: ${formatGas(tx.gasLimit)}`);
            console.log(`Gas Used: ${formatGas(tx.gasUsed)}`);
            console.log(`Gas Price: ${formatGas(tx.gasPrice)} Wei`);
            console.log(`Nonce: ${tx.nonce}`);

            // From Address
            console.log('\n📤 From Address');
            console.log('-------------');
            tx.fromDetails.forEach(from => {
                console.log(`Address: ${from.address}`);
                console.log(`Type: ${from.isContract ? 'Contract' : 'Wallet'}`);
            });

            // To Address
            console.log('\n📥 To Address');
            console.log('-----------');
            tx.toDetails.forEach(to => {
                console.log(`Address: ${to.address}`);
                console.log(`Type: ${to.isContract ? 'Contract' : 'Wallet'}`);
            });

            // Token Transfers
            if (tx.tokenTransferDetails && tx.tokenTransferDetails.length > 0) {
                console.log('\n🔄 Token Transfers');
                console.log('---------------');
                tx.tokenTransferDetails.forEach((transfer, index) => {
                    console.log(`\nTransfer #${index + 1}:`);
                    console.log(`Token: ${transfer.symbol}`);
                    console.log(`Amount: ${transfer.amount}`);
                    console.log(`From: ${transfer.from} ${transfer.isFromContract ? '(Contract)' : '(Wallet)'}`);
                    console.log(`To: ${transfer.to} ${transfer.isToContract ? '(Contract)' : '(Wallet)'}`);
                    console.log(`Contract: ${transfer.tokenContractAddress}`);
                });
            }

            // Internal Transactions (if any)
            if (tx.internalTransactionDetails && tx.internalTransactionDetails.length > 0) {
                console.log('\n💱 Internal Transactions');
                console.log('--------------------');
                tx.internalTransactionDetails.forEach((internal, index) => {
                    console.log(`\nInternal Transfer #${index + 1}:`);
                    console.log(`From: ${internal.from}`);
                    console.log(`To: ${internal.to}`);
                    console.log(`Amount: ${internal.amount} ${tx.symbol}`);
                    console.log(`Status: ${internal.state}`);
                });
            }

        } else {
            console.log('Status:', response.code);
            console.log('Message:', response.msg);
            console.log('Data:', response.data);
        }
    })
    .catch(error => console.error('Error:', error));
```

Update the script with:
- Your API credentials
- Any transaction hash you want to investigate

Check a transaction:
```bash
node getTx.js
```

You'll see a detailed breakdown including:
- Transaction basics
- Gas info
- Addresses involved
- Token transfers
- Internal transactions

## Conclusion

The Wallet API is one of 4 strong pillars within the OKX OS infrastructure, complemented by the [DEX API] for decentralized trading capabilities, the [Marketplace API] for NFT functionalities, and the [Explorer API] for comprehensive blockchain data access and analysis. Together, these APIs form a complete toolkit that enables developers to build sophisticated Web3 applications with enterprise-grade reliability and performance.

By leveraging OKX OS's powerful infrastructure suite, developers can build and scale innovative onchain applications quickly and efficiently. With its extensive tools, multi-chain support, and proven scalability, OKX OS continues to drive the future of Web3 development, making it easier than ever to create seamless experiences across the blockchain ecosystem.

[DEX API]: https://www.okx.com/web3/build/docs/waas/dex-introduction
[Marketplace API]: https://www.okx.com/web3/build/docs/waas/marketplace-introduction
[Explorer API]: https://www.oklink.com/docs/en/#introduction

# Olympix (/integrations/olympix)

---
title: "Olympix"
category: ["Security Tooling"]
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Olympix is an institutional-grade proactive security suite for smart contract developers, providing automated vulnerability detection and testing integrated into developer workflows."
logo: /images/olympix.png
developer: "Olympix.ai"
website: https://olympix.ai
documentation: https://olympix.github.io
---

## Overview


[Olympix](https://www.olympix.ai) is the only institutional-grade proactive security suite for Web3, purpose-built to identify and prevent vulnerabilities before audits or deployment. Its proprietary architecture (including a custom compiler, intermediate representation (IR), and symbolic execution engine), not LLM-wrappers, powers tools like static analysis, unit test generation, mutation testing, and automated POC generation.


By integrating directly into developer environments (VS Code, GitHub CI/CD), Olympix helps teams catch vulnerabilities early, strengthen audit readiness, and reduce the time and cost of achieving secure deployment on Lux and other EVM-compatible chains.

## Features

- Static Analyzer: Detects critical vulnerabilities early in development using advanced symbolic execution and proprietary detectors.

- Unit Test Generation: Automatically generates test suites to improve coverage and resilience of smart contracts.
- Mutation Testing: Measures the robustness of unit tests by simulating bad commits and highlighting which edge cases go undetected.
- Internal Audit Agent: Generates and audit-style report complete with POCs to prove the exploitability of findings.
- Developer Integration: Embedded within IDEs and CI/CD for continuous, proactive security.
- Audit Readiness: Hardens test suites (out of scope of typical audit), reduces audit findings by up to 60%, and shortens remediation cycles.
- Institutional-Grade Precision: 300% better benchmarking performance versus open-source alternatives.


## Getting Started 


To start using Olympix:
1. Visit [Olympix](https://olympix.ai) to request access or schedule a demo.
2. Install the Olympix VS Code or GitHub CI/CD integration.
3. Run static analysis, unit test generation, mutation testing, and internal audit agent on your Lux-based smart contracts. 
4. Review findings and fix issues before audit and before deployment.


## Use Cases

Olympix is ideal for:
1. DeFi Protocols: Secure high-value contracts and mitigate risk before audits.
2. Bridges and Cross-Chain Projects: Identify logic and invariant vulnerabilities across EVM environments.
3. Enterprises and Financial Institutions: Embed compliance-grade security early in tokenization and on-chain deployments.
4. Developers on Lux: Leverage proactive tooling to minimize risk and accelerate secure releases.

## Conclusion

Olympix brings enterprise-grade, proactive security to Lux’s developer ecosystem. By identifying vulnerabilities early and automating testing, it helps projects reduce exploit risk, save audit costs, and build trust with users. Olympix is designed for builders who want to secure smart contracts before audits, enabling safer, faster, and more confident on-chain development.

## Contact us
For more information, please visit [Olympix](https://olympix.ai) and [contact](https://www.olympix.ai/get-started-enterprise) us.


# Omniscia (/integrations/omniscia)

---
title: Omniscia
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Omniscia provides good-quality security audits with efficient processes and competitive rates for projects on Lux."
logo: /images/omniscia.jpeg
developer: Omniscia
website: https://omniscia.io/
---

## Overview

Omniscia is a security audit provider offering good-quality assessments for blockchain projects building on Lux. Known for their efficient processes and competitive rates, Omniscia delivers thorough security reviews while maintaining a focus on accessibility and practical value. Their team provides comprehensive audits with relatively low lead times, making them suitable for projects with time-sensitive deployment schedules.

## Features

- **Smart Contract Audits**: Comprehensive code reviews and vulnerability assessment.
- **Efficient Process**: Streamlined audit procedures with relatively low lead times.
- **Competitive Pricing**: Accessible rates with potential referral discounts.
- **20% Referral Discount**: Available referral discount for Lux ecosystem projects.
- **Protocol Security**: Analysis of protocol design and implementation.
- **Practical Remediation**: Actionable guidance for addressing security issues.
- **Verification Services**: Validation of security fixes after implementation.

## Getting Started

To engage Omniscia for security audits:

1. **Initial Contact**: Reach out through their website to discuss your security needs.
2. **Mention Referral**: Reference the Lux ecosystem for potential referral discounts.
3. **Audit Process**: 
   - Scope definition and planning
   - Comprehensive code review
   - Vulnerability identification and classification
   - Documentation of findings
4. **Report Delivery**: Receive a detailed audit report with security recommendations.
5. **Optional Follow-up**: Verification of implemented security improvements.

## Use Cases

Omniscia security audits are particularly suitable for:

- **Time-Sensitive Projects**: Benefit from relatively efficient audit processes.
- **DeFi Applications**: Security assessment of financial smart contracts.
- **NFT Platforms**: Audit of NFT-related contract implementations.
- **Budget-Conscious Projects**: Access to good-quality audits with competitive pricing.
- **Lux Ecosystem Projects**: Potential referral discounts available.

## Conclusion

Omniscia provides good-quality security audits with a focus on efficiency and accessibility. Their competitive rates and 20% referral discount for Lux ecosystem projects make professional security services available to a wider range of projects. While their audit process is relatively efficient, Omniscia maintains good technical standards in their security assessments, helping projects identify and address vulnerabilities before deployment. 

# OnFinality (/integrations/onfinality)

---
title: OnFinality
category: RPC Endpoints
available: ["LUExchange-Chain","Platform-Chain","Exchange-Chain"]
description: Blockchain Infrastructure Made Smarter. OnFinality empowers web3 developers with easy-to-use, reliable, and scalable blockchain infrastructure.
logo: /images/onfinality.png
developer: OnFinality
website: https://onfinality.io
---

## Overview

OnFinality empowers web3 developers with easy-to-use, reliable, and scalable blockchain infrastructure. OnFinality supports an enormous range of networks across a broad suite of blockchain tooling including RPC Nodes, Dedicated Nodes, Validators, Data Indexers, and AI Agents - making OnFinality your complete blockchain infrastructure platform

## Features

- **Generous Free Tier**: Try for free with our generous [free plan](https://onfinality.io/en/pricing)
- **Lux Native**: Complete set of Lux endpoints including all chains, web sockets, and ETH + LUX
- **Lightning Fast**: Our Lux RPC endpoints are served by a global fleet of nodes, ensuring the lowest possible latency for time sensitive tasks and a snappy user experience
- **Enterprise Nodes**: Dedicated Lux nodes and [load balanced clusters](https://blog.onfinality.io/onfinality-enterprise-nodes-series-blockchain-load-balancer/) for the most demanding enterprise needs like bridges and exchanges.
- **Data Indexers**: Deploy Subgraph and SubQuery data indexers on [OnFinality Indexing](https://indexing.onfinality.io/login)
- **Endpoint Security**: Secure your private endpoint to only accept requests from specific origins or IP addresses.
- **Analytics and Insights**: Gain insights into how your application is performing and where your users are.

## Getting Started

To start using OnFinality:

1. **Sign Up**: Create an account with [OnFinality](https://app.onfinality.io/signup)
2. **Create your API App**: After signing in, create an API App and select the Lux network
4. **Copy your Private Lux Endpoint**: Copy your C-chain, Platform-Chain, or Exchange-Chain endpoints. Web Socket is also supported.
5. **Monitor and Optimize**: Utilize OnFinality's Network Insights to track your app's performance and make changes - with analytics down to the method.

## Documentation

[OnFinality Documentation](https://documentation.onfinality.io/support/api-service)

## Use Cases

- **Bridges** requiring high availability connections between Lux and other blockchain networks.
- **Explorers and Scanners** who need full archive access with high throughput for historical backfills.
- **Decentralized Applications (dApps)** serving global Lux users 24/7
- **Exchanges and Custodial Services** who know that downtime and delays cost their customers

## Conclusion

OnFinality is the right choice for teams of all sizes who need a complete suite of Lux infrastructure and exceptional, personalised support.

Talk to us now at support@onfinality.io, we'd love to hear from you!

# Openfort (/integrations/openfort)

---
title: Openfort
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Create secure embedded wallets with seamless authentication flows and gas sponsorship capabilities."
logo: /images/openfort.png
developer: Openfort
website: https://openfort.io
documentation: https://www.openfort.io/docs
---

## Overview
[Openfort](https://openfort.io) is an open-source alternative to wallet infrastructure solutions. The core offerings—Openfort Kit, Invisible Wallet, and Cross-app Wallet - enable rapid integration of wallet functionality, intuitive onboarding, and flexible user journeys for any application or ecosystem.

### [Openfort Kit](https://www.openfort.io/docs/products/kit/react/quickstart)

Openfort Kit is a developer toolkit that streamlines the integration of wallet authentication and connectivity into any web application. It provides:

- **Plug-and-play UI Components**: Prebuilt, customizable authentication and wallet connection flows that can be deployed in minutes, not weeks, with support for major authentication providers and wallet connector
- **Developer Experience**: TypeScript-ready, ecosystem-standard libraries (wagmi, viem), and easy integration with frameworks like React, Next.js, and Create React App.
- **Full Customization**: Predesigned themes or the ability to fully tailor the UI to match your brand.

### [Invisible Wallet](https://www.openfort.io/docs/products/embedded-wallet/javascript)

Invisible Wallet enables applications to onboard users without requiring them to interact directly with traditional wallet interfaces. Features include:

- **Embedded Non-custodial Signer**: Secure, self-custodied wallet creation and signing for users, with no need for browser extensions or external apps.
- **Fundign Support**: Users can onramp their newly created wallets with traditional methods or depositing crypto. 
- **Key Export**: Users can always export private keys, allowing them to take the wallet with them.

### [Cross-app Wallet](https://www.openfort.io/docs/products/cross-app-wallet/setup)

The Cross-app Wallet empowers ecosystems and platforms to offer branded, interoperable wallets that work across multiple apps and services. Key capabilities:

- **Ecosystem SDK**: Build your own wallet SDK that can be integrated across your suite of apps, ensuring users have a consistent identity and asset management experience everywhere.
- **No App or Extension Required**: Users can create and use wallets instantly via iFrames or embedded flows, compatible with any EVM chain.
- **Modern Standards**: Supports the latest Ethereum standards (EIP-1193, 6963, 7702, 4337, and more) for broad compatibility and future-proofing.

## Getting Started

### 1. Installation

```bash
# Install dependencies
npm install @openfort/openfort-js @openfort/openfort-node
npm install ethers viem
```

### 2. Configuration

```typescript
// Initialize Openfort with client and server configurations
// Client side
const openfortClient = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

// Server side
const openfortServer = new Openfort("YOUR_SECRET_KEY");
```

### 3. Basic Implementation

```typescript
// Authentication
const authResponse = await openfort.logInWithEmailPassword({
  email: "user@example.com",
  password: "password123"
});

// Initialize Provider
const provider = await openfort.getProvider();
await provider.request({ 
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: `0x${luxChain.id.toString(16)}` }]
});

// Create a gas sponsorship policy (server-side)
const policy = await openfortServer.policies.create({
  chainId: 43114, // Lux LUExchange-Chain
  name: "Gas Sponsorship Policy",
  strategy: {
    sponsorSchema: "pay_for_user"
  }
});

// Create transaction intent with sponsorship (server-side)
const transactionIntent = await openfortServer.transactionIntents.create({
  player: "PLAYER_ID",
  chainId: 43114,
  optimistic: true,
  policy: policy.id,
  interactions: [{
    contract: "CONTRACT_ADDRESS",
    functionName: "transfer",
    functionArgs: [recipientAddress, amount]
  }]
});

// Sign and send the sponsored transaction (client-side)
const response = await openfortClient.sendSignatureTransactionIntentRequest(
  transactionIntent.id,
  transactionIntent.nextAction.payload.userOperationHash
);
```

## Documentation
For detailed implementation guides and API references, visit [Openfort Documentation](https://www.openfort.io/docs)


# OpenTrade (/integrations/opentrade)

---
title: OpenTrade
category: Tokenization Platforms
available: ["LUExchange-Chain"]
description: OpenTrade provides institutional-grade, asset-backed yield products for the stablecoin economy, offering exchanges and neobanks access to tokenized real-world assets like money market funds.
logo: /images/opentrade.webp
developer: OpenTrade
website: https://www.opentrade.io/
documentation: https://www.opentrade.io/
---

## Overview

OpenTrade was spun out of Circle to build institutional-grade, asset-backed yield products specifically designed for the stablecoin economy. Backed by Circle and a16z Crypto, OpenTrade provides cryptocurrency exchanges, neobanks, and fintech platforms with seamless access to yield-generating opportunities from high-quality real-world assets such as money market funds, U.S. Treasuries, and other short-duration fixed income products.

OpenTrade's full-service platform includes bank-grade legal structuring, off-chain asset management, and on-chain tokenization infrastructure, making it easy for platforms to integrate yield offerings into both front-end user experiences and back-end treasury operations. By bridging traditional finance with blockchain technology, OpenTrade enables platforms to offer their users competitive yields while maintaining the security, compliance, and liquidity characteristics essential for institutional adoption.

## Features

- **Asset-Backed Yield Products**: Tokenized exposure to institutional-grade real-world assets generating stable returns.
- **Money Market Funds**: Access to high-quality money market instruments with daily liquidity.
- **U.S. Treasury Exposure**: Tokenized products backed by U.S. government securities.
- **Institutional-Grade Assets**: All underlying assets meet institutional quality and compliance standards.
- **Full-Service Platform**: End-to-end solution from legal structuring to asset management to tokenization.
- **Bank-Grade Legal Structure**: Compliant securitization and fund structures developed with top-tier legal advisors.
- **Off-Chain Asset Management**: Professional management of underlying real-world assets by regulated managers.
- **On-Chain Tokenization**: Blockchain-native tokens representing ownership in underlying yield-generating assets.
- **Easy Integration**: Simple APIs for exchanges and platforms to offer yield products to end users.
- **Front-End and Back-End Use**: Support both customer-facing yield products and treasury management.
- **Daily Liquidity**: Products designed for redemption flexibility matching crypto market expectations.
- **Transparent Reporting**: Regular reporting on underlying asset composition and performance.
- **Stablecoin Native**: Purpose-built for platforms operating in the stablecoin ecosystem.
- **Regulatory Compliance**: Fully compliant structures meeting securities and banking regulations.

## Getting Started

To integrate OpenTrade into your platform:

1. **Contact OpenTrade**: Reach out to OpenTrade's partnerships team to discuss your platform's needs.

2. **Define Use Case**: Determine whether you need:
   - Customer-facing yield products for end users
   - Treasury management solutions for corporate funds
   - Both retail and treasury applications

3. **Platform Assessment**: Work with OpenTrade to assess integration requirements:
   - User base and expected demand
   - Regulatory considerations for your jurisdiction
   - Technical integration approach
   - Front-end vs back-end implementation

4. **Legal and Compliance Setup**: OpenTrade handles legal structuring:
   - Establish compliant fund or securitization structure
   - Navigate securities regulations
   - Set up custody and administration arrangements

5. **Technical Integration**: Implement OpenTrade's platform:
   - Integrate APIs for subscription and redemption
   - Connect to on-chain token infrastructure
   - Implement necessary compliance checks
   - Test in sandbox environment

6. **Launch Yield Products**: Go live with OpenTrade-powered yield offerings:
   - Enable users to earn yield on idle stablecoins
   - Use treasury products to generate returns on corporate holdings
   - Provide transparent reporting to users

## Lux Support

OpenTrade's tokenization infrastructure is designed to support multiple blockchain networks. As an EVM-compatible platform, Lux LUExchange-Chain can be leveraged for deploying OpenTrade's yield-generating tokenized products, enabling platforms on Lux to offer institutional-grade yield to their users with the efficiency and low costs of the Lux network.

## Product Offerings

OpenTrade provides several types of asset-backed yield products:

**Money Market Fund Tokens**: Tokenized exposure to institutional money market funds investing in high-quality, short-term debt instruments.

**Treasury Tokens**: Digital assets backed by U.S. Treasury bills and bonds, providing government-backed yield.

**Short-Duration Fixed Income**: Tokenized access to investment-grade corporate debt and other short-duration instruments.

**Cash Management Products**: Yield solutions designed for institutional cash management with daily liquidity.

All products are structured with institutional-grade underlying assets managed by regulated asset managers.

## Use Cases

OpenTrade serves various platform types and use cases:

**Cryptocurrency Exchanges**: Offer yield products to exchange users who want to earn returns on idle stablecoin balances without leaving the platform.

**Neobanks**: Provide competitive interest rates to customers through asset-backed tokenized products.

**Fintech Platforms**: Integrate yield-generating features into fintech apps serving retail or business customers.

**Treasury Management**: Enable companies to generate returns on corporate stablecoin treasuries through institutional-grade products.

**DeFi Protocols**: Bridge DeFi platforms to real-world asset yields through compliant tokenized products.

**Payment Platforms**: Offer yield on payment platform balances, enhancing user value proposition.

**Custodians**: Provide custody clients with access to yield on their held assets.

## Platform Benefits

**Turnkey Solution**: OpenTrade handles legal structuring, asset management, and compliance—platforms just integrate.

**Institutional Quality**: All underlying assets meet institutional standards for credit quality and liquidity.

**Regulatory Compliance**: Bank-grade legal structures ensure compliance with securities and financial regulations.

**Flexible Integration**: Support for both customer-facing and treasury management use cases.

**Stable Yields**: Generate predictable returns from high-quality fixed income assets.

**Daily Liquidity**: Redemption structures designed for crypto market expectations.

**Transparent Operations**: Regular reporting and disclosure of underlying assets.

**Proven Backing**: Supported by Circle and a16z Crypto with institutional credibility.

## Legal and Compliance

OpenTrade maintains comprehensive compliance:

- **Securities Compliance**: Registered offerings or appropriate exemptions for tokenized products
- **Banking Regulations**: Structures that comply with banking and financial services rules
- **Asset Management**: Underlying assets managed by regulated investment managers
- **Custody**: Institutional-grade custody arrangements for underlying assets
- **Reporting**: Regular financial reporting and audits
- **KYC/AML**: Integrated compliance processes for investor verification
- **Multi-Jurisdictional**: Structures adaptable to different regulatory environments

## Technology Infrastructure

OpenTrade provides comprehensive infrastructure:

- **Subscription/Redemption APIs**: Simple integration for platforms to offer yield products
- **On-Chain Tokens**: ERC-20 compatible tokens representing ownership in underlying assets
- **Smart Contracts**: Audited smart contracts for token issuance and lifecycle management
- **Off-Chain Asset Bridge**: Secure connection between blockchain tokens and traditional assets
- **Reporting Dashboard**: Real-time portfolio composition and performance data
- **Compliance Engine**: Automated compliance checks and regulatory requirements
- **Multi-Chain Support**: Capability to deploy across multiple blockchain networks

## Asset Management

OpenTrade partners with top-tier asset managers:

- **Institutional Managers**: Regulated asset management firms with proven track records
- **Quality Standards**: Strict criteria for underlying asset credit quality
- **Diversification**: Portfolio construction across multiple high-quality issuers
- **Liquidity Management**: Daily management to support redemptions
- **Risk Management**: Conservative approach prioritizing capital preservation
- **Transparent Reporting**: Regular disclosure of holdings and performance

## Circle and a16z Backing

OpenTrade's backing provides significant advantages:

**Circle Relationship**: Spun out of Circle, the issuer of USDC, providing deep stablecoin ecosystem ties.

**a16z Crypto Investment**: Support from leading crypto venture firm with extensive network.

**Industry Credibility**: Backing from respected names enhances trust with platforms and regulators.

**Strategic Alignment**: Close integration with Circle's broader stablecoin infrastructure.

**Network Access**: Connections to exchanges, platforms, and institutions through backers.

## Pricing

OpenTrade offers institutional pricing:

- **Management Fees**: Annual fees based on assets under management
- **Performance Fees**: Potential performance-based compensation (product dependent)
- **Platform Fees**: Integration and ongoing platform access fees
- **Custom Structures**: Tailored pricing for large platforms or unique requirements
- **Transparent Pricing**: Clear fee schedules with no hidden costs

Contact OpenTrade for detailed pricing based on your platform's specific needs.

## Competitive Advantages

**Purpose-Built for Stablecoins**: Designed specifically for the stablecoin economy, not retrofitted from TradFi.

**Full-Service Solution**: Handles legal, compliance, asset management, and technology in one package.

**Institutional Quality**: No compromise on underlying asset quality or regulatory compliance.

**Proven Team**: Leadership with deep experience in both traditional finance and crypto.

**Strategic Backing**: Support from Circle and a16z Crypto provides credibility and resources.

**Easy Integration**: Simple APIs make offering yield products straightforward for platforms.

**Flexible Deployment**: Support both retail yield products and institutional treasury management.

## Conclusion

OpenTrade represents the missing link between the stablecoin economy and institutional-grade yield-generating assets. By providing a full-service platform that handles legal structuring, asset management, and tokenization, OpenTrade makes it possible for cryptocurrency exchanges, neobanks, and fintech platforms to offer their users access to high-quality real-world asset yields without the complexity of building these capabilities in-house. With backing from Circle and a16z Crypto, and support for blockchain networks like Lux, OpenTrade is positioned to be the standard infrastructure for bringing institutional yield products to the crypto ecosystem. Whether you're an exchange looking to offer yield on user deposits or a company seeking to generate returns on treasury holdings, OpenTrade provides the compliant, institutional-grade solution that bridges traditional finance with the stablecoin economy.



# OpenZeppelin Audits (/integrations/openzeppelin-audit)

---
title: OpenZeppelin Audits
category: Audit Firms
available: ["LUExchange-Chain"]
description: OpenZeppelin is the gold standard in smart contract security, providing expert audits, security tools, and the industry's most widely used smart contract libraries trusted by thousands of projects.
logo: /images/openzeppelin.png
developer: OpenZeppelin
website: https://openzeppelin.com/
documentation: https://openzeppelin.com/security-audits
---

## Overview

OpenZeppelin is the most trusted name in smart contract security, known both for creating the industry-standard OpenZeppelin Contracts library used by thousands of projects and for providing world-class security audit services. Founded by security researchers and Ethereum core contributors, OpenZeppelin has audited hundreds of high-profile projects including Ethereum Foundation,  Coinbase, TheGraph, Aave, Compound, and many of the largest DeFi protocols.

OpenZeppelin's security team brings unparalleled expertise in smart contract security, having both created the security patterns used across the industry and audited the most critical blockchain infrastructure. Their combination of deep protocol knowledge, extensive audit experience, and ongoing contributions to Ethereum security standards makes them the gold standard choice for projects requiring the highest level of security assurance.

## Services

- **Smart Contract Audits**: Comprehensive security audits by industry-leading experts.
- **Protocol Security Reviews**: Architecture and design-level security assessment.
- **Security Consulting**: Advisory services for security best practices and protocol design.
- **Formal Verification**: Mathematical proofs of contract correctness for critical systems.
- **Incident Response**: Emergency support and post-mortem analysis.
- **Security Training**: Educational programs for development teams.
- **OpenZeppelin Defender**: Automated security operations platform.
- **Continuous Monitoring**: Ongoing security surveillance post-deployment.
- **Upgrade Security**: Safe upgrade pattern implementation and review.
- **Economic Security**: Tokenomics and game theory analysis.

## OpenZeppelin Contracts

Beyond audits, OpenZeppelin maintains the industry-standard smart contract library:

**OpenZeppelin Contracts**: Battle-tested Solidity library with implementations of ERC standards, access control, security utilities, and more. Used by thousands of projects as the secure foundation for their contracts.

**Upgradeable Contracts**: Safe upgrade patterns and implementations.

**Cairo Contracts**: Standard library for StarkNet smart contracts.

The library represents years of security research and community contributions.

## Audit Methodology

OpenZeppelin employs the most rigorous audit process in the industry:

1. **Kickoff & Planning**: Deep dive into protocol design and threat model
2. **Automated Analysis**: Run comprehensive suite of security tools
3. **Manual Review**: Expert review by senior security researchers
4. **Architecture Analysis**: Assess system design and attack surfaces
5. **Economic Security**: Review incentive structures and game theory
6. **Integration Testing**: Test interactions with external protocols
7. **Formal Verification**: Prove critical invariants mathematically (when applicable)
8. **Report Compilation**: Detailed report with prioritized findings
9. **Review Call**: In-depth discussion of findings with team
10. **Remediation Support**: Ongoing support during fixes
11. **Re-Audit**: Thorough verification of all remediations

## OpenZeppelin Defender

OpenZeppelin Defender provides ongoing security operations:

**Operations**: Automate smart contract operations securely.

**Monitoring**: Real-time alerts for suspicious transactions.

**Incident Response**: Automated response to detected threats.

**Access Control**: Secure management of contract permissions.

**Upgrades**: Safely execute contract upgrades.

This platform extends security beyond one-time audits into continuous protection.

## Lux Expertise

OpenZeppelin has experience securing protocols across all major blockchain networks including Lux:

- Lux LUExchange-Chain smart contracts
- Cross-chain bridge implementations
- Subnet-specific security considerations
- High-throughput protocol designs
- Lux consensus and finality properties

## Access Through Areta Marketplace

Lux projects can engage OpenZeppelin through the [Areta Audit Marketplace](https://areta.market/lux):

- **Direct Connection**: Get matched with OpenZeppelin for your Lux project
- **Competitive Process**: Compare proposals from multiple top-tier firms
- **Transparent Pricing**: Clear costs without intermediaries
- **Subsidy Eligibility**: Qualify for up to $10k in audit cashback
- **Streamlined Engagement**: Faster than traditional direct outreach
- **Ecosystem Support**: Marketplace built specifically for Lux

## Notable Audits

OpenZeppelin has audited the most critical infrastructure in blockchain:

- Ethereum Foundation (multiple projects)
- Coinbase (various infrastructure)
- Aave (multiple versions)
- Compound
- TheGraph
- Gnosis Safe
- Synthetix
- MakerDAO
- And hundreds of other leading projects

## Why Choose OpenZeppelin

**Industry Leader**: Most recognized and trusted name in smart contract security.

**Library Creators**: Built the security patterns the industry relies on.

**Deep Expertise**: Team includes Ethereum core contributors and security researchers.

**Comprehensive Methodology**: Most thorough audit process in the industry.

**Formal Verification**: Capability to provide mathematical security proofs.

**Ongoing Tools**: Defender platform provides continuous security.

**Best Practices**: Define what security best practices mean in the industry.

**Institutional Trust**: Chosen by the most security-critical projects.

## Research and Standards

OpenZeppelin actively shapes blockchain security:

- EIP contributions and security standards
- Security research and publications
- Conference presentations and workshops
- Open-source security tools and libraries
- Community education and resources

## Pricing

OpenZeppelin audits typically serve:

- High-value protocols requiring maximum security assurance
- Enterprise blockchain implementations
- Infrastructure-level systems
- Projects with significant funding and complexity

Pricing reflects their premium positioning and unmatched expertise. Contact via Areta marketplace or directly for proposals.

## Getting Started

To engage OpenZeppelin:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit your audit request
   - Receive proposal from OpenZeppelin
   - Access potential subsidies

2. **Direct Contact**:
   - Visit [openzeppelin.com/security-audits](https://openzeppelin.com/security-audits)
   - Submit audit inquiry
   - Schedule consultation
   - Receive detailed proposal

## Deliverables

OpenZeppelin provides:

- **Comprehensive Audit Report**: Exhaustive findings with detailed analysis
- **Executive Summary**: High-level overview for stakeholders
- **Architecture Recommendations**: System-level security improvements
- **Code Review**: Line-by-line assessment and suggestions
- **Formal Verification Report**: Mathematical proofs (when applicable)
- **Re-Audit Report**: Verification of all fixes
- **Defender Integration**: Optional ongoing monitoring setup

## Training and Resources

OpenZeppelin provides extensive security resources:

- OpenZeppelin Contracts documentation
- Security guides and best practices
- Video tutorials and workshops
- Smart contract security blog
- Community forums and support

## Conclusion

OpenZeppelin represents the gold standard in smart contract security, combining their position as creators of the industry's most-used smart contract library with world-class audit services trusted by the largest projects in blockchain. For Lux protocols requiring the highest level of security assurance, OpenZeppelin's unmatched expertise, comprehensive methodology, and ongoing security tools through Defender provide institutional-grade protection. Available through the Areta Audit Marketplace for streamlined engagement and potential subsidies, OpenZeppelin ensures your Lux project meets the same security standards as Ethereum Foundation, Coinbase, and the industry's most critical infrastructure.



# OpenZeppelin (/integrations/openzeppelin)

---
title: OpenZeppelin
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "OpenZeppelin provides high-quality security audits for smart contracts with additional auditing hours for community contributions."
logo: /images/openzeppelin.png
developer: OpenZeppelin
website: https://www.openzeppelin.com/security-audits
documentation: https://docs.openzeppelin.com/
---

## Overview

OpenZeppelin is a leading security firm specializing in smart contract security, best known for their widely-used secure contract libraries and security tools. They provide high-quality audits for projects building on Lux, combining manual code review with automated analysis. OpenZeppelin's team includes smart contract experts with extensive experience in identifying vulnerabilities and recommending secure development practices.

## Features

- **Smart Contract Audits**: Comprehensive review of smart contract code and architecture.
- **Security Research**: Continuous research on smart contract vulnerabilities and security patterns.
- **Architecture Review**: Assessment of system architecture and security design.
- **Best Practice Guidance**: Recommendations aligned with industry security standards.
- **Community Contributions**: Additional auditing hours available for community-focused projects.
- **Library Expertise**: Deep knowledge of secure smart contract patterns and libraries.
- **Custom Tooling**: Development and use of specialized security tools.

## Getting Started

To engage OpenZeppelin for security audits:

1. **Request an Audit**: Contact OpenZeppelin through their website to initiate the process.
2. **Scope Definition**: Collaborate to define the audit scope, timeline, and objectives.
3. **Audit Process**: 
   - Manual code review by security experts
   - Automated analysis using proprietary and open-source tools
   - Vulnerability identification and classification
   - Detailed remediation guidance
4. **Report Delivery**: Receive a comprehensive audit report with detailed findings.
5. **Optional Follow-up**: Post-audit verification of implemented fixes.

## Use Cases

OpenZeppelin security audits are particularly suitable for:

- **DeFi Protocols**: Thorough validation of financial smart contracts.
- **Open Source Projects**: Security reviews with potential for additional community-focused audit hours.
- **Projects Using OpenZeppelin Libraries**: Specialized expertise in reviewing implementations that build on their libraries.
- **EVM-Based Smart Contracts**: Deep expertise in EVM specifics and security implications.
- **Governance Systems**: Review of DAO and governance contract implementations.

## Conclusion

OpenZeppelin provides high-quality security audits with specific expertise in smart contract security and EVM environments. Their deep understanding of secure contract patterns and experience with their widely-used libraries make them particularly valuable for projects building smart contracts on Lux's LUExchange-Chain and EVM-compatible L1s. For community-oriented projects, they may offer additional auditing hours, providing extended value and thorough security coverage. 

# Orbital (/integrations/orbital)

---
title: Orbital
category: Payments
available: ["LUExchange-Chain"]
description: Orbital provides comprehensive payment solutions including merchant acquiring, payment gateway, and transaction processing services with support for traditional and digital currencies.
logo: /images/orbital.png
developer: Orbital
website: https://getorbital.com/
documentation: https://docs.getorbital.com/
---

## Overview

Orbital is a comprehensive payment solutions provider offering merchant acquiring, payment gateway services, and transaction processing capabilities for businesses of all sizes. By combining traditional payment processing with support for digital currencies, Orbital enables merchants to accept payments across multiple channels and currencies while maintaining the security, compliance, and reliability required for professional commerce.

The platform provides end-to-end payment infrastructure from customer checkout to settlement, handling the technical complexity of payment processing so businesses can focus on their core operations.

## Features

- **Merchant Acquiring**: Complete merchant services for payment acceptance.
- **Payment Gateway**: Secure gateway for processing online and in-person payments.
- **Multi-Currency**: Support for fiat currencies and cryptocurrencies.
- **Multiple Payment Methods**: Credit cards, debit cards, ACH, crypto, and more.
- **Transaction Processing**: Reliable processing with high uptime.
- **Fraud Prevention**: Built-in fraud detection and prevention tools.
- **PCI Compliance**: PCI DSS compliant payment infrastructure.
- **API Integration**: Developer-friendly APIs for custom integration.
- **Reporting**: Comprehensive transaction reporting and analytics.
- **Settlement**: Flexible settlement options and schedules.
- **Multi-Channel**: Support for online, mobile, and in-person payments.

## Getting Started

To integrate Orbital:

1. **Merchant Onboarding**: Apply for a merchant account with Orbital.

2. **Account Setup**: Configure your payment preferences:
   - Accepted payment methods
   - Settlement preferences
   - Fraud rules
   - Integration approach

3. **Integration**: Implement Orbital's payment gateway:
   - Integrate payment APIs
   - Add checkout flows
   - Configure webhooks
   - Test transactions

4. **Go Live**: Start processing customer payments.

## Lux Support

Orbital's multi-currency payment infrastructure includes support for blockchain-based payments on networks like Lux, enabling merchants to accept LUX and Lux stablecoins alongside traditional payment methods.

## Use Cases

**E-Commerce**: Process online payments for retail businesses.

**Omnichannel Retail**: Accept payments online, mobile, and in-store.

**Subscription Services**: Process recurring payments automatically.

**High-Volume Merchants**: Handle large transaction volumes reliably.

**International Sales**: Accept payments from global customers.

**Crypto Acceptance**: Integrate cryptocurrency payment options.

## Conclusion

Orbital provides comprehensive payment solutions that enable businesses to accept and process payments across multiple channels and currencies, including support for blockchain-based payments on networks like Lux for complete payment flexibility.



# Paladin Security (/integrations/paladinsec)

---
title: Paladin Security
category: Audit Firms
available: ["LUExchange-Chain"]
description: Paladin Security provides expert smart contract audits and blockchain security services with a focus on delivering thorough security assessments for DeFi, NFT, and infrastructure protocols.
logo: /images/paladin.svg
developer: Paladin Security
website: https://paladinsec.co/
documentation: https://paladinsec.co/services
---

## Overview

Paladin Security is a blockchain security firm specializing in comprehensive smart contract audits and security assessments for Web3 protocols. With a focus on thoroughness and attention to detail, Paladin helps development teams identify and remediate vulnerabilities before launching on Lux and other blockchain networks. The firm brings together experienced security researchers with deep knowledge of smart contract security patterns, attack vectors, and best practices.

Paladin's approach combines systematic manual code review with automated security tools to ensure comprehensive coverage of potential security issues. Their auditors have experience across multiple blockchain ecosystems and protocol types, from DeFi to NFTs to infrastructure.

## Services

- **Smart Contract Audits**: Full security audits of Solidity and other smart contract languages.
- **Security Assessments**: Comprehensive evaluation of protocol architecture and design.
- **Vulnerability Analysis**: Identification and classification of security issues by severity.
- **Code Quality Review**: Assessment of code organization, documentation, and maintainability.
- **Gas Optimization Analysis**: Recommendations for reducing transaction costs.
- **Post-Audit Consultation**: Support during vulnerability remediation.
- **Re-Audits**: Verification audits after fixes are implemented.
- **Security Documentation**: Detailed audit reports with findings and recommendations.
- **Ongoing Security Support**: Available for consultation on security matters.

## Audit Methodology

Paladin follows a structured approach to security audits:

1. **Scope Definition**: Establish clear audit boundaries and objectives
2. **Documentation Review**: Understand protocol design and intended behavior
3. **Automated Testing**: Run security analysis tools on codebase
4. **Manual Code Review**: Line-by-line examination by experienced auditors
5. **Vulnerability Testing**: Test for known attack patterns and edge cases
6. **Reporting**: Compile comprehensive report with prioritized findings
7. **Team Collaboration**: Present findings and answer questions
8. **Remediation Support**: Assist with fixing identified issues
9. **Verification**: Re-audit to confirm all issues are resolved

## Lux Expertise

Paladin has experience auditing protocols built on Lux LUExchange-Chain, understanding the platform-specific considerations including:

- Lux smart contract patterns
- EVM compatibility nuances
- Cross-chain bridge security
- Subnet-specific implementations
- High-throughput protocol designs

## Access Through Areta Marketplace

Lux builders can connect with Paladin Security through the [Areta Audit Marketplace](https://areta.market/lux):

- **Quick Matching**: Submit request and receive quotes within 48 hours
- **Multiple Proposals**: Compare Paladin's quote with other top auditors
- **Transparent Pricing**: No hidden fees or intermediaries
- **Subsidy Programs**: Potential eligibility for up to $10k in audit cashback
- **Streamlined Process**: Simplified engagement compared to direct outreach
- **Ecosystem-Specific**: Marketplace designed for Lux projects

## Audit Focus Areas

**DeFi Protocols**: DEXs, lending platforms, staking, and yield optimization.

**NFT Projects**: NFT minting, marketplaces, and gaming integrations.

**Token Contracts**: ERC-20, ERC-721, and custom token implementations.

**Governance Systems**: DAO contracts and voting mechanisms.

**Bridge Protocols**: Cross-chain bridges and messaging systems.

**Infrastructure**: Protocol-level infrastructure and system contracts.

## Why Choose Paladin

**Thorough Analysis**: Comprehensive review combining automated and manual techniques.

**Experienced Team**: Security researchers with extensive smart contract audit experience.

**Clear Communication**: Detailed reports with actionable recommendations.

**Reasonable Pricing**: Competitive rates for high-quality security audits.

**Fast Turnaround**: Efficient processes without sacrificing thoroughness.

**Lux Knowledge**: Experience with Lux ecosystem protocols.

## Getting Started

To engage Paladin Security:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit your audit request with scope details
   - Receive competitive quote from Paladin
   - Choose based on pricing, timeline, and fit

2. **Direct Contact**:
   - Visit [paladinsec.co](https://paladinsec.co/)
   - Request audit consultation
   - Discuss project scope and timeline
   - Receive audit proposal

## Deliverables

Paladin provides comprehensive audit deliverables:

- **Audit Report**: Complete findings with severity classifications and recommendations
- **Executive Summary**: Overview suitable for stakeholders and investors
- **Code Suggestions**: Specific code improvements and optimizations
- **Remediation Guidance**: Clear instructions for fixing identified issues
- **Re-Audit Report**: Verification that all issues have been properly addressed
- **Security Badge**: Post-audit badge for your documentation

## Conclusion

Paladin Security provides professional smart contract auditing services that help Lux projects launch securely and confidently. Accessible through the Areta Audit Marketplace for streamlined engagement and potential subsidies, Paladin combines thorough security methodology with clear communication to ensure your protocol is production-ready and protected against vulnerabilities.



# Palmera (/integrations/palmera-infra-provider)

---
title: Palmera
category: Wallets and Account Abstraction
available: ["All Lux L1s"]
description: Palmera is a Safe multisig infrastructure provider powering secure smart-account deployments, white-label UIs, and backend services for Lux L1s.
logo: /images/palmera.png
developer: Palmera
website: https://www.palmeradao.xyz/
documentation: https://docs.palmeradao.xyz/safe-multisig-deployment
---

## Overview

[Palmera](https://www.palmeradao.xyz/) provides end-to-end Safe multisig infrastructure for Lux L1s, enabling teams to deploy and operate secure smart accounts using official Safe contracts. With over four years of experience running Safe infrastructure, Palmera ensures reliable, production-ready systems with ongoing maintenance, SLAs, and DevOps support.

Palmera's infrastructure solution includes official Safe contract deployment, white-label Safe UI hosting, backend services, monitoring, and guaranteed uptime through SLAs. This comprehensive approach allows Lux L1 teams to focus on building their ecosystems while Palmera handles the complex infrastructure requirements.

## Features

Palmera provides a complete Safe multisig infrastructure solution with the following features:

- **Official Safe Contract Deployment**: Deployment of Safe multisig contracts using the canonical Safe releases, ensuring compatibility and security alignment with the official Safe ecosystem.

- **White-Label Safe UI**: Customizable Safe interface hosted and maintained by Palmera for each Lux L1, providing teams with a branded, production-ready user interface.

- **Infrastructure & DevOps**: Backend services, monitoring, and guaranteed uptime via SLAs, ensuring reliable operation of Safe infrastructure.

- **Proposer & Nested Safes**: Advanced Safe features fully supported across the chain ecosystem, enabling complex multi-signature workflows.

- **Safe App Compatibility**: Access to the Safe Apps ecosystem for extended capabilities, allowing teams to leverage the full range of Safe integrations.

- **Security-First Architecture**: Continuous updates and alignment with Safe's latest security requirements, ensuring infrastructure remains secure and up-to-date.

## Getting Started

Lux L1 teams can integrate Safe multisig infrastructure by contacting Palmera. The onboarding and setup process includes:

1. **Chain data collection**: Palmera gathers necessary information about your Lux L1 chain.
2. **Official Safe contract deployment**: Deployment of canonical Safe contracts to your chain.
3. **Backend indexing and infrastructure setup**: Configuration of backend services and indexing infrastructure.
4. **UI deployment and customization**: Setup and customization of the white-label Safe UI.
5. **Testing, QA, and launch support**: Comprehensive testing and quality assurance before production launch.

Teams can also use **Palmera's Safe One-Click Deployment**, which already supports deployment for Lux L1s for instant access to official Safe contracts and infrastructure.

To begin integration, visit [Palmera's website](https://www.palmeradao.xyz/) to get started.

## Documentation Link

For full technical documentation, setup guides, and API references, visit the [Palmera Documentation](https://docs.palmeradao.xyz/safe-multisig-deployment).

## Conclusion

Palmera brings secure, production-ready Safe multisig infrastructure to all Lux L1s. With strong DevOps practices, reliable system architecture, and deep Safe ecosystem expertise, Palmera supports Lux builders in scaling their ecosystems with confidence and secure smart-account foundations.



# PancakeSwap (/integrations/pancakeswap)

---
title: PancakeSwap
category: DeFi
available: ["LUExchange-Chain"]
description: "PancakeSwap is a leading DEX offering token swaps, yield farming, and perpetual trading on Lux's LUExchange-Chain with gamified features."
logo: /images/pancakeswap.jpeg
developer: PancakeSwap
website: https://pancakeswap.finance/
documentation: https://docs.pancakeswap.finance/
---

## Overview

PancakeSwap is a popular decentralized exchange that has expanded to Lux's LUExchange-Chain, bringing its comprehensive suite of DeFi services including token swaps, yield farming, and perpetual trading. Known for its user-friendly interface and gamified features, PancakeSwap combines serious DeFi functionality with an engaging user experience.

## Features

- **Smart Router**: Intelligent routing system for optimal trade execution and better rates.
- **Perpetual Trading**: Up to 100x leverage trading with competitive fees.
- **Stable Swaps**: Optimized pools for stablecoin trading with minimal slippage.
- **Yield Farming**: Multiple opportunities to earn CAKE and other tokens.
- **Fixed-Term Staking**: Flexible and fixed-term staking options for CAKE.
- **NFT Ecosystem**: Integration of NFTs with trading and farming features.
- **IFO (Initial Farm Offering)**: Launch platform for new projects.

## Getting Started

To begin using PancakeSwap on Lux:

1. **Access Platform**: Visit [PancakeSwap](https://pancakeswap.finance/) and switch to Lux network.
2. **Connect Wallet**: Link your Web3 wallet and ensure you have LUX for gas fees.
3. **Start Trading**: 
   - Select tokens for swapping
   - Review exchange rate and slippage
   - Confirm transaction
4. **Explore Features**: Discover farming, staking, and perpetual trading options.

## Documentation

For detailed guides and technical documentation, visit the [PancakeSwap Documentation](https://docs.pancakeswap.finance/).

## Use Cases

PancakeSwap serves various DeFi needs:

- **Token Swapping**: Efficient token exchanges with competitive rates.
- **Perpetual Trading**: Access to leveraged trading with deep liquidity.
- **Yield Generation**: Multiple farming and staking opportunities.
- **Project Launches**: Platform for new token launches through IFO.
- **Stablecoin Trading**: Optimized pools for stablecoin swaps.

## Conclusion

PancakeSwap brings its proven DEX model to Lux's LUExchange-Chain, offering users a full suite of DeFi services with an engaging interface. Whether you're looking to trade tokens, provide liquidity, or engage in perpetual trading, PancakeSwap provides a comprehensive platform that combines serious DeFi functionality with an accessible user experience.

# Pangolin (/integrations/pangolin)

---
title: Pangolin
category: DeFi
available: ["LUExchange-Chain"]
description: "Pangolin is a community-driven decentralized exchange for Lux and Ethereum assets with fast settlement, low transaction fees, and a democratic distribution."
logo: /images/pangolin.jpeg
developer: Pangolin DAO
website: https://pangolin.exchange/
documentation: https://docs.pangolin.exchange/
---

## Overview

Pangolin is a decentralized exchange (DEX) built on Lux, offering fast and cost-effective trading of Lux and Ethereum assets. As a community-driven platform, Pangolin emphasizes democratic governance and fair token distribution while providing essential DeFi services including swapping, yield farming, and liquidity provision.

## Features

- **Fast Settlement**: Leverage Lux's quick finality for near-instant trade settlement.
- **Low Transaction Fees**: Benefit from Lux's LUExchange-Chain efficiency for reduced trading costs.
- **Cross-Chain Trading**: Trade both Lux-native and Ethereum assets.
- **Yield Farming**: Earn rewards through liquidity provision and farming opportunities.
- **Community Governance**: Participate in platform decisions through the PNG governance token.
- **User-Friendly Interface**: Simple and intuitive trading interface for all user levels.

## Getting Started

To begin using Pangolin:

1. **Connect Wallet**: Visit [Pangolin Exchange](https://pangolin.exchange/) and connect your Web3 wallet.
2. **Fund Your Wallet**: Ensure you have LUX for transaction fees.
3. **Start Trading**: 
   - Select tokens to trade
   - Review rates and slippage
   - Confirm transaction
4. **Provide Liquidity**: Optionally, add liquidity to earn trading fees and PNG rewards.

## Documentation

For detailed guides and technical documentation, visit the [Pangolin Documentation](https://docs.pangolin.exchange/).

## Use Cases

Pangolin serves various DeFi needs:

- **Token Swaps**: Quick and efficient token exchanges on Lux.
- **Liquidity Provision**: Earn yields by providing liquidity to trading pairs.
- **Yield Farming**: Access additional rewards through farming programs.
- **Cross-Chain Access**: Trade Ethereum-based assets on Lux.
- **DAO Participation**: Engage in platform governance through PNG token.

## Conclusion

Pangolin provides a robust, community-driven DEX solution on Lux's LUExchange-Chain, combining efficient trading with democratic governance. Whether you're looking to swap tokens, provide liquidity, or participate in yield farming, Pangolin offers a comprehensive suite of DeFi services with the speed and cost advantages of the Lux network.

# ParaFi (/integrations/parafi)

---
title: ParaFi
category: Assets
available: ["LUExchange-Chain"]
description: "ParaFi Capital is a digital asset investment firm offering tokenized investment products and DeFi strategies."
logo: /images/parafi.png
developer: ParaFi Capital
website: https://www.parafi.capital/
documentation: https://www.parafi.capital/
---

## Overview

ParaFi Capital is a leading digital asset investment firm that bridges traditional finance and decentralized finance. Through tokenized investment products and strategic DeFi positions, ParaFi provides institutional and qualified investors with access to digital asset opportunities, combining traditional investment rigor with blockchain-native innovation.

## Features

- **Tokenized Products**: Investment products available as tokenized assets
- **DeFi Strategies**: Professional DeFi investment strategies
- **Institutional Grade**: Investment processes meeting institutional standards
- **Research-Driven**: Deep research into DeFi protocols and opportunities
- **Portfolio Management**: Professional portfolio management services
- **Regulatory Compliance**: Compliant investment structures

## Getting Started

To learn about ParaFi investment products:

1. **Visit ParaFi**: Explore [ParaFi Capital](https://www.parafi.capital/)
2. **Review Offerings**: Learn about available investment products
3. **Contact Team**: Reach out for investment inquiries
4. **Due Diligence**: Complete investor qualification process
5. **Invest**: Access ParaFi investment products

## Documentation

For more information, visit the [ParaFi Capital website](https://www.parafi.capital/).

## Use Cases

- **DeFi Exposure**: Gain professional DeFi exposure
- **Institutional Investment**: Institutional-grade digital asset investment
- **Tokenized Funds**: Access tokenized investment fund products
- **Strategic Allocation**: Strategic allocation to digital assets

## Conclusion

ParaFi Capital provides professional digital asset investment products on Lux, offering institutional-grade access to DeFi and tokenized asset opportunities.


# Parallel Markets (/integrations/parallel-markets)

---
title: Parallel Markets
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: Parallel Markets provides comprehensive KYC/AML solutions with a portable identity system ideal for crypto platforms implementing txAllowlist precompiles.
logo: /images/parallel-markets.png
developer: Parallel Markets
website: https://parallelmarkets.com/
documentation: https://developer.parallelmarkets.com/
---

## Overview

Parallel Markets offers a suite of streamlined identity verification and compliance solutions designed for financial institutions and blockchain platforms. Their innovative KYC (Know Your Customer) and AML (Anti-Money Laundering) tools verify user identities without the traditional friction in onboarding processes. For blockchain applications implementing txAllowlist precompiles, Parallel Markets provides a portable identity solution that enables users to verify once and access multiple platforms, creating a seamless experience while maintaining robust compliance.

## Features

- **Portable Identity Verification**: Users can complete KYC verification once and reuse their verified credentials across platforms in the Parallel Markets ecosystem.
- **Comprehensive KYC/AML Screening**: Automated verification against global sanctions lists, PEP (Politically Exposed Persons) databases, and adverse media sources.
- **Business Verification (KYB)**: Verify corporate entities, map beneficial ownership structures, and perform due diligence checks for institutional users.
- **No-Code Integration**: Implement identity verification with minimal development resources through their JavaScript SDK or API integration.
- **Real-Time Monitoring**: Continuous monitoring of user profiles for changes in risk status or sanctions exposure.
- **Customizable Verification Flows**: Design verification journeys specific to your platform's risk profile and regulatory requirements.
- **Dashboard Analytics**: Access verification results and monitor compliance metrics through a unified dashboard.

## Getting Started

To integrate Parallel Markets into your Lux-based application with txAllowlist precompiles, follow these steps:

1. **Account Setup**: Contact Parallel Markets to create an account and obtain API credentials.
2. **Integration Planning**: Choose between JavaScript SDK for frontend integration or direct API calls from your backend.
3. **Configure Verification Flow**: Set up your verification requirements based on your compliance needs.
4. **Implementation**: Follow the [documentation](https://developer.parallelmarkets.com/) to add the verification flow to your application.
5. **Testing**: Verify the integration in a sandbox environment before going live.
6. **Verification-to-Allowlist Mapping**: Connect user verification status to your txAllowlist management to ensure only verified users can transact.

## Integration with txAllowlist

Parallel Markets is particularly well-suited for platforms implementing txAllowlist precompiles because:

1. **Streamlined Allowlisting**: When a user completes verification through Parallel Markets, your application can automatically add their wallet address to the txAllowlist.
2. **Verification Status Monitoring**: If a user's compliance status changes (e.g., they appear on a sanctions list), your application can receive webhook notifications and remove their address from the allowlist.
3. **Programmatic Control**: The API-driven approach allows for complete automation of the allowlist management based on identity verification results.
4. **Reduced Onboarding Friction**: Users who have already verified with another platform in the Parallel Markets ecosystem can be fast-tracked through your verification process.

## Documentation

Comprehensive integration guides and API documentation are available in the [Parallel Markets Developer Documentation](https://developer.parallelmarkets.com/). The documentation includes details on:

- JavaScript SDK implementation
- Server-side API integration
- Webhook setup for status notifications
- Testing and sandbox environments
- Handling verification results

## Use Cases

Parallel Markets' identity verification solutions are ideal for various Lux-based applications:

- **Permissioned DeFi Protocols**: Ensure participants in lending or trading pools meet regulatory requirements.
- **Tokenized Securities**: Verify investor accreditation status and identity for compliant security token offerings.
- **Enterprise Blockchains**: Create permissioned networks with verified corporate and individual participants.
- **Regulated Exchanges**: Build compliant DEXs that satisfy regulatory requirements while maintaining a good user experience.
- **Cross-Chain Applications**: Apply consistent compliance standards across multiple blockchain networks.

## Conclusion

Parallel Markets offers a powerful solution for blockchain platforms looking to implement identity verification alongside txAllowlist precompiles. By providing a portable, user-friendly verification system that maintains high compliance standards, Parallel Markets enables platforms to create secure, regulated environments without sacrificing the user experience. The combination of their verification tools with Lux's txAllowlist functionality creates a comprehensive solution for building compliant blockchain applications. 

# Particle Network (/integrations/particle-network)

---
title: Particle Network
category: Chain Abstraction
available: ["LUExchange-Chain"]
description: Chain abstraction powered by Universal Accounts. One account, one balance, any chain.
logo: /images/particle-network.png
developer: Particle Network
website: https://particle.network/
documentation: https://developers.particle.network/intro/introduction
---

## **Overview**

Particle Network enables **chain abstraction** through its **Universal Accounts** infrastructure, giving users a unified account and balance. This allows them to interact with your Lux dApp with assets from any supported chain (EVM chains and Solana) without bridging. 

Universal Accounts also abstract away network switching and gas management, allowing users to pay gas with any token. Thanks to this, Particle Network delivers a truly chain-agnostic experience where liquidity can be deployed on any chain, independently of where the user holds funds.

Within Universal Accounts users’ assets are also automatically combined, allowing them to deposit tokens from multiple chains and spend them as if they were in the same chain.

## **Features**

* **Universal Accounts**: One account and one balance across all supported chains—no need to bridge or switch networks.  
* **Chain Abstraction**: Handle multi-chain logic like transfers, payments, and smart contract interactions at the account level, not the chain level.  
* **Multi-Chain Support**: Works with nearly all EVM chains and Solana, with new integrations added frequently.  
* **Developer Flexibility**: Compatible with common tools like ethers, wagmi, and viem.

## **Getting Started**

To integrate **Universal Accounts** into your application:

1. **Initialize the Universal Accounts SDK** using your API key from the [Particle Dashboard](https://dashboard.particle.network/).  
2. **Fetch the user’s universal address and unified balance** – a single address and balance valid across all chains.  
3. **Build and send UserOperations** using any supported network.  
4. **Deploy your chain-agnostic app** – users can now transact across ecosystems with a single unified account.

[Check out the Quickstart](https://developers.particle.network/universal-accounts/cha/web-quickstart) for more details.

## **Use Cases**

Particle Network empowers developers to create frictionless, multi-chain applications for a wide variety of use cases. These, and the benefits of UAs for them, include: 

* **DeFi Platforms**: Multi-chain deposits, cross-chain swaps, paying gas in any currency, and allowing users to combine their liquidity from different chains.  
* **Blockchain Games**: Web2-like onboarding via social logins, with full on-chain settlement and deposits/withdrawals to/from any chain.  
* **NFT Marketplaces**: Cross-chain spending (deposit assets from one chain, buy/mint in another) and combined ownership/listing of NFTs from multiple chains.  
* **Fintech & Payments**: Allowing users to pay gas in any token, simplified stablecoin-centric interfaces.  
* **Others**: Given Universal Accounts multi-dApp ecosystem, ability for users to use their UAs across a number of apps.

## **Supported Chains**

Universal Accounts currently support most **EVM chains and Solana**, and will soon support all major Lux L1s.

View the full list: [Network Coverage](https://developers.particle.network/universal-accounts/cha/chains)

## **Community**

* **Universal Accounts on Lux**: [Retail-friendly UX: Accepting stablecoins from any chain on Lux dapps](https://blog.particle.network/retail-friendly-ux-accepting-stablecoins-from-any-chain-on-lux-dapps/)  
* **Slack**: [Join Particle’s Slack](https://join.slack.com/t/particlenetworkhq/shared_invite/zt-3blxdzcd2-7skD8MNWUn_20eOrp9SICA)  
* **GitHub**: [Particle Network GitHub](https://github.com/particle-network)

## **TL;DR for Developers**

If you want your users to:

* Log in once  
* Use a single account and balance across all chains  
* Skip network switching, bridging, and gas management

Then you’re looking for **chain abstraction**.

You’re looking for **Universal Accounts**.

Start building → [Universal Accounts SDK](https://developers.particle.network/universal-accounts/cha/overview)

# PayAI (/integrations/payai)

---
title: PayAI
category: x402
available: ["LUExchange-Chain"]
description: PayAI offers the x402 protocol, a payment infrastructure that enables monetization of AI agents and services on Lux.
logo: /images/payai.svg
developer: PayAI
website: https://payai.network/
documentation: https://docs.payai.network/introduction
---

## Overview

PayAI provides the x402 protocol, a comprehensive payment infrastructure designed specifically for AI agent monetization and service payments on Lux's LUExchange-Chain.

The x402 protocol standardizes how AI agents and services can accept payments, making it easier for developers to build monetized AI applications without worrying about complex payment infrastructure.

## What is x402?

The x402 protocol is a payment standard that facilitates transactions between:
- **Merchants**: AI service providers and agents that offer paid services
- **Clients**: Users or applications that consume AI services
- **Facilitators**: Infrastructure that handles payment processing on Lux

## Key Features

- **Lux Native**: Built to leverage Lux's fast finality and low transaction costs
- **Simple Integration**: SDKs available in TypeScript and Python for both merchants and clients
- **Facilitator Network**: PayAI operates facilitators that handle payment routing on Lux
- **AI-First Design**: Built specifically for AI agent monetization and service payments

## Getting Started

### For Merchants (AI Service Providers)

If you're building an AI service or agent that needs to accept payments on Lux:

1. **Choose Your SDK**: PayAI provides SDKs in both TypeScript and Python
2. **Set Up Payment Endpoints**: Configure your service to accept x402 protocol payments on Lux
3. **Configure for Lux**: Use the `lux` network string for mainnet or `lux-testnet` for testnet
4. **Start Accepting Payments**: Your AI agent can now receive payments for services in LUX

### For Clients (Service Consumers)

If you're building an application that consumes paid AI services on Lux:

1. **Install the Client SDK**: Available in TypeScript and Python
2. **Configure for Lux**: Set up payments using Lux LUExchange-Chain
3. **Connect to Services**: Start paying for AI services through the x402 protocol with LUX

## Use Cases

### AI Agent Monetization
Enable your AI agents to charge for their services on a per-request or subscription basis.

### Freelance AI Services
Build marketplaces where AI agents can offer specialized services and receive payment automatically.

### Token-Gated AI Access
Create premium AI services that require payment to access, with automated payment verification.

### CT (Crypto Twitter) Agent Monetization
Monetize AI agents that provide crypto analysis, trading signals, or social media insights.

## Documentation

For detailed implementation guides and API references:
- [PayAI Documentation](https://docs.payai.network/introduction)
- [Supported Networks](https://docs.payai.network/x402/supported-networks)

## Integration Examples

### Express Server Example

Set up an Express server that accepts x402 payments on Lux:

**Environment Variables (.env)**

```bash
FACILITATOR_URL=https://facilitator.payai.network
NETWORK=lux-testnet # or lux for mainnet
ADDRESS=0x... # wallet public address you want to receive payments to
```

**Server Code (index.ts)**

```typescript
import { config } from "dotenv";
import express from "express";
import { paymentMiddleware, Resource } from "x402-express";
config();

const facilitatorUrl = process.env.FACILITATOR_URL as Resource;
const payTo = process.env.ADDRESS as `0x${string}`;

if (!facilitatorUrl || !payTo) {
  console.error("Missing required environment variables");
  process.exit(1);
}

const app = express();

app.use(
  paymentMiddleware(
    payTo,
    {
      "GET /weather": {
        // USDC amount in dollars
        price: "$0.001",
        network: "lux-testnet", // or "lux" for mainnet
      },
      "/premium/*": {
        // Define atomic amounts in any EIP-3009 token
        price: {
          amount: "100000",
          asset: {
            address: "0xabc",
            decimals: 18,
            eip712: {
              name: "WETH",
              version: "1",
            },
          },
        },
        network: "lux-testnet", // or "lux" for mainnet
      },
    },
    {
      url: facilitatorUrl,
    },
  ),
);

app.get("/weather", (req, res) => {
  res.send({
    report: {
      weather: "sunny",
      temperature: 70,
    },
  });
});

app.get("/premium/content", (req, res) => {
  res.send({
    content: "This is premium content",
  });
});

app.listen(4021, () => {
  console.log(`Server listening at http://localhost:${4021}`);
});
```

## Lux LUExchange-Chain Integration

When deploying x402 on Lux's LUExchange-Chain:

- **Network String**: Use `lux` for mainnet or `lux-testnet` for testnet
- **Native Token**: LUX is used for gas fees
- **Fast Finality**: Benefit from Lux's sub-second transaction finality
- **Low Fees**: Enable micropayments for AI services with minimal transaction costs

## Conclusion

PayAI's x402 protocol makes it simple to build monetized AI services on Lux. Whether you're creating AI agents that need to earn revenue or building applications that consume paid AI services, x402 provides the payment infrastructure you need to get started quickly. With Lux LUExchange-Chain's fast finality and low transaction costs, you can enable seamless micropayments for AI services.



# PeckShield (/integrations/peckshield)

---
title: PeckShield
category: Audit Firms
available: ["LUExchange-Chain"]
description: PeckShield is a leading blockchain security company providing smart contract audits, security solutions, and real-time threat monitoring for protocols across multiple blockchain ecosystems.
logo: /images/peckshield.jpg
developer: PeckShield
website: https://peckshield.com/
documentation: https://peckshield.com/services
---

## Overview

PeckShield is one of the most prolific and well-known blockchain security companies globally, having audited thousands of smart contracts and protocols across multiple blockchain ecosystems. Founded by security researchers and blockchain experts, PeckShield provides comprehensive security services including smart contract audits, real-time security monitoring, and incident response. The firm is recognized for its extensive audit portfolio, quick turnaround times, and expertise across diverse protocol types.

PeckShield's security research team continuously monitors the blockchain ecosystem for emerging threats and vulnerabilities, publishing regular security reports and advisories that help keep the entire industry informed. Their combination of deep technical expertise, automated security tools, and rapid response capabilities makes them a trusted partner for projects of all sizes.

## Services

- **Smart Contract Audits**: Comprehensive security audits for Solidity, Vyper, and other languages.
- **Security Assessments**: Full protocol architecture and design review.
- **Real-Time Monitoring**: Continuous security monitoring post-deployment.
- **Incident Response**: Emergency support for security incidents and exploits.
- **Vulnerability Research**: Proactive identification of emerging threats.
- **Security Tools**: Automated analysis and detection systems.
- **Penetration Testing**: Adversarial testing of protocols and systems.
- **Code Review**: Detailed examination of smart contract implementations.
- **Consulting Services**: Security advisory for protocol design and architecture.
- **Public Security Reports**: Regular threat intelligence and security updates.

## Audit Portfolio

PeckShield has one of the largest audit portfolios in the industry, having audited:

- 1000+ blockchain projects
- Major DeFi protocols with billions in TVL
- Leading NFT marketplaces and platforms
- Cross-chain bridges and infrastructure
- Layer 1 and Layer 2 blockchain protocols
- GameFi and metaverse projects

This extensive experience provides PeckShield with unparalleled knowledge of security patterns and vulnerabilities across protocol types.

## Audit Methodology

PeckShield employs a comprehensive audit approach:

1. **Preliminary Assessment**: Review scope, documentation, and architecture
2. **Automated Analysis**: Run multiple security analysis tools
3. **Manual Code Review**: Expert review by senior security researchers
4. **Vulnerability Detection**: Test for known attack vectors and edge cases
5. **Logic Analysis**: Verify business logic and economic mechanisms
6. **Documentation**: Compile detailed findings with severity ratings
7. **Presentation**: Discuss findings with development team
8. **Remediation Support**: Available for questions during fixes
9. **Re-Audit**: Verify fixes and issue final report

## PeckShield Security Platform

Beyond audits, PeckShield offers monitoring tools:

**CoinHolmes**: Blockchain transaction tracking and analysis platform.

**AlertSystem**: Real-time monitoring for suspicious activities.

**DeFiHub**: Analytics and security insights for DeFi protocols.

**Security Scores**: Ongoing security ratings for protocols.

These tools provide continuous security beyond one-time audits.

## Lux Expertise

PeckShield has experience auditing protocols across all major blockchain networks including Lux:

- Lux LUExchange-Chain smart contracts
- Subnet-specific implementations
- Cross-chain bridge security
- DeFi protocols on Lux
- NFT and gaming projects
- Infrastructure and tooling

## Access Through Areta Marketplace

Lux projects can engage PeckShield through the [Areta Audit Marketplace](https://areta.market/lux):

- **Rapid Response**: Submit request and get quotes within 48 hours
- **Competitive Proposals**: Compare PeckShield with other leading firms
- **Clear Pricing**: Transparent costs without hidden fees
- **Subsidy Opportunities**: Eligible for up to $10k audit cashback
- **Streamlined Process**: Faster than traditional direct engagement
- **Lux-Focused**: Marketplace built for Lux ecosystem

## Audit Focus Areas

**DeFi Protocols**: All DeFi categories including DEXs, lending, derivatives, and yield.

**NFT & Gaming**: NFT marketplaces, game contracts, and metaverse infrastructure.

**Bridges & Interoperability**: Cross-chain bridges and messaging protocols.

**Infrastructure**: Layer 1/2 protocols, consensus mechanisms, and core infrastructure.

**Token Economics**: Token contracts, vesting, and distribution mechanisms.

**Governance**: DAO governance systems and voting mechanisms.

## Why Choose PeckShield

**Extensive Experience**: One of the most prolific audit firms with 1000+ audits completed.

**Fast Turnaround**: Known for efficient audit processes and quick delivery.

**Comprehensive Coverage**: Experience across all protocol types and blockchain networks.

**Real-Time Monitoring**: Ongoing security monitoring beyond one-time audits.

**Incident Response**: Rapid response capability for security emergencies.

**Research Leadership**: Regular security research and threat intelligence.

**Global Reach**: Serving projects worldwide with multilingual support.

## Public Security Contributions

PeckShield actively contributes to ecosystem security:

- Regular security blog posts and advisories
- Public incident response and analysis
- Vulnerability disclosures and reports
- Security threat intelligence sharing
- Community education on security best practices

## Pricing

PeckShield offers competitive pricing:

- Tiered pricing based on project size and complexity
- Fast-track options for urgent audits
- Volume discounts for multiple audits
- Flexible engagement models

Contact via Areta marketplace or directly for detailed proposals.

## Getting Started

To engage PeckShield:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit audit request with project details
   - Receive competitive quote from PeckShield
   - Access potential subsidies and streamlined process

2. **Direct Contact**:
   - Visit [peckshield.com](https://peckshield.com/)
   - Submit audit inquiry
   - Discuss scope and requirements
   - Receive audit proposal

## Deliverables

PeckShield provides:

- **Comprehensive Audit Report**: Detailed findings with severity classifications
- **Executive Summary**: High-level overview for stakeholders
- **Remediation Recommendations**: Specific guidance for fixing issues
- **Re-Audit Report**: Verification of fixes
- **Security Badge**: Post-audit security badge
- **Optional Monitoring**: Ongoing security monitoring services

## Conclusion

PeckShield is a leading blockchain security firm with one of the most extensive audit portfolios in the industry. With experience auditing 1000+ projects across all major blockchains including Lux, PeckShield provides comprehensive security services combining thorough audits with real-time monitoring and incident response capabilities. Available through the Areta Audit Marketplace for streamlined access and potential subsidies, PeckShield's combination of extensive experience, fast turnaround times, and ongoing security support makes them a trusted choice for Lux projects of all sizes seeking to launch securely.



# Pharaoh (/integrations/pharaoh)

---
title: Pharaoh
category: DeFi
available: ["LUExchange-Chain"]
description: "Pharaoh is a decentralized exchange offering advanced liquidity solutions and trading features on Lux."
logo: /images/pharaoh.png
developer: Pharaoh
website: https://pharaoh.exchange
documentation: https://pharaoh.exchange
---

## Overview

Pharaoh is a decentralized exchange platform deployed on Lux's LUExchange-Chain, providing advanced liquidity solutions and efficient trading mechanisms. The platform aims to deliver a comprehensive DeFi trading experience with innovative features and competitive rates for the Lux ecosystem.

## Features

- **Advanced Trading**: Sophisticated token swapping with optimized execution.
- **Liquidity Management**: Efficient liquidity pools with flexible participation options.
- **Yield Farming**: Earn rewards through liquidity provision and staking.
- **Multi-Asset Support**: Trade a wide range of tokens within the Lux ecosystem.
- **Optimized Performance**: Leverage Lux's fast transaction speeds and low costs.
- **User-Friendly Interface**: Intuitive design for seamless trading experience.

## Getting Started

To begin using Pharaoh:

1. **Access Platform**: Visit [Pharaoh](https://pharaoh.exchange).
2. **Connect Wallet**: Link your Web3 wallet and ensure you have LUX for transaction fees.
3. **Start Trading**: 
   - Choose tokens for swapping
   - Review pricing and slippage settings
   - Execute trades with confidence
4. **Explore Liquidity Options**: Provide liquidity to earn trading fees and additional rewards.

## Documentation

For detailed information and guides, visit the [Pharaoh platform](https://pharaoh.exchange).

## Use Cases

Pharaoh serves various DeFi needs:

- **Token Trading**: Execute efficient swaps with competitive rates and minimal slippage.
- **Liquidity Provision**: Earn passive income by providing liquidity to pools.
- **Yield Strategies**: Participate in farming opportunities for enhanced returns.
- **Portfolio Management**: Access diverse tokens for balanced portfolio allocation.

## Conclusion

Pharaoh brings advanced DEX functionality to Lux's LUExchange-Chain, offering traders and liquidity providers a robust platform for DeFi activities. With its focus on efficiency, user experience, and innovative features, Pharaoh contributes to the growing DeFi landscape on Lux.



# Pocket Network (/integrations/pocket-network)

---
title: Pocket Network
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: "Pocket Network is a decentralized RPC provider offering reliable, censorship-resistant access to blockchain networks."
logo: /images/pocket.png
developer: Pocket Network
website: https://www.pokt.network/
documentation: https://docs.pokt.network/
---

## Overview

Pocket Network is a decentralized infrastructure protocol that provides reliable, censorship-resistant RPC (Remote Procedure Call) services for blockchain networks. By utilizing a distributed network of node operators, Pocket Network ensures high availability, redundancy, and geographic diversity for accessing blockchain data, making it an ideal solution for developers building decentralized applications.

## Features

- **Decentralized Infrastructure**: Distributed network of thousands of independent node operators ensures no single point of failure.
- **Multi-Chain Support**: Access to multiple blockchain networks including Ethereum, Lux, and many others.
- **High Availability**: Redundant node infrastructure provides reliable uptime and performance.
- **Censorship-Resistant**: Decentralized architecture prevents any single entity from controlling or censoring access.
- **Cost-Effective**: Competitive pricing through a decentralized marketplace of node operators.
- **Load Balancing**: Automatic routing to the best available nodes for optimal performance.
- **Native Token Economics**: POKT token incentivizes node operators to provide quality service.

## Documentation

For detailed integration guides and API references, visit the [Pocket Network Documentation](https://docs.pokt.network/).

## Use Cases

Pocket Network serves various blockchain infrastructure needs:

- **DApp Development**: Reliable RPC access for decentralized applications.
- **Infrastructure Redundancy**: Backup RPC provider for enhanced reliability.
- **Decentralized Access**: Censorship-resistant blockchain data access.
- **Multi-Chain Applications**: Single provider for accessing multiple blockchain networks.

## Conclusion

Pocket Network provides decentralized, reliable RPC infrastructure for blockchain applications on Lux, offering high availability and censorship resistance through its distributed network of node operators.



# Portable (/integrations/portable)

---
title: Portable
category: KYC / Identity Verification
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Portable provides portable identity verification enabling users to carry verified credentials across Web3 applications."
logo: /images/portable.png
developer: Portable
website: https://www.portable.io/
---

## Overview

Portable is an identity verification platform that enables users to carry their verified identity credentials across multiple Web3 applications. By making KYC portable, Portable reduces verification friction for users while ensuring applications can meet compliance requirements efficiently.

## Features

- **Portable Credentials**: Carry verified identity across applications
- **One-Time Verification**: Complete KYC once, use everywhere
- **Compliance Framework**: Meet regulatory requirements efficiently
- **User-Controlled Data**: Users maintain control of their credentials
- **Easy Integration**: Simple APIs and SDKs for developers
- **Privacy Options**: Selective disclosure of identity attributes

## Getting Started

To integrate Portable:

1. **Sign Up**: Create account at [Portable](https://www.portable.io/)
2. **API Integration**: Access Portable APIs for verification
3. **Configure Flow**: Set up verification requirements
4. **User Experience**: Implement user-facing verification flow
5. **Verify Users**: Begin accepting portable credentials

## Use Cases

- **Streamlined Onboarding**: Reduce KYC friction for new users
- **Cross-Platform Identity**: Accept verified credentials from other platforms
- **Regulatory Compliance**: Meet KYC requirements efficiently
- **Repeat Users**: Seamless experience for verified returning users

## Conclusion

Portable streamlines identity verification for Lux applications, enabling users to carry their verified credentials and reducing onboarding friction while maintaining compliance.


# Privy (/integrations/privy)

---
title: Privy
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Spin up embedded wallets and beautiful authentication flows for all users."
logo: /images/privy.png
developer: Privy
website: https://privy.io/
documentation: https://docs.privy.io/
---

## What is Privy?
Privy is a simple tool to easily onboard all your users to web3, regardless of whether they already have a wallet, across mobile and desktop.

## Terminology
Before we dive into the guide, let's first understand the terminology.


| Term | Meaning |
| -------- | ------- |
| Social Login | Social Login is a form of single sign-on (SSO) that allows users to log into a third-party website or app using their existing credentials from a social media platform, such as Google, X (formerly Twitter), or Apple. Instead of creating a new username and password, users can authenticate themselves through their social media accounts, streamlining the login process. |
| Magic Link | A Magic Link is a form of passwordless authentication where users can log into an application or website by clicking a unique, time-sensitive link sent to their email address. This method eliminates the need for a traditional username and password combination, making the login process simpler and more user-friendly. |
| Next.js  | Next.js’ Pages Router is a full-stack React framework. It’s versatile and lets you create React apps of any size—from a mostly static blog to a complex dynamic application. |


## Prerequisites and Recommended Knowledge

- Privy account
- Basic understanding of EVM, and transaction data
- Basic understanding of frontend development

## Preparation

### Create Application and Retrieve API Keys

- Log in to [Privy Dashboard](https://dashboard.privy.io/)
- Click on `New App` on the Applications page.
- Click on the Settings button on the left pane. Under the Basic tab, you'll find the API keys.

### Start a New React Project with Next.js

To create a new Next.js project, run in your terminal:

```bash
npx create-next-app@latest
```

### Install Dependencies

After the React project is created, we need to install some dependencies: to use Privy (its own package), to add a custom chain, to create and use an HTTP client (viem), and to include utilities (ethers).

```bash
npm install @privy-io/react-auth@latest
npm i viem@latest
npm i ethers@latest
```

### Define Your Lux L1

In this guide, we are using the `Echo L1` as an example Lux L1. However, you can use any Lux L1 that has a public RPC URL. If the L1 has an explorer page, you can see better what is happening, but it is not required.

```typescript
export const echo = defineChain({
  id: 173750,
  name: 'Echo L1',
  network: 'echo',
  nativeCurrency: {
    decimals: 18,
    name: 'Ech',
    symbol: 'ECH',
  },
  rpcUrls: {
    default: {
      http: ['https://subnets.lux.network/echo/testnet/rpc']
    },
  },
  blockExplorers: {
    default: {name: 'Explorer', url: 'https://subnets-test.lux.network/echo'},
  },
});
```

### Import Privy into Your App 

After the React project is created, navigate to `page.tsx`. Inside the `Home` function, wrap your content with `PrivyProvider`.

```typescript title="page.tsx"
export default function Home() {

  return (
    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        appearance: {
          theme: 'dark',
          accentColor: '#e84242',
          logo: 'https://your-logo-url',
        },
        embeddedWallets: {
          createOnLogin: 'users-without-wallets',
        },
        defaultChain: echo,
        supportedChains: [echo],
        loginMethods: ['email', 'wallet', 'google', 'apple']
      }}
    >
      { content }
    </PrivyProvider>
  );

}
```

## Walkthrough

So far in the guide, we have installed the necessary dependencies, created our Privy application, and obtained our API key. Now, we are ready to use Privy.

Here is our walkthrough:

- We will create a simple login flow.
- We will create a welcome page for users who have logged in, showing their embedded wallet address and balance.
- We will trigger a test transfer of the `ECH` token via Privy.

### Login Flow

To onboard your users into your application, you just need to know the following hooks:

```typescript
const { ready, authenticated } = usePrivy();
const { login } = useLogin();
```

It's really that simple!

- `ready`: Checks whether the `PrivyProvider` is `ready` to be used.
- `authenticated`: Returns `true` if the user is `authenticated`, `false` otherwise.
- `login`: Opens the Privy login modal and prompts the user to log in.

```typescript
<button onClick={login}>Login via Privy</button>
```

We've only added a button to trigger `login` function, and Privy handles the rest.


When we click on the `Login via Privy` button, this modal appears.


You can choose any login method to log in. We’ve already defined these options in the `PrivyProvider` when we wrapped our content.

### Welcome Page

After checking whether the user is authenticated or not, we display the following information to the user who has logged in.


As you can see, Privy has generated an embedded wallet for our user. We’ve displayed the following properties on the screen: Privy ID, embedded wallet address, and embedded wallet balance.

```typescript
<span>{user.id}</span>
<span>{user.wallet.address}</span>
<span>{balance} ECH</span>
```

We’ve used the user object of Privy to retrieve the user ID and wallet address. To fetch the user’s balance, we need to create an HTTP client for our Lux L1, which we’ve already defined earlier.

```typescript
const client = createPublicClient({
    chain: echo,
    transport: http(),
});
// get native asset balance
client.getBalance({
    address: address,
}).then(balance => {
    setBalance(ethers.formatEther(balance));
});
```

We can allow users to log out using the following hook:

```typescript
const { logout } = useLogout();
```

### Fund the New Wallet Using the Faucet

We’ve funded the new wallet that was generated for our user with some ECH tokens from the [Echo AWM Testnet Faucet](https://test.core.app/tools/testnet-faucet/?lux-l1=echo&token=echo).

After the ECH tokens were sent, our balance updated accordingly.


### Send Test Transfer via Privy

Now that we have a balance, we can send some ECH tokens to another recipient via Privy to test Privy's `sendTransaction` flow. Privy provides the following hook for this:

```typescript
const { sendTransaction } = useSendTransaction();
```

We’ve already added the following button to trigger the `transfer` function, which will, in turn, trigger the `sendTransaction` function provided by Privy.

```typescript
<button onClick={transfer}>Send Test Transfer via Privy</button>
```

We have built a simple transaction that sends some ECH tokens to another recipient.


```typescript
const transfer = () => {
    if (authenticated === false || address === undefined) {
        return;
    }
    let receiver = "0x..."; // receiver address
    sendTransaction({
        "value": ethers.parseUnits("0.01", "ether"),
        "to": receiver, // destination address
        "from": address, // logged in user's embedded wallet address
    }).catch(() => {
        // handle err 
    });
}
```

When we click on the `Send Test Transfer via Privy` button, this modal appears. Users can see the following details related to the transaction.


## Conclusion

What we achieved is the creation of a simple React project that integrates Privy. Our application can now easily onboard new users to our Web3 application without needing them to install a Web3 wallet extension, regardless of which chain they are on


# Proof of Play vRNG (/integrations/proof-of-play)

---
title: Proof of Play vRNG
category: VRF
available: ["LUExchange-Chain"]
description: "A hyper-optimized, secure, onchain verified random number generator (vRNG). Battle-tested at scale, faster, more reliable, and more affordable than alternatives."
logo: /images/proofofplay.jpg
developer: Proof of Play
website: https://proofofplay.com/
documentation: https://docs.proofofplay.com/
---

## Overview

Proof of Play vRNG (Verified Random Number Generator) is a hyper-optimized, secure, onchain random number generation solution that has been battle-tested at scale with over 485 million transactions. The platform provides a faster, more reliable, and more affordable alternative to traditional VRF solutions, enabling developers to build high-performance decentralized applications and games with verifiable randomness. With exceptional white-glove engineering support, seamless integration capabilities, and proven reliability across the Ethereum ecosystem, Proof of Play vRNG delivers the speed, security, and cost-efficiency needed for applications requiring unpredictable outcomes, from blockchain games and NFTs to random assignment systems and consensus mechanisms.



# Pyth Network (/integrations/pyth)

---
title: Pyth Network
category: Oracles
available: ["LUExchange-Chain"]
description: Pyth Network is a decentralized oracle solution that provides high-fidelity data for DeFi applications.
logo: /images/pyth.png
developer: Pyth Network
website: https://pyth.network/
documentation: https://docs.pyth.network/
---

## Overview

Pyth Network is a decentralized oracle solution designed to provide high-fidelity data for decentralized finance (DeFi) applications. By leveraging a network of data providers and validators, Pyth Network delivers accurate and reliable real-world data, crucial for executing smart contracts and ensuring the integrity of DeFi platforms.

## Features

- **High-Fidelity Data**: Pyth Network aggregates and validates data from a diverse set of sources to ensure accuracy and reliability.
- **Decentralized Network**: Operates as a decentralized oracle network, reducing reliance on any single data source and increasing trustworthiness.
- **Real-Time Data**: Provides up-to-date data feeds for various assets, including cryptocurrencies, commodities, and equities.
- **Integration with DeFi**: Seamlessly integrates with DeFi applications, offering essential data for trading, lending, and other financial activities.

## Getting Started

To integrate Pyth Network into your application:

1. **Visit the Pyth Network Website**: Explore the [Pyth Network website](https://pyth.network/) to understand its offerings and capabilities.
2. **Access the Documentation**: Refer to the [Pyth Network Documentation](https://docs.pyth.network/) for detailed guides on integration, data feeds, and API usage.
3. **Integrate Data Feeds**: Use the provided APIs to integrate Pyth Network’s data feeds into your smart contracts and DeFi applications.
4. **Test and Deploy**: Test the integration in a development environment to ensure data accuracy and application functionality before deploying to production.

## Documentation

For detailed integration instructions, data feed options, and API references, visit the [Pyth Network Documentation](https://docs.pyth.network/).

## Use Cases

Pyth Network is ideal for applications that require accurate and timely real-world data:

- **Decentralized Finance (DeFi)**: Utilize Pyth Network’s data feeds for trading, lending, and other financial operations in DeFi platforms.
- **Risk Management**: Integrate real-time data into risk management systems for better decision-making and risk assessment.
- **Market Analytics**: Provide accurate market data for analysis and forecasting in various financial and trading applications.

## Conclusion

Pyth Network offers a robust decentralized oracle solution that provides high-fidelity data essential for DeFi applications. With its real-time data feeds and decentralized nature, Pyth Network ensures the accuracy and reliability of data used in smart contracts and financial operations. Whether you are building a DeFi platform or integrating market data, Pyth Network delivers the tools and resources needed for successful data management and application development.



# QuickNode (/integrations/quicknode)

---
title: QuickNode
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: QuickNode is a blockchain developer platform that provides a suite of APIs and tools for building and scaling blockchain applications.
logo: /images/quicknode.png
developer: QuickNode
website: https://www.quicknode.com/
documentation: https://www.quicknode.com/docs
---

## Overview

QuickNode is a blockchain developer platform that offers a comprehensive suite of APIs and tools for building and scaling blockchain applications. It provides developers with reliable and scalable infrastructure to interact with blockchain networks, enabling efficient and effective development of decentralized applications.

## Features

- **Scalable APIs**: Access a range of APIs designed to handle high-throughput and low-latency requirements for blockchain interactions.
- **Multi-Chain Support**: Connect with various blockchain networks, including Ethereum, Binance Smart Chain, and others, through a unified platform.
- **Developer Tools**: Utilize advanced tools and services for building, monitoring, and optimizing blockchain applications.
- **Reliable Infrastructure**: Benefit from QuickNode’s high-performance infrastructure, ensuring reliable and consistent access to blockchain networks.
- **Analytics and Monitoring**: Track and analyze blockchain interactions with built-in monitoring and analytics tools.

## Getting Started

To start using QuickNode:

1. **Visit the QuickNode Website**: Explore the [QuickNode website](https://www.quicknode.com/) to understand its features and offerings.
2. **Access the Documentation**: Refer to the [QuickNode Documentation](https://www.quicknode.com/docs) for detailed guides on setting up and using QuickNode’s APIs and tools.
3. **Create an Account**: Sign up for a QuickNode account to gain access to API keys and start integrating blockchain functionality into your applications.
4. **Integrate APIs**: Use the provided APIs to interact with your desired blockchain networks, and implement features such as data retrieval, transaction submission, and more.
5. **Monitor and Optimize**: Utilize QuickNode’s monitoring and analytics tools to track performance and optimize your blockchain applications.

## Documentation

For detailed integration instructions, API references, and setup guides, visit the [QuickNode Documentation](https://www.quicknode.com/docs).

## Use Cases

QuickNode is suitable for various blockchain development scenarios:

- **Decentralized Applications (dApps)**: Build and scale dApps with QuickNode’s APIs and tools for efficient blockchain interactions.
- **Blockchain Analytics**: Use QuickNode’s monitoring and analytics tools to gain insights into blockchain data and application performance.
- **Smart Contract Development**: Develop, test, and deploy smart contracts with reliable infrastructure and scalable API access.
- **Transaction Management**: Manage and monitor blockchain transactions with high performance and low latency.

## Conclusion

QuickNode provides a powerful and flexible blockchain developer platform, offering a suite of APIs and tools for building and scaling blockchain applications. With its scalable infrastructure, multi-chain support, and advanced developer tools, QuickNode ensures efficient and effective blockchain development. Whether you’re creating dApps, analyzing blockchain data, or managing transactions, QuickNode delivers the resources and capabilities needed for success.



# Rain (/integrations/rain)

---
title: Rain
category: Payments
available: ["LUExchange-Chain"]
description: Rain is a global card issuing platform enabling partners to launch fully integrated credit and debit card programs with direct wallet spending, supporting fintechs globally as a Visa principal member.
logo: /images/rain.svg
developer: Rain
website: https://www.rain.xyz/
documentation: https://www.rain.xyz/resources
---

## Overview

Rain is a pioneering global card issuing and payment infrastructure platform that enables businesses to launch fully integrated credit and debit card programs powered by digital assets and stablecoins. As a principal member of the Visa network, Rain can sponsor card programs end-to-end without relying on bank partners, providing unprecedented flexibility and control for fintech platforms, exchanges, wallets, and financial applications.

Rain's cards are fully functional with Google Pay and Apple Pay, work anywhere Visa is accepted worldwide (over 150 million merchants), and uniquely support non-custodial spending, allowing users to spend directly from their self-custodial wallets. This infrastructure supports diverse use cases including cross-border payments, remittances, cryptocurrency exchanges, neobanks, and Web3 applications globally.

## Features

- **Visa Principal Membership**: Direct Visa network sponsorship enabling end-to-end card program ownership without bank dependencies.
- **Global Card Issuance**: Issue virtual and physical debit and credit cards accepted at 150+ million merchants worldwide.
- **Digital Wallet Integration**: Full support for Apple Pay and Google Pay for mobile-first payment experiences.
- **Non-Custodial Spending**: Unique capability for users to spend directly from self-custodial wallets without custody intermediaries.
- **Multi-Currency Support**: Support for stablecoins, cryptocurrencies, and traditional fiat currencies.
- **Stablecoin-Native**: Purpose-built for stablecoin-powered transactions and digital dollar spending.
- **Cross-Border Payments**: Enable instant, low-cost international payments and remittances.
- **White-Label Solutions**: Fully customizable card programs branded for your business.
- **Modular Platform**: Choose specific components (cards, accounts, money-in, money-out) based on needs.
- **Real-Time Settlement**: Instant settlement of transactions on blockchain networks.
- **Compliance Infrastructure**: Built-in KYC/AML and regulatory compliance tools.
- **API-First Design**: Comprehensive APIs for seamless integration into any platform.
- **Multi-Blockchain Support**: Compatible with multiple blockchain networks including Lux.
- **Instant Card Issuance**: Generate virtual cards instantly for immediate use.

## Platform Capabilities

### Cards

Issue globally-accepted payment cards linked to users' digital asset balances:

- **Virtual Cards**: Instant issuance of virtual cards for online and mobile payments
- **Physical Cards**: Branded physical cards mailed to users globally
- **Credit Cards**: Full credit card programs with spending limits and billing cycles
- **Debit Cards**: Direct debit from user balances with real-time settlement
- **Prepaid Cards**: Preloaded cards for controlled spending
- **Multi-Currency**: Cards supporting multiple currencies and automatic conversion

### Money-In (On-Ramp)

Enable users to deposit funds and convert to digital assets:

- **Fiat Deposits**: Bank transfers, card deposits, and local payment methods
- **Crypto Purchases**: Buy cryptocurrencies and stablecoins with fiat
- **Instant Conversion**: Real-time conversion from local currencies to stablecoins
- **Global Payment Methods**: Support for payment methods in 150+ countries
- **Low Fees**: Competitive pricing for on-ramp transactions

### Accounts (Embedded Wallets)

Integrate secure digital asset accounts into applications:

- **Embedded Wallets**: Secure wallets integrated directly into partner applications
- **Custodial Options**: Managed custody for simplified user experience
- **Self-Custodial Support**: Non-custodial wallets for users maintaining control
- **Multi-Asset**: Support for multiple cryptocurrencies and stablecoins
- **Account Management**: Tools for managing balances, transactions, and settings

### Money-Out (Off-Ramp)

Facilitate withdrawals and cross-border transfers:

- **Fiat Withdrawals**: Convert digital assets to local currency and withdraw to banks
- **Cross-Border Payments**: Send payments internationally with low fees
- **Stablecoin Transfers**: Send stablecoins globally instantly
- **Local Currency Conversion**: Convert to any supported currency for withdrawal
- **Multiple Destinations**: Support for bank transfers, mobile money, and other methods

## Getting Started

To integrate Rain into your platform:

1. **Partnership Discussion**: Contact Rain's team to discuss your card program requirements and use case.

2. **Program Design**: Work with Rain to design your card program:
   - Define card types (credit, debit, virtual, physical)
   - Choose currencies and digital assets to support
   - Determine custodial vs non-custodial approach
   - Select which Rain modules to integrate (cards, accounts, money-in, money-out)
   - Design branded card appearance and user experience

3. **Compliance Setup**: Establish necessary compliance infrastructure:
   - Complete Rain's partner onboarding and due diligence
   - Set up KYC/AML processes for your users
   - Navigate regulatory requirements for your markets
   - Establish spending limits and controls

4. **Technical Integration**: Implement Rain's platform:
   - Integrate Rain's APIs for card issuance and management
   - Connect wallet infrastructure (custodial or non-custodial)
   - Implement user interfaces for card management
   - Set up webhooks for transaction notifications
   - Test in sandbox environment

5. **Card Program Launch**: Go live with your Rain-powered card program:
   - Issue cards to your users
   - Enable spending at merchants worldwide
   - Process transactions in real-time
   - Provide customer support with Rain's assistance

## Lux Support

Rain's multi-blockchain infrastructure supports Lux LUExchange-Chain, enabling card programs powered by LUX and Lux-based stablecoins. Notably, Rain partnered with Wyoming and Lux to launch the Frontier Stable Token (FRNT), Wyoming's state-issued, dollar-pegged stablecoin, enabling real-world spending through Rain-issued Visa cards. This demonstrates Rain's commitment to bringing Lux assets into everyday commerce at 150+ million merchants globally.

## Use Cases

Rain's infrastructure serves diverse payment use cases:

**Cryptocurrency Exchanges**: Enable exchange users to spend their crypto holdings at any merchant accepting Visa.

**Neobanks**: Launch full-featured banking services with card programs without traditional banking infrastructure.

**Web3 Wallets**: Add card spending directly from self-custodial wallets for seamless crypto-to-fiat usage.

**Cross-Border Remittances**: Facilitate low-cost international money transfers using stablecoins and local currency conversion.

**Fintech Applications**: Embed payment cards into any fintech app or platform.

**DeFi Platforms**: Bridge DeFi yields and holdings to real-world spending.

**Gaming Platforms**: Enable gamers to spend in-game earnings in the real world.

**Payroll Solutions**: Issue payroll cards for instant wage access and spending.

## Non-Custodial Innovation

Rain's unique non-custodial card capability represents a breakthrough:

- **User Control**: Users maintain custody of assets in self-custodial wallets
- **Direct Spending**: No need to deposit to custodial accounts before spending
- **Real-Time Settlement**: Transactions settle directly from user wallets
- **Security**: Users never surrender custody to third parties
- **Web3 Native**: True Web3 payment experience maintaining decentralization principles

This innovation is particularly valuable for Web3-native applications where user custody is paramount.

## Visa Principal Membership

Rain's status as a Visa principal member provides significant advantages:

- **Independent Operation**: No reliance on sponsoring banks or third-party BINs
- **Full Control**: Complete ownership and control of card programs
- **Faster Implementation**: Direct relationship with Visa accelerates deployment
- **Flexibility**: Greater flexibility in program design and features
- **Stability**: Not dependent on bank partner relationships or changes
- **Global Reach**: Access to Visa's global acceptance network

## Compliance and Regulation

Rain maintains comprehensive compliance infrastructure:

- **Money Transmitter Licenses**: Licensed in multiple jurisdictions for money transmission
- **Visa Compliance**: Full compliance with Visa network rules and regulations
- **KYC/AML**: Integrated identity verification and anti-money laundering screening
- **Transaction Monitoring**: Real-time monitoring for fraudulent or suspicious activity
- **Data Security**: PCI DSS compliant infrastructure for secure payment data handling
- **Regulatory Expertise**: Experienced team navigating global financial regulations

## Partner Benefits

**Bank-Free Card Programs**: Launch card programs without needing bank sponsors.

**Global Reach**: Immediate access to 150+ million merchants worldwide.

**Fast Time-to-Market**: Modular platform enables quick deployment of card programs.

**Brand Control**: Fully white-labeled solutions matching your brand experience.

**Flexible Custody**: Support both custodial and non-custodial models.

**Multi-Asset**: Accept payments in stablecoins, crypto, and fiat.

**Comprehensive APIs**: Developer-friendly integration with extensive documentation.

**Revenue Sharing**: Earn interchange revenue from card transactions.

## Technology Infrastructure

Rain provides enterprise-grade technology:

- **Card Issuance APIs**: Instant virtual card generation and physical card ordering
- **Transaction Processing**: Real-time authorization and settlement
- **Wallet Integration**: Connect custodial and non-custodial wallets
- **Multi-Chain Support**: Compatibility with multiple blockchain networks
- **Webhooks**: Real-time notifications for all card events
- **Admin Dashboard**: Portal for managing cards, users, and transactions
- **Fraud Prevention**: Machine learning-based fraud detection
- **Reporting**: Comprehensive transaction reporting and analytics

## Pricing

Rain offers partnership-based pricing:

- **Setup Fees**: Initial integration and card program setup costs
- **Card Issuance Fees**: Fees for virtual and physical card issuance
- **Transaction Fees**: Percentage or fixed fees on card transactions
- **Interchange Revenue**: Partners share in Visa interchange fees
- **Monthly Fees**: Platform access and maintenance fees
- **Custom Pricing**: Tailored pricing for high-volume partners

Contact Rain for detailed pricing based on your specific program requirements.

## Global Coverage

Rain supports card programs in 150+ countries with:

- **Multi-Currency**: Support for major fiat currencies and stablecoins
- **Local Payment Methods**: On-ramp via local payment methods globally
- **Regional Compliance**: Compliance with regional regulations
- **Global Support**: 24/7 customer support for international users
- **Multi-Language**: Platform localization for key markets

## Conclusion

Rain is revolutionizing digital asset payments by making it possible for anyone to spend cryptocurrencies and stablecoins at any merchant accepting Visa worldwide. As a Visa principal member, Rain provides the infrastructure for fintechs, exchanges, wallets, and Web3 applications to launch fully-featured card programs without traditional banking dependencies. With support for Lux and unique capabilities like non-custodial spending, Rain bridges the gap between blockchain-based assets and real-world commerce. Whether you're building a neobank, cryptocurrency exchange, Web3 wallet, or any fintech application that needs payment cards, Rain provides the trusted, compliant, and flexible infrastructure to bring your vision to life and enable your users to spend their digital assets anywhere Visa is accepted.



# Ramp Network (/integrations/ramp-network)

---
title: Ramp Network
category: Fiat On-Ramp
available: ["LUExchange-Chain", "All Lux L1s"]
description: Ramp Network is a global provider of fiat-to-crypto on-ramp and off-ramp infrastructure, enabling users to purchase and sell cryptocurrencies directly within applications.
logo: /images/ramp-network.png
developer: Ramp Network
website: https://ramp.network/
documentation: https://docs.ramp.network/
---

## Overview

Ramp Network is a leading fiat-to-crypto infrastructure provider that enables users to purchase and sell cryptocurrencies directly within blockchain applications. With a focus on regulatory compliance and user experience, Ramp offers a seamless on-ramp and off-ramp solution that can be integrated into any application with minimal developer effort. Ramp supports multiple payment methods across 150+ countries and provides a customizable widget that can be tailored to match your application's design.

## Features

- **Global Coverage**: Available in 150+ countries with localized payment methods and support for multiple currencies.
- **Diverse Payment Options**: Bank transfers, credit/debit cards, Apple Pay, Google Pay, and region-specific payment methods.
- **Full Off-Ramp Solution**: Complete selling experience allowing users to convert crypto back to fiat with direct bank deposits.
- **Customizable Widget**: White-labeled solution that can be styled to match your application's branding.
- **Low Integration Effort**: Simple SDK integration requiring just a few lines of code.
- **Multi-Platform Support**: Web SDK, React SDK, and mobile SDKs for iOS and Android.
- **Robust Compliance**: Built-in KYC and AML processes that meet regulatory requirements across jurisdictions.
- **Competitive Fees**: Transparent fee structure with some of the lowest rates in the industry.
- **Advanced Developer Tools**: Webhooks, callbacks, and detailed documentation for seamless integration.
- **Advanced Purchase Flows**: Support for automatic purchases and recurring purchases.

## Getting Started

To integrate Ramp into your application:

1. **Create an Account**: Register on the [Ramp Developer Dashboard](https://app.ramp.com/sign-in) to get your API key.

2. **Install the SDK**: For web applications, add the Ramp SDK to your project:
   ```bash
   npm install @ramp-network/ramp-instant-sdk
   ```

3. **Initialize the On-Ramp Widget**: Implement the widget in your application:
   ```javascript
   import { RampInstantSDK } from '@ramp-network/ramp-instant-sdk';
   
   const ramp = new RampInstantSDK({
     hostAppName: 'Your App Name',
     hostLogoUrl: 'https://yourdomain.com/logo.png',
     swapAsset: 'LUX',
     swapAmount: '100000000000000000', // Optional, in wei
     userAddress: '0x...', // User's wallet address
     hostApiKey: 'YOUR_API_KEY',
     variant: 'auto', // or 'desktop', 'mobile', 'embedded'
     webhookStatusUrl: 'https://your-webhook-endpoint.com', // Optional
     defaultFlow: 'ONRAMP', // or 'OFFRAMP'
   });
   
   ramp.show();
   ```

4. **Implement Off-Ramp** (if needed):
   ```javascript
   import { RampInstantSDK } from '@ramp-network/ramp-instant-sdk';
   
   const ramp = new RampInstantSDK({
     hostAppName: 'Your App Name',
     hostLogoUrl: 'https://yourdomain.com/logo.png',
     swapAsset: 'LUX',
     userAddress: '0x...', // User's wallet address
     hostApiKey: 'YOUR_API_KEY',
     variant: 'auto',
     defaultFlow: 'OFFRAMP',
   });
   
   ramp.show();
   ```

5. **Handle Events**: Listen for purchase events:
   ```javascript
   ramp.on('PURCHASE_CREATED', (event) => {
     console.log(`User started purchase: ${event.purchase.id}`);
   });
   
   ramp.on('PURCHASE_SUCCESSFUL', (event) => {
     console.log(`Purchase successful: ${event.purchase.id}`);
   });
   
   ramp.on('WIDGET_CLOSE', () => {
     console.log('Widget closed');
   });
   ```

6. **Test in Sandbox**: Use the sandbox environment to test your integration before going live:
   ```javascript
   const ramp = new RampInstantSDK({
     // ...your configuration
     url: 'https://ri-widget-staging.firebaseapp.com/', // Use staging environment
   });
   ```

## Documentation

For comprehensive integration guides, API references, and webhook setup, visit the [Ramp Documentation](https://docs.ramp.network/).

## Use Cases

Ramp can enhance various blockchain applications:

**Crypto Wallets**: Enable users to purchase crypto directly within your wallet application and cash out to their bank accounts.

**DeFi Platforms**: Provide a seamless entry and exit point for users to acquire and liquidate tokens needed for DeFi protocols.

**NFT Marketplaces**: Allow direct purchase of NFTs with fiat, simplifying the user journey.

**Blockchain Games**: Let players purchase in-game tokens or assets without needing to understand crypto exchanges.

**Enterprise Solutions**: Offer a compliant on/off-ramp solution for corporate blockchain applications.

## Pricing

Ramp operates on a transaction fee model:

- **Standard Fee Range**: 0.49% to 2.9% per transaction, depending on payment method and region
- **Volume Discounts**: Available for applications with high transaction volumes
- **Revenue Sharing**: Partnership opportunities for qualified integrators
- **No Monthly Fees**: Pay only for processed transactions

For specific pricing details and potential custom arrangements, contact Ramp's sales team.

## Conclusion

Ramp Network provides a comprehensive fiat-to-crypto infrastructure solution that can significantly enhance user experience in blockchain applications. By handling the complex compliance, payment processing, and liquidity management, Ramp allows developers to focus on their core product while providing users with a seamless way to enter and exit the crypto ecosystem. With its competitive fees, extensive global coverage, and flexible integration options, Ramp is an ideal solution for any project looking to reduce friction in user onboarding and provide a complete crypto experience. 

# RD Technology (/integrations/rdtechnology)

---
title: RD Technology
category: Payments
available: ["LUExchange-Chain"]
description: RD Technology provides blockchain payment solutions and infrastructure for businesses to integrate cryptocurrency and digital asset payment capabilities.
logo: /images/rdtechnology.jpeg
developer: RD Technology
website: https://rd.group/
documentation: https://rd.group/products/wallet/enterprise-solution/
---

## Overview

RD Technology is a blockchain technology company specializing in payment solutions and infrastructure that enable businesses to integrate cryptocurrency and digital asset payment capabilities into their operations. By providing comprehensive tools and APIs, RD Technology makes it possible for businesses to accept, process, and manage digital currency payments while maintaining compliance and security standards.

The platform is designed to serve businesses looking to expand their payment options to include cryptocurrencies and stablecoins, providing the technical infrastructure and support needed for successful implementation.

## Features

- **Payment Infrastructure**: Comprehensive tools for cryptocurrency payment processing.
- **Multi-Currency Support**: Accept various cryptocurrencies and stablecoins.
- **Blockchain Integration**: Connect with multiple blockchain networks including Lux.
- **Payment Processing**: Handle payment authorization and settlement efficiently.
- **API Platform**: Developer-friendly APIs for custom integrations.
- **Security**: Enterprise-grade security for payment processing.
- **Compliance Tools**: Built-in compliance and regulatory features.
- **Transaction Management**: Tools for tracking and managing payments.
- **Settlement Options**: Flexible settlement in crypto or fiat.
- **Reporting**: Comprehensive transaction reporting and analytics.

## Getting Started

To integrate RD Technology:

1. **Contact RD Technology**: Reach out to discuss your payment infrastructure needs.

2. **Platform Assessment**: Determine integration requirements:
   - Payment volumes and currencies
   - Technical integration approach
   - Compliance requirements
   - Settlement preferences

3. **Implementation**: Integrate RD Technology's solutions:
   - Connect to payment APIs
   - Implement payment flows
   - Configure settlement options
   - Test in development environment

4. **Launch**: Go live with cryptocurrency payment capabilities.

## Lux Support

RD Technology's infrastructure supports Lux LUExchange-Chain, enabling businesses to accept and process payments using LUX and Lux-based assets with fast transactions and low fees.

## Use Cases

**Business Payments**: Accept cryptocurrency payments for products and services.

**Payment Processing**: Process digital currency payments at scale.

**Cross-Border**: Facilitate international payments using blockchain technology.

**E-Commerce**: Integrate crypto payments into online stores.

**B2B Transactions**: Enable business-to-business cryptocurrency payments.

**Financial Services**: Build fintech applications with crypto payment capabilities.

## Conclusion

RD Technology provides the blockchain payment infrastructure and tools that enable businesses to integrate cryptocurrency payment capabilities, supporting networks like Lux for fast, efficient digital asset transactions.



# Re (/integrations/re)

---
title: Re
category: Assets
available: ["LUExchange-Chain"]
description: "Re provides tokenized insurance and risk products, bringing traditional insurance mechanisms to blockchain infrastructure."
logo: /images/re.png
developer: Re
website: https://www.re.xyz/
documentation: https://docs.re.xyz/
---

## Overview

Re is pioneering the tokenization of insurance and risk products on blockchain. By bringing traditional insurance mechanisms on-chain, Re enables transparent, efficient, and accessible risk transfer products, allowing users to participate in insurance markets through tokenized instruments.

## Features

- **Tokenized Insurance**: Insurance products in tokenized form
- **Risk Markets**: Access to diversified risk transfer markets
- **Transparency**: On-chain transparency for insurance products
- **Yield Generation**: Earn yield through insurance capacity provision
- **Smart Contracts**: Automated claims and policy management
- **Decentralized Risk**: Participate in decentralized risk pools

## Getting Started

To use Re:

1. **Visit Re**: Access the [Re platform](https://www.re.xyz/)
2. **Explore Products**: Learn about available risk products
3. **Connect Wallet**: Connect your Web3 wallet
4. **Participate**: Provide capacity or purchase protection
5. **Manage**: Manage positions through the platform

## Documentation

For technical documentation, visit [Re Documentation](https://docs.re.xyz/).

## Use Cases

- **Insurance Capacity**: Provide capacity to insurance pools
- **Risk Protection**: Purchase on-chain risk protection
- **Yield Earning**: Earn yield from insurance premiums
- **Risk Diversification**: Diversify exposure across risk products

## Conclusion

Re brings insurance and risk products to Lux, enabling transparent, efficient participation in tokenized risk markets through blockchain infrastructure.


# Reactive Network (/integrations/reactive-network)

---
title: Reactive Network
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: "Reactive Network is a fully on-chain, EVM-compatible, events-driven if-this-then-that network for decentralized automation of on-chain workflows through enabling reactivity between contracts deployed either on the same or different chains."
logo: /images/Symbol_ColorBlack_H32.png
developer: PARSIQ
website: https://reactive.network/
documentation: https://dev.reactive.network
---

## Overview

Reactive Network is a fully on-chain, EVM-compatible, events-driven if-this-then-that network for decentralized automation of on-chain workflows through enabling reactivity between contracts deployed either on the same or different chains. Core purpose of Reactive is to enable more autonomous, self-sufficient and user friendly dApps.

## Features

- **Decentralized automation**: Web3’s first IFTTT infrastructure. Automate multi-chain workflows with event-driven logic – execute actions without compromising decentralization.
- **Cost-efficient Execution**: Offload heavy computations to Reactive’s parallelized EVM. Complex logic at minimal cost.
- **Inversion of Control**: RSCs invert the traditional execution model by allowing the contract itself to decide when to execute based on predefined events, eliminating the need for external triggers like bots or users.
- **DeFAI-Ready Infrastructure**: Create autonomous DeFi agents with on-chain data triggers and off-chain AI intelligence that trade, optimize, and adapt.

## Getting Started

To start using Reactive Network:

1. **Review Documentation**: Study the [Reactive Network Documentation](https://dev.reactive.network).
2. **Check out Reactive's [origins and destinations](https://dev.reactive.network/origins-and-destinations)**, along with their Callback Proxy addresses. 
3. **Connect to [Reactive Mainnet or Kopli Testnet](https://dev.reactive.network/reactive-mainnet)**.
4. **Explore what can be built**:
    - Hands-on [demonstrations](https://dev.reactive.network/demos) for the Reactive Network.
    - Clone the [GitHub](https://github.com/Reactive-Network/reactive-smart-contract-demos) project and start building.
5. **Learn more** about Reactive Smart Contracts in our [educational course](https://dev.reactive.network/education/introduction).

## Documentation

For comprehensive integration guides and technical details, visit the [Reactive Network Documentation](https://dev.reactive.network).

## Use Cases

Reactive Network supports a wide range of cross-chain automations:

- **Decentralized Trading Automation**: Automate gasless cross-chain swaps, enabling a frictionless P2P crypto trading experience.
- **Dynamic NFT Royalty System**: Enable real-time royalty adjustments, automate cross-chain transactions, and ensure transparent, fair revenue distribution for creators, buyers, and marketplaces.
- **Flash Profit Extractor**: Automate token swaps, dynamic pricing, and real-time price tracking, making DeFi arbitrage accessible and efficient.
- **Cross-Chain Lending**: Borrow assets across multiple blockchains.

## Conclusion

Reactive Network is an EVM-compatible execution layer that allows developers to create dApps using reactive contracts. These contracts differ from traditional smart contracts by using inversion-of-control for the transaction lifecycle, driven by data flows across blockchains rather than user input. Put simply - fully onchain, events driven if-this-then-that network for decentralized automation or simplification of workflows. Whether you're a seasoned or new blockchain developer, all you need is knowledge of Solidity. Reactive is not just a toolkit — it’s a new execution paradigm for Lux and beyond.


# Reap Protocol (/integrations/reap-protocol)

---
title: Reap Protocol
category: x402
available: ["LUExchange-Chain"]
description:  Reap Protocol gives AI Agent's the power to search real products, verify inventory, and purchase autonomously. Reap bridges Web2 shops with Web3 settlement so agents can operate in the real economy — safely, verifiably, and on-chain.
logo: /images/reap-protocol.png
developer: April Labs
website: https://protocol.reap.deals/
documentation: https://docs.reap.deals/
---

## Overview

Reap Protocol gives AI Agents the power to search real products, verify inventory, and purchase autonomously. Reap bridges Web2 shops with Web3 settlement so agents can operate in the real economy — safely, verifiably, and on-chain.  We provide both Python and Typescript SDK's.

## Features

- **Product Search → On-Chain Inventory**: Agents can index any Web2 product with a single call.
- **x402 Negotiation Engine**: Turns HTTP into a payment-capable negotiation loop.
- **Agentic Cart**: Identity, stock, and settlement in a single atomic mission.
- **Self-Custody by Design**: The agent controls its wallet; Reap handles the complexity.

## Getting Started

## Installation
```bash
npm install @reap-protocol/sdk ethers axios
```

This example demonstrates the full Agentic Commerce Loop: Identity -> Discovery -> Settlement.

### 1. Setup

If using TypeScript, ensure your tsconfig.json targets ES2020 or higher.

### 2. The Agent Code (agent.ts)
```typescript
import { ReapClient } from "@reap-protocol/sdk";

// Load your private key securely
const PRIVATE_KEY = process.env.MY_WALLET_KEY || "";

async function main() {
  // 1. Initialize the Agent
  // (Points to official middleware by default)
  const client = new ReapClient(PRIVATE_KEY);
  console.log("🤖 Agent Online");

  try {
    // 2. Identity (One-time setup)
    // Registers your wallet as an authorized Agent on the Protocol
    console.log("🆔 Checking Identity...");
    await client.registerIdentity();

    // 3. JIT Stocking (Discovery)
    // Searches Web2 (Reap Deals), registers items on-chain, and returns inventory
    console.log("📦 Stocking Shelf with 'Gaming Laptop'...");
    const result = await client.stockShelf("Gaming Laptop");
    
    const inventory = result.items;
    console.log(`   🔍 Found ${inventory.length} items on-chain.`);

    if (inventory.length > 0) {
        // 4. Decision Logic
        // Example: Pick the first available item
        const target = inventory[0];
        console.log(`   🎯 Selected: ${target.name} ($${target.price})`);
        console.log(`      ID: ${target.id}`);

        // 5. Agentic Cart (Settlement)
        // Automatically approves USDC and executes the atomic purchase
        console.log("💸 Buying Item...");
        const receipt = await client.buyProduct(target.id);
        
        if (receipt) {
            console.log(`🎉 SUCCESS! Transaction Hash: ${receipt.hash}`);
        }
    } else {
        console.log("❌ No items found.");
    }

  } catch (e: any) {
    console.error("❌ Error:", e.message);
  }
}

main();
```

### 3. Run It
```bash
# Install execution tools if you haven't already
npm install --save-dev ts-node typescript @types/node

# Run
npx ts-node agent.ts
```

## Configuration

You can override defaults for custom RPCs or self-hosted middleware.
```typescript
const client = new ReapClient(
  "YOUR_PRIVATE_KEY",
  "https://lux-testnet.g.alchemy.com/v2/YOUR_KEY", // Custom RPC
  "https://lux.api.reap.deals"    // Middleware URL
);
```

## Documentation

For integration guides and API documentation, visit the [Reap Protocol Documentation](https://docs.reap.deals/).

## Use Cases

Reap Protocol serves various agentic commerce needs:

- **Agentic Commerce**: Enable agents to conduct onchain commerce
- **x402 payments**: Pay for x402 resources and goods
- **On-chain shopping**: Create on-chain shopping flows

## Conclusion

Reap Protocol brings agentic commerce to Lux, giving AI Agents the power to search real products, verify inventory, and purchase autonomously.


# RedStone Oracles (/integrations/redstone-oracles)

---
title: RedStone Oracles
category: Data Feeds
available: ["LUExchange-Chain"]
description: RedStone is a modular, gas-optimized oracle providing diverse and reliable price feeds for dApps.
logo: /images/RedStone.png
developer: RedStone Oracles
website: https://redstone.finance/
documentation: https://docs.redstone.finance/docs/introduction
---

## Overview

RedStone Oracles is a fast-growing modular oracle solution designed to provide gas-optimized and reliable price feeds across over 50 blockchain networks and rollups. Specializing in supporting yield-bearing collateral for lending markets, such as liquid staking tokens (LSTs) and liquid restaking tokens (LRTs), RedStone offers a scalable and flexible solution for decentralized finance (DeFi) platforms.

## Features

- **Modular and Flexible Oracle System**: RedStone’s architecture allows seamless integration of data feeds across multiple Layer 1 (L1), Layer 2 (L2), app chains, and non-EVM chains.
- **Gas-Optimized Data Feeds**: RedStone minimizes gas costs, reducing the expenses associated with putting data on the blockchain.
- **Diverse and Reliable Data Sources**: Data is aggregated from a wide range of sources, including directly from liquidity pools, ensuring accuracy of data.

## Getting Started

To integrate RedStone Oracles into your application:

1. **Visit the RedStone Website**: Explore the [RedStone Oracle website](https://redstone.finance/) to understand the range of services and integrations available.
2. **Access the Documentation**: Review the [RedStone Documentation](https://docs.redstone.finance/docs/introduction) for detailed guidance on selecting the right oracle model for your dApps.
3. **Integrate and Expand**: Implement RedStone’s data feeds in your smart contracts and reach out to the RedStone team for any support needed during the integration process.

## Documentation

For in-depth integration instructions, oracle model selection, and data feed details, visit the [RedStone Documentation](https://docs.redstone.finance/docs/introduction).

## Use Cases

RedStone Oracles is ideal for applications that require reliable and cost-efficient data feeds:

- **Traditional DeFi Platforms**: Easily integrate RedStone's Push model into existing DeFi protocols.
- **Liquid Staking and Restaking Platforms**: Manage LSTs and LRTs with precise and timely data not supported by other oracles.
- **Bitcoin in DeFi**: Unlock Bitcoin’s potential in DeFi.

## Conclusion

RedStone Oracles provides a modular, flexible, and gas-optimized solution for decentralized applications, backed by some of the most respected names in the Web3 ecosystem. Whether you're working with LSTs, integrating Bitcoin into DeFi, or seeking a reliable oracle across multiple blockchains, RedStone offers the tools and resources necessary for successful data integration and application development.


# Republic (/integrations/republic)

---
title: Republic
category: Tokenization Platforms
available: ["LUExchange-Chain"]
description: Republic is a global investment and advisory platform that merges private markets with Web3 technologies, enabling tokenized investments in startups, real estate, and digital securities.
logo: /images/republic.jpg
developer: Republic
website: https://republic.com/
documentation: https://republic.com/tokenization
---

## Overview

Republic is a multi-faceted investment platform that democratizes access to private market investments through tokenization and blockchain technology. Founded as a retail investing platform, Republic has evolved into a comprehensive ecosystem that enables individuals and institutions to invest in startups, tokenized assets, and digital securities while offering end-to-end services for businesses across fundraising, tokenization, and on-chain infrastructure.

Republic's tokenization platform enables the creation of Mirror Tokens and other digital representations of real-world assets, providing compliant and accessible entry points to traditionally exclusive investment opportunities. By bridging traditional finance with Web3 technologies, Republic makes it possible for a broader audience to participate in private markets that were historically reserved for institutional investors and venture funds.

## Features

- **Mirror Tokens**: Digital representations of debt securities tied to late-stage private companies, enabling fractional ownership of traditionally illiquid assets.
- **Multi-Asset Tokenization**: Support for tokenizing startups, real estate, video games, crypto projects, and other alternative assets.
- **End-to-End Platform**: Complete infrastructure for fundraising, token issuance, investor management, and secondary trading.
- **Regulatory Compliance**: Fully compliant digital securities structured to meet SEC and international regulatory requirements.
- **Global Investment Access**: Platform available to investors worldwide with localized regulatory compliance.
- **Fractional Ownership**: Enable smaller investors to participate in high-value assets through tokenized shares.
- **Secondary Markets**: Facilitate liquidity through regulated secondary trading of tokenized securities.
- **Investor Dashboard**: Comprehensive portfolio management tools for tracking tokenized investments.
- **Smart Contract Infrastructure**: Blockchain-based token issuance and management with transparent ownership records.
- **Institutional Services**: Advisory and infrastructure services for businesses looking to tokenize assets or raise capital.
- **Multi-Chain Support**: Tokenization infrastructure compatible with multiple blockchain networks.
- **KYC/AML Integration**: Built-in compliance processes for investor verification and regulatory adherence.

## Getting Started

To work with Republic for tokenization:

1. **Explore the Platform**: Visit [republic.com](https://republic.com/) to understand available investment opportunities and tokenization services.

2. **For Investors**:
   - Create an account on the Republic platform
   - Complete KYC verification process
   - Browse available tokenized investment opportunities
   - Invest in startups, real estate, or other tokenized assets
   - Track your portfolio through the investor dashboard

3. **For Issuers/Businesses**:
   - Contact Republic's advisory team to discuss tokenization needs
   - Determine which Republic service fits your requirements (fundraising, tokenization, infrastructure)
   - Work with Republic to structure compliant digital securities
   - Launch your tokenized offering on the platform
   - Access Republic's global investor network

4. **Integration Opportunities**: Businesses can explore partnerships with Republic for:
   - Tokenizing existing assets or securities
   - Launching security token offerings (STOs)
   - Building on Republic's blockchain infrastructure
   - Accessing advisory services for Web3 transition

## Lux Support

Republic's tokenization infrastructure supports multiple blockchain networks. While specific chain support may vary by offering, Republic's platform is designed to work with EVM-compatible networks including Lux LUExchange-Chain, enabling efficient and low-cost tokenization of assets on Lux's high-performance infrastructure.

## Use Cases

Republic's tokenization platform serves various investment categories:

**Startup Equity**: Invest in early-stage companies through tokenized equity offerings, enabling fractional ownership and potential liquidity.

**Real Estate**: Access tokenized real estate investments with lower capital requirements and improved liquidity compared to traditional real estate.

**Gaming Projects**: Invest in video game development through tokenized revenue shares or equity stakes.

**Crypto Projects**: Participate in Web3 and crypto project funding through compliant token offerings.

**Private Company Access**: Mirror Tokens provide exposure to late-stage private companies before they go public.

**Alternative Assets**: Tokenize and invest in art, collectibles, intellectual property, and other non-traditional assets.

## Republic's Investment Products

**Republic Capital**: Venture capital arm providing institutional-grade investment opportunities.

**Republic Crypto**: Focused on Web3 investments and blockchain technology companies.

**Republic Real Estate**: Platform for investing in tokenized real estate projects.

**Republic Gaming**: Dedicated to gaming industry investments and tokenization.

**Republic Note**: Convertible securities that provide optionality across Republic's diverse portfolio.

## Tokenization Services

Republic offers comprehensive tokenization services for businesses:

- **Asset Structuring**: Legal and financial structuring of tokenized securities
- **Regulatory Compliance**: Navigation of SEC regulations and international securities laws
- **Token Issuance**: Technical infrastructure for minting and distributing security tokens
- **Investor Relations**: Platform for managing investor communications and distributions
- **Secondary Trading**: Access to regulated secondary markets for liquidity
- **Smart Contract Development**: Custom smart contract development for tokenized securities
- **Advisory Services**: Strategic guidance on tokenization strategy and implementation

## Regulatory Framework

Republic operates under strict regulatory compliance:

- **SEC Registered**: Registered with the U.S. Securities and Exchange Commission
- **FINRA Member**: Member of the Financial Industry Regulatory Authority
- **Regulation CF**: Utilizes Regulation Crowdfunding for certain offerings
- **Regulation D**: Offers securities under Regulation D exemptions
- **Regulation A+**: Conducts mini-IPOs through Regulation A+ offerings
- **International Compliance**: Adheres to securities regulations in multiple jurisdictions

## Track Record

Republic has established significant presence in the tokenization and private markets space:

- Facilitated hundreds of millions in investments across thousands of deals
- Built a community of over 2 million users globally
- Partnered with leading startups and established companies for tokenization
- Expanded services across multiple asset classes and investment categories
- Developed robust infrastructure trusted by both issuers and investors

## Why Choose Republic

**Democratized Access**: Republic makes elite investment opportunities accessible to retail investors through tokenization and fractional ownership.

**Comprehensive Platform**: End-to-end solution covering everything from token issuance to secondary trading.

**Regulatory Expertise**: Deep experience navigating complex securities regulations across multiple jurisdictions.

**Global Reach**: Access to a worldwide network of investors and issuers.

**Multi-Asset Focus**: Platform supports diverse asset classes from startups to real estate to gaming.

**Web3 Integration**: Native understanding of blockchain technology and crypto markets.

**Proven Track Record**: Years of experience facilitating billions in private market investments.

## Conclusion

Republic represents a bridge between traditional private markets and the future of tokenized finance. By combining regulatory compliance, blockchain technology, and a global investment community, Republic enables both issuers and investors to participate in the tokenization revolution. Whether you're looking to invest in tokenized assets, tokenize your own securities, or build on Web3 infrastructure, Republic provides the platform, expertise, and network to make it possible. With support for multiple blockchain networks including Lux, Republic is well-positioned to be a leader in the evolution of private markets toward tokenized, accessible, and liquid digital securities.



# Request Network (/integrations/request)

---
title: Request Network
category: Payments
available: ["LUExchange-Chain"]
description: Request Network is the all-in-one finance platform for Web3 CFOs to manage stablecoin, crypto, and fiat operations covering accounts payable, receivable, payroll, and accounting in a compliant, audit-ready hub.
logo: /images/request.png
developer: Request Network
website: https://www.request.finance/
documentation: https://docs.request.network/
---

## Overview

Request Network is a comprehensive finance platform designed specifically for Web3 CFOs and finance teams to manage their entire financial operations—from accounts payable and receivable to payroll and accounting—all in one compliant, audit-ready platform. By seamlessly connecting stablecoin, cryptocurrency, and fiat operations with existing tools like QuickBooks, Xero, and Gnosis, Request saves time, reduces errors, and gives finance leaders confidence and control over their operations.

With over $1 billion in payments processed, Request Network has established itself as the essential financial infrastructure for Web3 companies, DAOs, and crypto-native organizations. The platform combines the efficiency of blockchain-based payments with the compliance and reporting requirements of traditional finance, creating a bridge that enables crypto-native companies to operate with the same financial rigor as their traditional counterparts.

## Features

- **All-in-One Finance Platform**: Complete financial operations in a single platform—AP, AR, payroll, accounting.
- **Multi-Currency Support**: Handle stablecoins, cryptocurrencies, and fiat currencies seamlessly.
- **Accounts Payable**: Manage vendor invoices, approvals, and batch payments efficiently.
- **Accounts Receivable**: Create invoices, track payments, and manage collections.
- **Payroll Management**: Process payroll in crypto or fiat with full compliance.
- **Accounting Integration**: Sync with QuickBooks, Xero, and other accounting software automatically.
- **Gnosis Safe Integration**: Direct integration with Gnosis Safe for secure multi-sig payments.
- **$1B+ Processed**: Proven platform with over $1 billion in payment volume.
- **Audit-Ready**: Comprehensive audit trails and reporting for compliance.
- **Batch Payments**: Pay multiple vendors or employees in a single transaction.
- **Invoice Creation**: Professional crypto-native invoices with multiple payment options.
- **Payment Requests**: Send payment requests with automatic tracking and reminders.
- **Tax Compliance**: Tools and reports for tax compliance across jurisdictions.
- **Multi-Chain Support**: Support for Lux and other major blockchain networks.
- **Real-Time Tracking**: Monitor all financial transactions in real-time dashboard.
- **Approval Workflows**: Customizable approval processes for expenditures.
- **Expense Management**: Track and categorize business expenses efficiently.

## Getting Started

To implement Request Network for your organization:

1. **Create an Account**: Sign up on [request.finance](https://www.request.finance/) to access the platform.

2. **Connect Your Wallet**: Link your organization's wallet (Gnosis Safe, MetaMask, etc.) for crypto operations.

3. **Set Up Integrations**: Connect existing tools:
   - **Accounting Software**: QuickBooks, Xero, or other platforms
   - **Multi-Sig Wallets**: Gnosis Safe for secure payments
   - **Bank Accounts**: For fiat operations (if applicable)
   - **Payroll Systems**: For streamlined payroll processing

4. **Configure Your Organization**:
   - Add team members and set permissions
   - Define approval workflows
   - Set up expense categories and budgets
   - Configure payment methods (stablecoins, crypto, fiat)

5. **Start Managing Finance Operations**:
   - **Accounts Payable**: Import or create vendor invoices, route for approval, batch pay
   - **Accounts Receivable**: Create invoices for customers, track payments
   - **Payroll**: Set up employee payment schedules and process payroll
   - **Reporting**: Generate financial reports for stakeholders

## Accounts Payable

Request streamlines the entire AP process:

**Invoice Management**: Import invoices from vendors or create internally, with automatic data extraction.

**Approval Workflows**: Route invoices through customizable approval chains before payment.

**Batch Payments**: Pay multiple vendors in a single blockchain transaction, saving gas fees.

**Vendor Portal**: Vendors can submit invoices directly through Request.

**Payment Scheduling**: Schedule payments for specific dates or conditions.

**Reconciliation**: Automatic matching of invoices to payments for easy reconciliation.

## Accounts Receivable

Manage customer payments efficiently:

**Professional Invoices**: Create crypto-native invoices with your branding.

**Multiple Payment Options**: Accept payments in various stablecoins, cryptocurrencies, or fiat.

**Payment Tracking**: Real-time tracking of invoice status and payment confirmations.

**Automated Reminders**: Send automatic payment reminders to customers.

**Collections Management**: Tools for managing overdue invoices.

**Customer Portal**: Customers can view and pay invoices through dedicated portal.

## Payroll Management

Handle payroll for crypto-native teams:

**Global Payroll**: Pay employees and contractors globally in their preferred currency.

**Compliance**: Maintain compliance with employment and tax regulations.

**Multiple Currencies**: Pay in stablecoins, crypto, or fiat as needed.

**Payment Scheduling**: Automate regular payroll cycles.

**Tax Reporting**: Generate necessary tax documents for employees and compliance.

**Contractor Management**: Separate workflows for employees vs. contractors.

## Accounting Integration

Request connects seamlessly with existing accounting tools:

**QuickBooks Integration**: Two-way sync with QuickBooks for automatic reconciliation.

**Xero Integration**: Full integration with Xero accounting platform.

**Automatic Categorization**: Transactions automatically categorized for accounting.

**Real-Time Sync**: Financial data syncs in real-time between Request and accounting software.

**Journal Entries**: Automatic generation of journal entries for crypto transactions.

**Tax Compliance**: Proper accounting treatment for crypto assets and transactions.

## Lux Support

Request Network operates on multiple blockchain networks including Lux LUExchange-Chain, enabling:

**Low-Cost Transactions**: Benefit from Lux's low fees for frequent payments.

**Fast Finality**: Near-instant payment confirmation for better cash flow management.

**Stablecoin Support**: Use USDC and other stablecoins on Lux for payments.

**Scalability**: Handle high volumes of transactions without network congestion.

**Enterprise-Ready**: Lux's institutional focus aligns with Request's finance use cases.

## Use Cases

Request serves diverse Web3 organizations:

**Web3 Startups**: Manage all financial operations as the company scales.

**DAOs**: Enable decentralized organizations to manage treasury and payments compliantly.

**Crypto Companies**: Finance operations for exchanges, protocols, and infrastructure providers.

**Remote Teams**: Pay global teams in crypto or fiat with full compliance.

**Service Providers**: Invoice clients and manage receivables for crypto-native services.

**Investment Funds**: Manage fund operations and investor distributions.

**NFT Projects**: Handle creator payments and royalty distributions.

**DeFi Protocols**: Manage protocol expenses and contributor compensation.

## Compliance and Audit

Request provides comprehensive compliance features:

**Complete Audit Trail**: Every transaction recorded with full details and blockchain proof.

**Financial Reports**: Generate reports for auditors, investors, and regulators.

**Tax Documentation**: Comprehensive tax reports for various jurisdictions.

**SOC 2 Compliance**: Platform maintains SOC 2 Type II certification.

**Data Export**: Export financial data in standard formats for analysis.

**Regulatory Reporting**: Tools for meeting reporting requirements.

## Platform Benefits

**Time Savings**: Automate financial workflows that previously required hours of manual work.

**Error Reduction**: Eliminate manual data entry errors through automation and integration.

**Cost Efficiency**: Reduce accounting costs and payment processing fees.

**Better Control**: Real-time visibility and control over all financial operations.

**Audit-Ready**: Maintain compliance and audit-ready records automatically.

**Scalability**: Platform grows with your organization from startup to enterprise.

**Professional Image**: Present professional, compliant financial operations to stakeholders.

## Technology Infrastructure

Request Network provides robust technology:

- **Smart Contract Layer**: Open-source smart contracts for payment requests and invoicing
- **Multi-Chain Support**: Operate across Ethereum, Lux, Polygon, and other networks
- **API Access**: Comprehensive APIs for custom integrations
- **Wallet Integration**: Connect with Gnosis Safe, MetaMask, Ledger, and other wallets
- **Real-Time Dashboard**: Monitor all financial activity in real-time
- **Mobile Access**: Manage finances on the go with mobile-friendly interface
- **Security**: Enterprise-grade security with encrypted data and secure key management

## Gnosis Safe Integration

Deep integration with Gnosis Safe multi-sig wallets:

**Direct Payments**: Pay directly from Gnosis Safe within Request platform.

**Multi-Sig Approvals**: Leverage Gnosis Safe's approval process for payments.

**Batch Transactions**: Combine multiple payments into single Gnosis transaction.

**Treasury Management**: Manage organizational treasury through Gnosis + Request.

**Security**: Maintain multi-sig security while streamlining finance operations.

## Pricing

Request Network offers transparent pricing:

- **Free Tier**: Basic features for small teams and startups
- **Professional**: Enhanced features for growing companies
- **Enterprise**: Custom solutions for large organizations
- **Transaction Fees**: Small fees on processed payments
- **Integration**: Accounting software integrations included

Visit [request.finance/pricing](https://www.request.finance/pricing) for current pricing details.

## Track Record

Request Network's proven success:

- **$1+ Billion**: Over $1 billion in payments processed
- **Thousands of Organizations**: Used by companies, DAOs, and protocols globally
- **Years of Operation**: Established platform with multi-year track record
- **Open Source**: Core protocol is open-source and transparent
- **Community Support**: Active community and ecosystem of integrations

## Ecosystem

Request connects the broader Web3 finance ecosystem:

**Accounting Software**: QuickBooks, Xero, and other platforms.

**Wallets**: Gnosis Safe, MetaMask, Ledger, and hardware wallets.

**Payment Rails**: Support for multiple blockchains and payment methods.

**Service Providers**: Integration with tax advisors, accountants, and auditors.

**DeFi Protocols**: Connections to lending, yield, and treasury management protocols.

## Customer Support

Request provides comprehensive support:

- **Documentation**: Extensive guides and API documentation
- **Customer Success**: Dedicated support for paid customers
- **Community**: Active Discord and forums for peer support
- **Training**: Onboarding and training for finance teams
- **Professional Services**: Custom integrations and implementations available

## Conclusion

Request Network has established itself as the essential financial infrastructure for Web3 organizations, providing the tools and compliance necessary for crypto-native companies to operate with professional financial rigor. By combining accounts payable, receivable, payroll, and accounting in one platform with seamless integration to tools like QuickBooks, Xero, and Gnosis Safe, Request saves finance teams time, reduces errors, and provides the control and visibility needed to manage operations confidently. With over $1 billion processed and support for blockchain networks like Lux, Request has proven its ability to handle real-world financial operations at scale. Whether you're a Web3 startup, DAO, or established crypto company, Request Network provides the comprehensive, compliant, audit-ready finance platform that enables you to focus on building your business while maintaining the same financial standards as traditional companies.



# Revolut (/integrations/revolut)

---
title: Revolut
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: "Revolut is a global fintech platform enabling users to buy, hold, and manage cryptocurrencies alongside traditional banking services."
logo: /images/revolut.png
developer: Revolut
website: https://www.revolut.com/
documentation: https://developer.revolut.com/
---

## Overview

Revolut is a leading global fintech platform that provides banking services alongside cryptocurrency trading and management. With millions of users worldwide, Revolut enables easy purchase of cryptocurrencies directly from its app, providing a familiar and trusted gateway for traditional finance users to enter the crypto ecosystem.

## Features

- **Integrated Banking**: Crypto alongside traditional banking services
- **Easy Purchase**: Buy crypto directly with bank accounts
- **Multiple Cryptocurrencies**: Support for major cryptocurrencies
- **Trusted Platform**: Millions of verified users worldwide
- **Mobile-First**: Seamless mobile app experience
- **Instant Conversion**: Quick fiat-to-crypto conversions

## Getting Started

For users:
1. **Download Revolut**: Get the Revolut app
2. **Create Account**: Complete verification process
3. **Add Funds**: Fund your Revolut account
4. **Buy Crypto**: Purchase cryptocurrencies including those on Lux
5. **Manage**: Track and manage your crypto holdings

For developers, explore [Revolut Developer Portal](https://developer.revolut.com/).

## Documentation

For API documentation, visit [Revolut Developer Docs](https://developer.revolut.com/).

## Use Cases

- **Consumer On-Ramp**: Easy crypto access for mainstream users
- **Portfolio Management**: Manage crypto alongside traditional assets
- **Payments**: Use crypto for payments through Revolut
- **Banking Integration**: Bridge traditional and crypto finance

## Conclusion

Revolut provides a trusted, mainstream fiat on-ramp for cryptocurrency, enabling millions of users to easily access and manage crypto assets including those in the Lux ecosystem.


# Rise (/integrations/rise)

---
title: Rise
category: Payments
available: ["LUExchange-Chain"]
description: Rise is a global payroll and compliance platform enabling businesses to pay teams in 190+ countries with flexible options in local currencies, stablecoins, and cryptocurrencies with automated compliance.
logo: /images/rise.webp
developer: Rise
website: https://riseworks.io/
documentation: https://riseworks.io/docs
---

## Overview

Rise is a comprehensive global payroll and compliance platform designed to help businesses of all sizes—from startups to enterprises and Web3 organizations—seamlessly pay their distributed teams across 190+ countries. By offering flexible payment options including local currencies, stablecoins, and cryptocurrencies, Rise eliminates the complexity of international payroll while ensuring full compliance with local regulations through its Agent of Record (AOR) and Employer of Record (EOR) models.

The platform automates critical payroll functions including onboarding, tax reporting, benefits administration, and compliance management, enabling companies to focus on building their business while Rise handles the intricacies of global employment. With secure, compliant, and audit-ready infrastructure, Rise has become the payroll solution of choice for companies navigating the complexities of a global, distributed workforce.

## Features

- **Global Payroll Coverage**: Pay employees and contractors in 190+ countries worldwide.
- **Multiple Payment Options**: Support for local currencies, stablecoins (USDC, USDT), and cryptocurrencies.
- **Automated Onboarding**: Streamlined employee and contractor onboarding with digital workflows.
- **Tax Compliance**: Automatic tax calculations, withholdings, and reporting for all jurisdictions.
- **Agent of Record (AOR)**: Compliance services for contractor management globally.
- **Employer of Record (EOR)**: Full employment services in countries without local entities.
- **Benefits Administration**: Manage health insurance, retirement plans, and other benefits.
- **Automated Compliance**: Stay compliant with local labor laws and regulations automatically.
- **Audit-Ready Records**: Comprehensive documentation and reporting for audits.
- **Multi-Currency Support**: Pay in local currencies or digital assets based on preference.
- **Blockchain Payments**: Native support for stablecoin and crypto payments on networks like Lux.
- **Self-Service Portal**: Employee portal for managing pay, benefits, and documents.
- **API Integration**: Connect Rise with existing HR and accounting systems.
- **Real-Time Exchange Rates**: Competitive FX rates for international payments.
- **Payment Scheduling**: Automated recurring payroll with customizable schedules.
- **Compliance Monitoring**: Continuous monitoring of changing regulations.

## Getting Started

To implement Rise for your organization:

1. **Initial Consultation**: Contact Rise to discuss your global payroll needs:
   - Number of employees/contractors
   - Countries where team members are located
   - Current payroll challenges
   - Payment preferences (fiat, stablecoins, crypto)
   - Compliance requirements

2. **Platform Setup**: Configure your Rise account:
   - Set up company profile and entities
   - Define payroll schedules and policies
   - Configure payment methods and currencies
   - Set up benefits and compensation structures
   - Integrate with existing HR/accounting systems

3. **Employee Onboarding**: Add team members to the platform:
   - Digital onboarding workflows for employees and contractors
   - Collect necessary documentation and tax forms
   - Set up payment preferences (bank accounts, crypto wallets)
   - Enroll in benefits programs
   - Complete compliance requirements by jurisdiction

4. **Payroll Processing**: Run your first payroll:
   - Review employee hours/salaries
   - Approve payroll run
   - Automatic tax calculations and withholdings
   - Process payments in chosen currencies
   - Generate pay stubs and reports

5. **Ongoing Management**: Maintain compliant payroll operations:
   - Monitor compliance across jurisdictions
   - Handle tax filings automatically
   - Manage benefits and HR administration
   - Access real-time reporting and analytics
   - Scale to new countries as needed

## Agent of Record (AOR)

Rise's AOR service simplifies contractor management:

**Global Contractor Compliance**: Ensure proper classification and treatment of contractors worldwide.

**Payment Processing**: Handle contractor payments in their preferred currency or digital asset.

**Tax Documentation**: Manage tax forms and reporting requirements (1099s, etc.).

**Contract Management**: Store and manage contractor agreements compliantly.

**Invoice Processing**: Automate contractor invoice collection and payment.

**Compliance Monitoring**: Stay updated on contractor regulations by country.

Rise's AOR service eliminates the risk of misclassification while enabling fast, flexible contractor payments globally.

## Employer of Record (EOR)

Rise's EOR service enables hiring without local entities:

**Legal Employment**: Rise becomes the legal employer in countries where you don't have entities.

**Full HR Services**: Complete HR administration including payroll, benefits, and compliance.

**Local Expertise**: In-country experts ensure compliance with local labor laws.

**Rapid Deployment**: Hire in new countries in days, not months.

**Benefits Administration**: Provide competitive local benefits packages.

**Offboarding Support**: Handle employee departures compliantly.

This allows companies to hire the best talent globally without the cost and complexity of establishing local entities.

## Payment Flexibility

Rise's multi-modal payment approach provides unprecedented flexibility:

**Local Currency Payments**: Pay employees in their local currency via local banking rails.

**Stablecoin Payments**: Offer payment in USDC, USDT, or other stablecoins for instant settlement.

**Cryptocurrency Options**: Enable payment in LUX, BTC, ETH, or other cryptocurrencies.

**Mixed Payments**: Allow employees to split compensation between fiat and crypto.

**Instant Settlement**: Blockchain payments settle instantly vs. days with traditional banking.

**Lower Costs**: Reduce FX fees and international wire costs with crypto payments.

This flexibility is particularly valuable for Web3 companies and teams preferring crypto compensation.

## Lux Integration

Rise's blockchain payment infrastructure supports Lux LUExchange-Chain, enabling:

**LUX Payroll**: Pay employees directly in LUX with fast finality and low fees.

**Stablecoin Payments**: Leverage USDC on Lux for dollar-denominated crypto payroll.

**Instant Settlement**: Benefit from Lux's sub-second transaction finality.

**Low Costs**: Lux's minimal fees make frequent payments economically viable.

**Global Reach**: Send payments to anywhere globally using Lux network.

**Compliance**: Maintain necessary tax reporting even with crypto payments.

Rise's Lux integration demonstrates commitment to supporting Web3-native payroll solutions.

## Use Cases

Rise serves diverse organizations with global teams:

**Web3 Startups**: Pay distributed crypto-native teams in their preferred currencies and digital assets.

**Global Enterprises**: Manage payroll for thousands of employees across dozens of countries.

**Remote-First Companies**: Support fully distributed workforce with compliant global payroll.

**Rapid Expansion**: Quickly enter new markets and hire talent without local entity setup.

**Contractor Management**: Compliantly manage large contractor workforces globally.

**Hybrid Organizations**: Support mix of full-time employees and contractors worldwide.

**DAOs**: Enable decentralized organizations to pay contributors compliantly.

**Crypto Companies**: Offer crypto-native payroll to teams building blockchain applications.

## Compliance and Security

Rise maintains rigorous compliance standards:

- **Multi-Jurisdictional Compliance**: Expertise in employment law across 190+ countries
- **Automated Tax Filing**: Handle federal, state, and local tax filings automatically
- **Data Security**: SOC 2 Type II certified infrastructure with bank-level security
- **Audit Trails**: Complete records for audits and regulatory requirements
- **Data Privacy**: GDPR, CCPA, and other privacy regulation compliance
- **Regular Updates**: Continuous monitoring of regulatory changes
- **Insurance**: Employment practices liability insurance coverage
- **Legal Expertise**: In-house legal team ensuring ongoing compliance

## Platform Capabilities

### Payroll Management

- **Automated Payroll**: Set-and-forget recurring payroll processing
- **Multi-Country**: Single platform for all countries
- **Tax Calculations**: Automatic withholdings for all jurisdictions
- **Payment Methods**: Bank transfer, crypto, stablecoins, local rails
- **Approval Workflows**: Customizable payroll approval processes
- **Pay Stubs**: Automatic generation of compliant pay stubs

### HR Administration

- **Employee Records**: Centralized employee data and documentation
- **Time Tracking**: Integration with time tracking systems
- **Leave Management**: PTO, sick leave, and holiday tracking
- **Benefits Enrollment**: Digital benefits selection and administration
- **Performance Management**: Tools for reviews and feedback
- **Onboarding/Offboarding**: Complete hire-to-retire workflows

### Reporting and Analytics

- **Real-Time Dashboard**: View payroll status and metrics instantly
- **Cost Analytics**: Understand total employment costs by country/department
- **Compliance Reports**: Generate audit and compliance documentation
- **Tax Reports**: Comprehensive tax reporting for all jurisdictions
- **Custom Reports**: Build reports tailored to your needs
- **Data Export**: Export data to accounting and analytics tools

## Integrations

Rise connects with essential business tools:

**Accounting Software**: QuickBooks, Xero, NetSuite for financial sync.

**HRIS Platforms**: BambooHR, Workday, Greenhouse for HR data.

**Time Tracking**: Harvest, Toggl, Clockify for hours worked.

**Expense Management**: Expensify, Ramp for expense reimbursement.

**Communication**: Slack, Microsoft Teams for notifications.

**Blockchain Wallets**: MetaMask, Gnosis Safe for crypto payments.

**Banking**: Integration with business bank accounts.

## Pricing

Rise offers transparent, scalable pricing:

- **Per-Employee Pricing**: Predictable costs based on headcount
- **Country-Specific Rates**: Pricing varies by employment complexity
- **EOR Premium**: Additional fees for Employer of Record services
- **AOR Pricing**: Competitive rates for contractor management
- **No Setup Fees**: No upfront costs to get started
- **Volume Discounts**: Reduced rates for larger teams
- **Custom Enterprise**: Tailored pricing for large organizations

Contact Rise for detailed pricing based on your team size and locations.

## Competitive Advantages

**Global Scale**: Support for 190+ countries from a single platform.

**Payment Flexibility**: Unique combination of fiat, stablecoin, and crypto options.

**Web3 Native**: Purpose-built for crypto-native companies and teams.

**Compliance First**: Automated compliance reduces legal risk.

**Fast Deployment**: Hire globally in days, not months.

**Cost Efficiency**: Reduce costs vs. traditional international payroll.

**Blockchain Integration**: Native support for Lux and other networks.

## Customer Support

Rise provides comprehensive support:

- **Dedicated Account Manager**: Personalized support for your organization
- **24/7 Global Support**: Support teams across time zones
- **Compliance Experts**: Access to employment law specialists
- **Onboarding Assistance**: White-glove setup and migration support
- **Training**: Platform training for HR and finance teams
- **Knowledge Base**: Comprehensive documentation and guides
- **Community**: Connect with other Rise customers

## Why Choose Rise

**Simplicity**: Manage global payroll in one platform instead of dozens of providers.

**Flexibility**: Pay teams however they prefer—fiat, stablecoins, or crypto.

**Compliance**: Sleep easy knowing you're compliant in every jurisdiction.

**Speed**: Hire and pay globally faster than traditional solutions.

**Web3 Ready**: Built for the future of work with blockchain-native payments.

**Scalability**: Start with one country, scale to hundreds.

**Transparency**: Clear pricing with no hidden fees or surprises.

## Conclusion

Rise is transforming global payroll by combining the compliance and reliability of traditional payroll providers with the flexibility and efficiency of blockchain-based payments. By supporting 190+ countries with payment options spanning local currencies, stablecoins on networks like Lux, and cryptocurrencies, Rise enables companies to pay their distributed teams exactly how they want while maintaining full compliance through automated AOR and EOR services. Whether you're a Web3 startup paying your first contractor or a global enterprise managing thousands of employees, Rise provides the secure, compliant, and audit-ready infrastructure to streamline payroll operations while embracing the future of global work. With Rise, companies can focus on building their business while confident that their global payroll is handled professionally and compliantly across every jurisdiction.



# RockX (/integrations/rockx)

---
title: RockX
category: RPC Endpoints
available: ["LUExchange-Chain"]
description: "RockX provides blockchain infrastructure services including RPC endpoints and staking solutions for Web3 applications."
logo: /images/rockX.jpg
developer: RockX
website: https://www.rockx.com/
documentation: https://www.rockx.com/
---

## Overview

RockX is a blockchain infrastructure provider offering RPC services, node infrastructure, and staking solutions for Web3 applications. With support for multiple blockchain networks including Lux, RockX provides developers with reliable, high-performance access to blockchain data and networks, along with comprehensive staking services.

## Features

- **RPC Infrastructure**: High-performance RPC endpoints for blockchain access.
- **Node Services**: Reliable node infrastructure for various blockchain networks.
- **Staking Solutions**: Comprehensive staking services for proof-of-stake networks.
- **Multi-Chain Support**: Support for multiple blockchain networks and protocols.
- **High Availability**: Robust infrastructure ensuring reliable uptime.
- **Performance Optimized**: Optimized nodes for fast response times and low latency.
- **Enterprise Solutions**: Scalable infrastructure for enterprise applications.
- **Security Focus**: Institutional-grade security for node operations.

## Documentation

For more information, visit the [RockX website](https://www.rockx.com/).

## Use Cases

RockX serves various blockchain infrastructure needs:

- **DApp Development**: Reliable RPC infrastructure for decentralized applications.
- **Staking Services**: Infrastructure for staking and validator operations.
- **Institutional Solutions**: Enterprise-grade infrastructure for institutional clients.
- **Node Operations**: Managed node services for blockchain networks.

## Conclusion

RockX provides comprehensive blockchain infrastructure and RPC services for Lux applications, offering reliable node access combined with professional staking solutions for developers and institutions.



# Routescan (/integrations/routescan)

---
title: Routescan
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: Routescan provides block explorer as a service for Lux L1s, offering real-time data on transactions, blocks, validators, and more.
logo: /images/routescan.avif
developer: Routescan
website: https://routescan.io/explorer-as-a-service
documentation: https://routescan.io/documentation
---

## Overview

Routescan is a block explorer service tailored for Lux Layer 1 (L1) networks. It provides a comprehensive solution for monitoring blockchain activity, offering real-time data on transactions, blocks, validators, and other critical metrics. Routescan is designed to be scalable and customizable, making it an ideal choice for developers and enterprises looking to integrate block explorer capabilities into their Lux-based solutions.

## Features

- **Real-Time Data**: Access up-to-date information on transactions, blocks, and validators across Lux L1s.
- **Explorer as a Service**: Utilize Routescan’s block explorer as a service to integrate blockchain monitoring into your own platform or application.
- **Customizable Solutions**: Tailor the explorer to fit specific needs, offering flexibility for different use cases.
- **Detailed Validator Information**: Get insights into validator performance, staking details, and historical data.
- **Scalable Infrastructure**: Routescan’s infrastructure is built to handle large volumes of data and transactions, ensuring reliability and performance.
- **API Integration**: Leverage Routescan’s API to fetch and display blockchain data within your own applications.

## Getting Started

To begin using Routescan:

1. **Visit the Routescan Website**: Explore the [Routescan website](https://routescan.io/explorer-as-a-service) to learn more about their block explorer as a service and its features.
2. **Access Documentation**: Check out the [Routescan Documentation](https://routescan.io/documentation) for detailed guides on setting up and using their services.
3. **Integrate the API**: Obtain an API key and start integrating Routescan’s data into your own applications or platforms.
4. **Customize Your Explorer**: Tailor the block explorer service to meet the specific needs of your Lux L1 project.
5. **Monitor Network Activity**: Use Routescan to monitor transactions, blocks, and validators in real-time, ensuring that your network is functioning optimally.

## Documentation

For comprehensive information on setting up, customizing, and using Routescan, visit the [Routescan Documentation](https://routescan.io/documentation).

## Use Cases

Routescan is ideal for:

- **Blockchain Developers**: Integrate a scalable block explorer into your Lux L1 projects, providing users with real-time network data.
- **Enterprises**: Leverage Routescan’s customizable explorer service to monitor and manage blockchain activity at scale.
- **Validators**: Track validator performance and optimize operations using detailed real-time and historical data.
- **Platform Providers**: Offer block explorer functionality as a value-added service on your own platforms using Routescan’s infrastructure.

## Conclusion

Routescan provides a powerful, scalable block explorer service for Lux L1 networks, enabling developers, enterprises, and validators to monitor and manage blockchain activity with precision. Whether you need a standalone explorer or an integrated service within your own platform, Routescan delivers the tools and flexibility required to support your blockchain monitoring needs. With real-time data, customizable options, and robust infrastructure, Routescan is an essential resource for any Lux L1 project.



# RWA.xyz (/integrations/rwa-xyz)

---
title: RWA.xyz
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "RWA.xyz provides comprehensive analytics and data tracking for Real World Assets (RWA) tokenized on blockchain, including Lux."
logo: /images/rwa.jpeg
developer: RWA.xyz
website: https://rwa.xyz/
documentation: https://rwa.xyz/
---

## Overview

RWA.xyz is a specialized analytics platform focused on Real World Assets (RWA) tokenized on blockchain networks, including Lux. The platform provides comprehensive data, metrics, and insights into the growing RWA sector, helping users track tokenized assets, market trends, and ecosystem developments.



# Sardine (/integrations/sardine)

---
title: Sardine
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: Sardine provides fraud prevention and risk management infrastructure for crypto on-ramp and off-ramp solutions with built-in compliance and KYC capabilities.
logo: /images/sardine.png
developer: Sardine
website: https://www.sardine.ai/
documentation: https://docs.sardine.ai/
---

## Overview

Sardine is a behavior intelligence and fraud prevention platform that provides comprehensive risk management infrastructure for cryptocurrency and financial applications. While Sardine specializes in fraud detection and prevention, they also offer integrated fiat-to-crypto on-ramp solutions that enable businesses to offer secure cryptocurrency purchases with built-in compliance, KYC verification, and real-time fraud prevention capabilities.

Sardine's platform leverages advanced machine learning and behavioral biometrics to detect and prevent fraud across the entire customer journey, from account creation to transaction processing. With support for Lux and other major blockchains, Sardine helps applications reduce fraud while improving conversion rates and user experience.

## Features

- **Fraud Prevention**: Real-time fraud detection using machine learning, behavioral biometrics, and device intelligence.
- **Risk Management**: Comprehensive risk scoring and monitoring across the customer lifecycle.
- **KYC/AML Compliance**: Built-in identity verification and anti-money laundering screening that meets global regulatory requirements.
- **Fiat On-Ramp Integration**: Seamless integration of payment rails for crypto purchases with fraud protection.
- **Payment Method Support**: Accept credit cards, debit cards, ACH, and other payment methods with built-in fraud prevention.
- **Behavioral Biometrics**: Analyze user behavior patterns to detect account takeovers and synthetic identity fraud.
- **Device Intelligence**: Track and analyze device fingerprints to prevent fraud and account sharing.
- **Transaction Monitoring**: Real-time monitoring of crypto transactions for suspicious activity.
- **Sanctions Screening**: Automated screening against global sanctions lists and watchlists.
- **Customizable Rules Engine**: Create custom risk rules tailored to your business needs.
- **Webhooks and APIs**: Comprehensive API suite with real-time webhooks for fraud alerts and risk events.
- **Dashboard and Analytics**: Access detailed analytics and insights on fraud patterns and user behavior.

## Getting Started

To integrate Sardine into your application:

1. **Create a Sardine Account**: Sign up on the Sardine platform to access the dashboard and API credentials.

2. **Complete Onboarding**: Go through Sardine's onboarding process to configure your fraud prevention policies and risk thresholds.

3. **Obtain API Keys**: Generate your API keys from the Sardine dashboard for both sandbox and production environments.

4. **Choose Integration Approach**: Sardine offers multiple integration options:
   - **Full Platform Integration**: Integrate Sardine's complete fraud prevention suite across user onboarding, transactions, and account management
   - **On-Ramp Integration**: Add Sardine's fiat-to-crypto on-ramp with built-in fraud prevention
   - **API Integration**: Build custom solutions using Sardine's fraud detection and risk management APIs

5. **Configure Risk Rules**: Set up your fraud detection rules, risk scoring thresholds, and automated actions.

6. **Test in Sandbox**: Use Sardine's sandbox environment to test fraud scenarios and verify your integration.

7. **Set Up Webhooks**: Configure webhook endpoints to receive real-time notifications about fraud events and risk alerts.

8. **Go Live**: After testing, activate your production environment and start protecting your users from fraud.

## Lux Support

Sardine supports fraud prevention and on-ramp services for Lux-based assets, including LUX and USDC on the Lux LUExchange-Chain. This enables applications built on Lux to offer secure fiat on-ramp experiences while maintaining high conversion rates through intelligent fraud detection.

## Documentation

For comprehensive integration guides, API references, and fraud prevention best practices, visit:

- [Sardine Documentation](https://docs.sardine.ai/)
- [Integration Guides](https://docs.sardine.ai/guides/integration/integrationguides/overview)
- [API Reference](https://docs.sardine.ai/guides/api-reference/overview)
- [Knowledge Base](https://docs.sardine.ai/guides/knowledge-base/overview)

## Use Cases on Lux

Sardine can enhance security and compliance for Lux applications:

**Cryptocurrency Exchanges**: Prevent fraud across user registration, deposits, withdrawals, and trades involving LUX and Lux-based tokens.

**DeFi Platforms**: Protect your platform from fraudulent activities while enabling secure fiat on-ramps for Lux DeFi protocols.

**NFT Marketplaces**: Detect and prevent fraud in NFT purchases on Lux, protecting both buyers and sellers.

**Wallet Applications**: Secure user onboarding and transactions with behavioral analysis and fraud detection for Lux wallets.

**GameFi Applications**: Prevent account takeovers, payment fraud, and bot activity in Lux-based gaming platforms.

**On-Ramp Providers**: Reduce chargebacks and fraud losses while maintaining high approval rates for legitimate users purchasing LUX and Lux tokens.

## Pricing

Sardine's pricing is based on transaction volume and features used:

- **Risk Assessment**: Priced per risk assessment or transaction screened
- **KYC Verification**: Per verification with volume-based pricing tiers
- **On-Ramp Services**: Transaction-based fees for fiat-to-crypto conversions
- **Custom Enterprise Plans**: Tailored pricing for high-volume applications
- **Volume Discounts**: Available for applications with significant transaction volumes

For detailed pricing information and custom enterprise solutions, contact Sardine's sales team.

## Fraud Prevention Capabilities

Sardine provides comprehensive fraud prevention across multiple vectors:

- **Account Opening Fraud**: Detect synthetic identities, stolen identities, and fake accounts during registration
- **Payment Fraud**: Prevent credit card fraud, ACH fraud, and payment method abuse
- **Account Takeover**: Identify unauthorized access through behavioral analysis and device intelligence
- **Transaction Fraud**: Monitor crypto purchases and transfers for suspicious patterns
- **Bot Detection**: Identify and block automated attacks and bot activity
- **Money Laundering**: Detect suspicious transaction patterns indicative of money laundering
- **Promo Abuse**: Prevent exploitation of promotional offers and referral programs

## Compliance and Security

Sardine maintains robust compliance and security standards:

- **SOC 2 Type II Certified**: Independently audited security controls and processes
- **GDPR Compliant**: Full compliance with European data protection regulations
- **PCI DSS Compliant**: Secure handling of payment card information
- **Global Compliance**: Support for KYC/AML requirements across multiple jurisdictions
- **Data Encryption**: End-to-end encryption for sensitive user data
- **Regular Audits**: Ongoing security assessments by independent third parties

## Why Choose Sardine

**Advanced AI/ML**: Sardine's machine learning models continuously adapt to new fraud patterns and attack vectors.

**Real-Time Decisions**: Make instant accept/reject decisions without sacrificing security for speed.

**Low False Positives**: Intelligent risk scoring reduces false declines while catching actual fraud, improving conversion rates.

**Comprehensive Coverage**: Protect every step of the customer journey from onboarding to transactions.

**Easy Integration**: Well-documented APIs and SDKs make integration straightforward for developers.

**Proven Track Record**: Trusted by leading crypto and fintech companies to prevent fraud at scale.

## Conclusion

Sardine provides essential fraud prevention and risk management infrastructure for applications building on Lux. By combining advanced fraud detection with compliant on-ramp solutions, Sardine enables developers to offer secure cryptocurrency purchasing experiences while minimizing fraud losses and maintaining high conversion rates. Whether you need comprehensive fraud prevention across your entire platform or a secure on-ramp solution for Lux assets, Sardine's intelligent risk management tools help protect your business and users while growing your application with confidence.



# Securitize (/integrations/securitize)

---
title: Securitize
category: Tokenization Platforms
available: ["LUExchange-Chain"]
description: Securitize is a leading regulated platform that enables compliant tokenization, issuance, trading, and management of real-world assets on blockchain, serving institutional and retail investors.
logo: /images/securitize.png
developer: Securitize
website: https://securitize.io/
documentation: https://securitize.io/learn
---

## Overview

Securitize is a premier digital securities platform that provides end-to-end infrastructure for tokenizing, issuing, and managing real-world assets on blockchain networks. As a regulated transfer agent and SEC-registered broker-dealer, Securitize enables institutions and asset managers to bring traditional financial assets on-chain in a fully compliant manner. With over $4 billion in assets tokenized, Securitize has established itself as a trusted partner for leading financial institutions including BlackRock, KKR, and Hamilton Lane.

Securitize's comprehensive platform handles the entire lifecycle of digital securities—from token creation and investor onboarding to transfer agent services, fund administration, and secondary trading through its regulated Alternative Trading System (ATS). By combining cutting-edge blockchain technology with regulatory compliance, Securitize is accelerating the transformation of global capital markets toward tokenized, programmable securities.

## Features

- **End-to-End Tokenization**: Complete platform for structuring, issuing, and managing tokenized securities.
- **Regulatory Compliance**: SEC-registered transfer agent and broker-dealer with full regulatory infrastructure.
- **Multi-Asset Support**: Tokenize private equity, credit funds, real estate, public stocks, treasuries, and more.
- **Alternative Trading System (ATS)**: Regulated secondary marketplace for trading tokenized securities.
- **Transfer Agent Services**: Compliant shareholder recordkeeping and corporate actions management.
- **Fund Administration**: Comprehensive fund operations including NAV calculations and investor reporting.
- **Investor Onboarding**: Streamlined KYC/AML processes with accredited investor verification.
- **Smart Contract Infrastructure**: Secure, audited smart contracts for token issuance and lifecycle management.
- **Distribution Network**: Access to Securitize's network of qualified investors and institutional buyers.
- **Compliance Automation**: Automated compliance checks for transfer restrictions and regulatory requirements.
- **Multi-Chain Support**: Tokenization across multiple blockchain networks with interoperability.
- **Institutional-Grade Security**: Enterprise security standards with SOC 2 Type II certification.
- **Cap Table Management**: Digital cap table with real-time ownership tracking and reporting.
- **Dividend Distribution**: Automated dividend and distribution payments to token holders.

## Getting Started

To work with Securitize:

1. **For Asset Managers and Issuers**:
   - Contact Securitize's institutional team to discuss tokenization requirements
   - Define the asset or fund to be tokenized
   - Work with Securitize to structure the digital security
   - Complete legal documentation and regulatory filings
   - Launch the tokenized offering on Securitize's platform
   - Utilize transfer agent and fund administration services
   - Access secondary trading through Securitize Markets

2. **For Investors**:
   - Create an account on the Securitize platform
   - Complete KYC/AML verification and accreditation
   - Browse available tokenized investment opportunities
   - Invest in digital securities through the platform
   - Manage your portfolio and receive distributions
   - Trade on Securitize Markets (for eligible securities)

3. **For Technology Partners**:
   - Explore Securitize's APIs and integration capabilities
   - Partner with Securitize to embed tokenization services
   - Access Securitize's infrastructure for building complementary services

## Lux Support

Securitize's platform supports multiple blockchain networks for token issuance. While Ethereum is commonly used, Securitize's infrastructure is designed to support EVM-compatible chains including Lux LUExchange-Chain, enabling efficient, low-cost tokenization of securities on Lux's high-throughput network.

## Major Partnerships and Assets

Securitize has tokenized significant institutional assets:

**BlackRock USD Institutional Digital Liquidity Fund (BUIDL)**: BlackRock's tokenized money market fund providing qualified investors with access to U.S. dollar yields on-chain.

**KKR Funds**: Tokenization of KKR's Health Care Strategic Growth Fund II, expanding access to institutional private equity.

**Hamilton Lane**: First tokenized Hamilton Lane funds in the U.S., democratizing access to private markets.

**Distributing for Franklin Templeton**: Distribution partnership for Franklin Templeton's tokenized funds.

These partnerships demonstrate Securitize's position as the trusted infrastructure provider for institutional-grade tokenization.

## Use Cases

Securitize's platform enables tokenization across multiple asset classes:

**Private Equity Funds**: Tokenize PE funds to increase accessibility, reduce minimums, and improve liquidity for LPs.

**Real Estate**: Transform real estate holdings into digital securities with fractional ownership and enhanced liquidity.

**Credit Funds**: Tokenize debt funds and fixed-income products for broader distribution.

**Public Equities**: Create tokenized representations of public stocks with programmable features.

**Treasury Products**: Offer tokenized exposure to U.S. Treasuries and money market instruments.

**Revenue-Sharing Agreements**: Structure and tokenize revenue participation rights for businesses.

**Art and Collectibles**: Fractionally own high-value art and collectibles through compliant tokenization.

## Securitize Markets

Securitize operates a regulated Alternative Trading System (ATS) for secondary trading:

- **Regulated Marketplace**: SEC-registered ATS providing compliant secondary liquidity
- **Qualified Investors**: Marketplace accessible to accredited and institutional investors
- **Price Discovery**: Transparent order book for discovering fair market value
- **Settlement Infrastructure**: Efficient on-chain settlement of trades
- **Market Making**: Potential liquidity provision through market makers
- **Trading Hours**: Extended trading windows beyond traditional market hours

## Technology Infrastructure

Securitize provides enterprise-grade technology:

- **Blockchain Agnostic**: Support for multiple blockchain networks
- **Smart Contract Security**: Audited contracts with formal verification
- **API Integration**: RESTful APIs for seamless integration
- **Compliance Layer**: On-chain compliance rules enforced through smart contracts
- **Identity Management**: Secure identity verification and management
- **Data Room**: Secure document management for offering materials
- **Reporting Tools**: Comprehensive reporting for investors and regulators
- **Custody Integration**: Compatible with institutional-grade custody providers

## Regulatory Licensing

Securitize maintains comprehensive regulatory compliance:

- **SEC-Registered Transfer Agent**: Authorized to maintain shareholder records
- **SEC-Registered Broker-Dealer**: Member of FINRA for securities distribution
- **Alternative Trading System (ATS)**: Registered ATS for secondary trading
- **Multi-Jurisdictional**: Compliance frameworks for international operations
- **SOC 2 Type II Certified**: Independently audited security and compliance controls

## Benefits of Securitize

**Institutional Trust**: Chosen by BlackRock, KKR, and Hamilton Lane for multi-billion dollar tokenizations.

**Comprehensive Solution**: Only platform offering issuance, transfer agent, fund admin, and secondary trading.

**Regulatory Certainty**: Full regulatory licensing eliminates compliance risks.

**Proven at Scale**: Over $4 billion in tokenized assets demonstrates capability and reliability.

**Investor Network**: Access to network of qualified investors seeking tokenized securities.

**Technology Leadership**: Advanced blockchain infrastructure with security and compliance built-in.

**Secondary Liquidity**: Regulated ATS provides true liquidity for tokenized securities.

## Pricing

Securitize offers customized pricing for institutional clients:

- **Initial Setup**: One-time fees for structuring and launching tokenized securities
- **Transfer Agent Fees**: Ongoing fees for shareholder recordkeeping and corporate actions
- **Fund Administration**: Monthly fees for NAV calculation and investor reporting
- **Trading Fees**: Transaction fees for secondary market trading
- **Platform Fees**: Annual platform access and technology fees
- **Custom Solutions**: Tailored pricing for complex or large-scale tokenizations

Contact Securitize's institutional team for detailed pricing.

## Conclusion

Securitize has established itself as the leading infrastructure provider for institutional tokenization, bridging the gap between traditional finance and blockchain technology. With comprehensive regulatory licensing, proven technology, and partnerships with the world's largest asset managers, Securitize enables the compliant transformation of real-world assets into digital securities. Whether you're an asset manager looking to tokenize funds, an issuer seeking to improve access to capital, or an investor wanting exposure to tokenized assets on blockchain networks like Lux, Securitize provides the trusted, regulated infrastructure to make it possible. As tokenization becomes mainstream, Securitize is positioned as the essential platform for bringing trillions of dollars of traditional assets on-chain.



# Sensei Node (/integrations/sensei-node)

---
title: Sensei Node
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Sensei Node provides institutional-grade validator infrastructure and staking services for proof-of-stake networks."
logo: /images/sensei-node.png
developer: Sensei Node
website: https://www.senseinode.com/
documentation: https://docs.senseinode.com/
---

## Overview

Sensei Node is a professional blockchain infrastructure provider offering institutional-grade validator services and staking solutions. With a focus on security, reliability, and performance, Sensei Node enables institutions and individuals to participate in Lux network validation with confidence.

## Features

- **Professional Validation**: Institutional-grade validator operations
- **High Availability**: Redundant infrastructure for maximum uptime
- **Multi-Chain Support**: Validation services across leading PoS networks
- **Staking Services**: Comprehensive staking solutions for clients
- **Security Focus**: Enterprise security practices for validator operations
- **Performance Monitoring**: Real-time validator performance tracking

## Getting Started

To work with Sensei Node:

1. **Contact Sensei Node**: Reach out through [Sensei Node](https://www.senseinode.com/)
2. **Discuss Requirements**: Share your validation or staking needs
3. **Onboarding**: Complete the setup process
4. **Operations**: Begin validation or staking operations
5. **Monitor**: Track performance through provided dashboards

## Documentation

For more information, visit [Sensei Node Documentation](https://docs.senseinode.com/).

## Use Cases

- **Validator Operations**: Run professional Lux validators
- **Staking Delegation**: Delegate to Sensei Node validators
- **Institutional Services**: Staking solutions for institutions
- **L1 Infrastructure**: Validation services for Lux L1s

## Conclusion

Sensei Node provides professional validator infrastructure for Lux, enabling reliable participation in network validation with institutional-grade operations.


# Sherry (/integrations/sherry-protocol)

---
title: Sherry
category: Mini-Apps
available: ["LUExchange-Chain"]
description: "Sherry is the publishing layer that turns any interaction — from a tweet to a chatbot message — into a verifiable, tappable onchain action."
logo: /images/sherry.png
developer: Sherry Labs
website: https://sherry.social
documentation: https://docs.sherry.social/docs/intro
---

## Overview

Sherry Protocol enables decentralised, verifiable distribution and execution of onchain actions. As the publishing layer for Web3, it allows anyone to create, embed, and amplify interactive Web3 actions anywhere on the internet and execute complex multi-step flows directly from their context.

Our SDK empowers developers to create rich, composable mini-apps called Triggers that seamlessly integrate into social networks making blockchain interactions as simple as sharing a link. Sherry is building the foundation for a universal communication standard between AI Agents and Web3 applications.

## Features

- **Interactive Triggers**: Transform static posts into dynamic Web3 experiences with built-in validation and cross-chain support.
- **Multi-Chain Support**: Native integration across Lux, Ethereum, and more blockchain networks.
- **Multiple Action Types**: 
  - **Blockchain Actions**: Smart contract interactions with rich parameter configuration
  - **Transfer Actions**: Native token and ERC20 transfers with customizable UIs
  - **Dynamic Actions**: User-defined actions with flexible parameters for custom logic
  - **HTTP Actions**: API calls and form submissions
  - **Nested Action Flows**: Complex multi-step processes with conditional logic
- **Frictionless UX**: Users can interact with Web3 applications without leaving their social feed.
- **Developer-Friendly SDK**: Full TypeScript support with comprehensive type definitions and built-in validation.
- **AI Agent Ready**: Structured metadata designed to become a common language for AI agents to discover and execute blockchain capabilities.

## Getting Started

To begin building with Sherry:

1. **Install the SDK**:
   ```bash
   npm install @sherrylinks/sdk
   # or
   yarn add @sherrylinks/sdk
   ```

2. **Create Your First Trigger**:
   ```typescript
   import { createMetadata, Metadata } from '@sherrylinks/sdk';

   const metadata: Metadata = {
     url: 'https://myapp.example',
     icon: 'https://example.com/icon.png',
     title: 'Send LUX',
     description: 'Quick LUX transfer',
     actions: [
       {
         label: 'Send 0.1 LUX',
         description: 'Transfer 0.1 LUX to recipient',
         to: '0x1234567890123456789012345678901234567890',
         amount: 0.1,
         chains: { source: 'lux' },
       },
     ],
   };

   const validatedMetadata = createMetadata(metadata);
   ```

3. **Deploy and Share**: Embed your trigger into social media posts and let users interact directly.

## Documentation

For comprehensive guides and technical documentation, visit [Sherry Documentation](https://docs.sherry.social/docs/intro). Key resources include:

- **[SDK Introduction](https://docs.sherry.social/docs/intro)**: Getting started with the Sherry SDK
- **[Action Types](https://docs.sherry.social/docs/api/action-types)**: Learn about different interaction types
- **[Parameters Guide](https://docs.sherry.social/docs/api-reference/parameters/)**: Configure user inputs and validation
- **[Chain Support](https://docs.sherry.social/docs/core-concepts/chains)**: Multi-chain deployment guide
- **[Guides](https://docs.sherry.social/docs/getting-started/examples)**: Guides and code samples for common use cases

## Use Cases

Sherry serves diverse Web3 integration needs:

- **Social DeFi**: Enable token swaps, staking, and yield farming directly within social posts.
- **DAO Governance**: Create voting interfaces and proposal submission forms embedded in community posts.
- **NFT Experiences**: Allow minting, trading, and showcasing NFTs without leaving social platforms.
- **Fundraising Campaigns**: Build donation and crowdfunding triggers with real-time progress tracking.
- **Cross-Chain Operations**: Execute seamless asset transfers between different blockchain networks.
- **AI Agent Integration**: Provide structured interfaces for AI agents to interact with Web3 protocols.
- **Community Engagement**: Create interactive experiences that boost social media engagement while driving Web3 adoption.

## Supported Chains

Sherry currently supports the following blockchain networks:

- **Lux LUExchange-Chain** (`lux`)
- **Lux Testnet Testnet** (`testnet`)

Additional L1 chains are continuously being added to expand the platform's reach and capabilities.

## Recent Milestones

**Lux Codebase **: Part of Lux Codebase S25.

## Vision & Roadmap

Sherry aims to be the performance layer of the permissionless internet — where every link, post, or message can carry embedded economic intent.  We're building the foundation for a universal standard of communication between AI Agents and blockchain applications. Our structured metadata is designed to become a common language that allows AI Agents to:

- **Discover Blockchain Capabilities**: Enable AI agents to understand available actions in each Web3 application
- **Execute Complex Actions**: Make it easier for agents to compose and execute sequences of blockchain actions
- **Universal Interoperability**: Establish bridges between different AI and blockchain ecosystems
- **Complexity Abstraction**: Hide technical details so agents can focus on meeting user needs

## Conclusion

Sherry represents the next evolution of how Web3 is experienced and adopted. Whether you're a developer building the next generation of social DApps, a community manager looking to engage your audience, or an AI agent seeking to interact with blockchain protocols, Sherry provides the infrastructure to make it happen.

# Silo (/integrations/silo)

---
title: Silo
category: DeFi
available: ["LUExchange-Chain"]
description: "Silo is a decentralized lending protocol with isolated money markets, providing secure liquidity solutions on Lux."
logo: /images/silo.png
developer: Silo Finance
website: https://silo.finance
documentation: https://docs.silo.finance
---

## Overview

Silo is a decentralized lending protocol deployed on Lux's LUExchange-Chain, featuring isolated money markets that minimize risk by segregating assets. This unique approach allows Silo to support a wide range of tokens while maintaining strong security guarantees and efficient liquidity management.

## Features

- **Isolated Markets**: Each token has its own isolated lending market, reducing systemic risk.
- **Risk Containment**: Protocol-wide risk is minimized through market isolation.
- **Permissionless Listings**: Support for any token without requiring governance approval.
- **Bridge Assets**: Connect isolated markets through bridge assets like ETH and stablecoins.
- **Flexible Collateral**: Use a variety of assets as collateral for borrowing.
- **Security Focused**: Enhanced security through isolated market architecture.

## Getting Started

To begin using Silo:

1. **Access Platform**: Visit [Silo](https://silo.finance) and connect to Lux.
2. **Connect Wallet**: Link your Web3 wallet with LUX for transaction fees.
3. **Supply Assets**: 
   - Deposit assets to isolated markets to earn interest
   - Each market operates independently
   - Monitor your positions across different silos
4. **Borrow Safely**: Take out loans against your collateral with contained risk exposure.

## Documentation

For detailed protocol information and guides, visit the [Silo Documentation](https://docs.silo.finance).

## Use Cases

Silo serves various DeFi needs:

- **Safe Lending**: Earn interest with reduced protocol-wide risk through isolated markets.
- **Diverse Assets**: Access lending and borrowing for a wide range of tokens.
- **Risk Management**: Benefit from isolated market architecture that contains potential exploits.
- **Yield Generation**: Earn competitive yields by supplying assets to various silos.
- **Flexible Borrowing**: Access liquidity against diverse collateral types.

## Conclusion

Silo brings innovative isolated lending markets to Lux, offering users a secure and flexible platform for DeFi lending and borrowing. Its unique architecture provides enhanced security while maintaining capital efficiency, making it an attractive option for users seeking safer DeFi participation on Lux's LUExchange-Chain.



# Skybridge (/integrations/skybridge)

---
title: Skybridge
category: Assets
available: ["LUExchange-Chain"]
description: "Skybridge Capital offers tokenized fund products providing institutional investors access to digital asset strategies."
logo: /images/skybridge.png
developer: Skybridge Capital
website: https://www.skybridge.com/
---

## Overview

Skybridge Capital is a global alternative investment firm that has embraced digital assets, offering tokenized fund products and digital asset strategies. Through blockchain technology, Skybridge provides institutional and qualified investors with innovative access to alternative investment opportunities including digital assets and tokenized fund structures.

## Features

- **Tokenized Funds**: Fund products available in tokenized form
- **Digital Asset Strategies**: Professional digital asset investment strategies
- **Alternative Investments**: Broad alternative investment expertise
- **Institutional Standards**: Investment processes meeting institutional requirements
- **Transparency**: Enhanced transparency through tokenization
- **Professional Management**: Experienced investment management

## Getting Started

To access Skybridge products:

1. **Visit Skybridge**: Explore [Skybridge Capital](https://www.skybridgecapital.com/)
2. **Review Products**: Learn about available fund products
3. **Qualification**: Complete investor qualification process
4. **Investment**: Access Skybridge investment products
5. **Monitoring**: Track investment performance

## Use Cases

- **Fund Access**: Access alternative investment funds
- **Digital Asset Exposure**: Gain exposure to digital asset strategies
- **Tokenized Ownership**: Own tokenized fund shares
- **Institutional Portfolio**: Add digital assets to institutional portfolios

## Conclusion

Skybridge Capital provides tokenized access to alternative investment strategies on Lux, enabling institutional investors to participate in digital asset opportunities through familiar fund structures.


# Snowpeer (/integrations/snowpeer)

---
title: Snowpeer
category: Analytics & Data
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Snowpeer provides comprehensive Lux network analytics, offering real-time monitoring, validator insights, and network performance metrics."
logo: /images/snowpeer.png
developer: Snowpeer
website: https://snowpeer.io/
documentation: https://snowpeer.io/
---

## Overview

Snowpeer is a specialized analytics platform designed for the Lux network, providing real-time data and insights into network performance, validator operations, and blockchain metrics. It offers comprehensive monitoring tools for developers, validators, and network participants to track and analyze Lux ecosystem activity.

## Features

- **Network Analytics**:
  - Real-time network metrics
  - Validator performance tracking
  - Node monitoring
  - Network health indicators
- **Data Visualization**:
  - Interactive dashboards
  - Historical data charts
  - Performance graphs
  - Network topology views
- **Validator Insights**:
  - Uptime tracking
  - Delegation statistics
  - Reward analytics
  - Performance comparisons
- **Monitoring Tools**:
  - Alert notifications
  - Custom metrics tracking
  - API access
  - Data exports

## Getting Started

To use Snowpeer:

1. **Access Platform**:
   - Visit [Snowpeer](https://snowpeer.io/)
   - Explore available metrics and dashboards
   - Set up monitoring preferences
2. **Monitor Network**:
   - Track validator performance
   - View network statistics
   - Analyze historical trends
3. **Integration**:
   - Access API endpoints
   - Configure alerts
   - Export data for analysis

## Documentation

For more information and detailed guides, visit the [Snowpeer website](https://snowpeer.io/).

## Use Cases

Snowpeer enables:

- **Validator Operations**: Monitor and optimize validator performance
- **Network Analysis**: Track Lux network health and metrics
- **Research**: Access historical data for blockchain research
- **Delegation Decisions**: Evaluate validators for informed delegation
- **Portfolio Tracking**: Monitor staking rewards and performance

## Conclusion

Snowpeer provides essential analytics and monitoring capabilities for the Lux ecosystem, offering comprehensive tools for validators, delegators, and developers to track network performance and make informed decisions. With its real-time data and intuitive dashboards, Snowpeer is a valuable resource for anyone participating in the Lux network.



# SnowScan (/integrations/snowscan)

---
title: SnowScan
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: SnowScan is a block explorer for the Lux network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/snowscan.png
developer: Etherscan
website: https://snowscan.xyz/
documentation: https://docs.snowscan.xyz/
---

## Overview

SnowScan is a comprehensive block explorer for the Lux network, developed by Etherscan. It provides users with real-time data on transactions, blocks, validators, and other crucial metrics within the Lux ecosystem. With its reliable infrastructure and intuitive interface, SnowScan is a valuable tool for developers, validators, and anyone interested in exploring the Lux blockchain.

## Features

- **Real-Time Data**: Access up-to-the-minute information on transactions, block confirmations, and validator activities on the Lux network.
- **Detailed Analytics**: Get in-depth analytics on blocks, transactions, and addresses to better understand blockchain activity.
- **Validator Monitoring**: Track validator performance and staking information with detailed insights and historical data.
- **User-Friendly Interface**: Navigate the Lux blockchain with an intuitive, easy-to-use interface similar to Etherscan.
- **API Integration**: Utilize the SnowScan API to integrate blockchain data into your applications and services.
- **Comprehensive Search Tools**: Easily find specific transactions, addresses, or blocks with advanced search functionalities.

## Getting Started

To start using SnowScan:

1. **Visit the SnowScan Website**: Explore the [SnowScan website](https://snowscan.xyz/) to begin navigating the Lux network.
2. **Search and Analyze**: Use the search functionality to find transactions, addresses, and block information, or dive into detailed analytics.
3. **Monitor Validators**: Access performance data for validators, including staking details and historical metrics.
4. **Use the API**: For developers, refer to the [SnowScan Documentation](https://docs.snowscan.xyz/) to learn how to integrate SnowScan’s API into your projects.
5. **Explore the Lux Network**: Leverage SnowScan’s tools to monitor and analyze network activity, ensuring you stay informed on the latest developments.

## Documentation

For more detailed information on using SnowScan and integrating its features, visit the [SnowScan Documentation](https://docs.snowscan.xyz/).

## Use Cases

SnowScan is ideal for:

- **Blockchain Developers**: Monitor and analyze transactions, blocks, and validators to support development and deployment on the Lux network.
- **Validators**: Optimize performance and track staking activities with real-time data and insights.
- **Researchers and Analysts**: Conduct detailed analyses of the Lux blockchain using comprehensive data provided by SnowScan.
- **General Users**: Explore and verify transactions, blocks, and network activities with a user-friendly block explorer.

## Conclusion

SnowScan offers a powerful and reliable block explorer experience tailored for the Lux network. Whether you’re a developer, validator, or blockchain enthusiast, SnowScan provides the tools and data you need to effectively monitor and analyze blockchain activity on Lux. With its real-time data, intuitive interface, and robust API, SnowScan is an essential resource for anyone involved with Lux.



# SnowTrace (/integrations/snowtrace)

---
title: SnowTrace
category: Explorers
available: ["LUExchange-Chain"]
description: SnowTrace is a block explorer for the Lux network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/snowtrace.jpg
developer: Routescan
website: https://snowtrace.io/
documentation: https://snowtrace.io/documentation
---

## Overview

SnowTrace is a powerful block explorer for the Lux network, developed by Routescan. It provides users with detailed, real-time data on transactions, blocks, validators, and other essential blockchain metrics. SnowTrace is designed to be user-friendly while offering robust features for developers, validators, and anyone interested in tracking Lux network activities.

## Features

- **Real-Time Blockchain Data**: Access up-to-date information on transactions, block confirmations, and validator activities.
- **Comprehensive Search Tools**: Easily search for specific transactions, addresses, blocks, and more using advanced search functionality.
- **Validator Insights**: Get detailed information on validator performance, including staking details and historical data.
- **Network Overview**: View a holistic overview of the Lux network, including key metrics and network status.
- **User-Friendly Interface**: Navigate through blockchain data with a clean, intuitive interface suitable for both beginners and advanced users.
- **API Access**: Integrate SnowTrace data into applications via its API, providing developers with reliable access to blockchain data.

## Getting Started

To start using SnowTrace:

1. **Visit SnowTrace**: Navigate to the [SnowTrace website](https://snowtrace.io/) to begin exploring the Lux network.
2. **Search and Explore**: Use the search functionality to find specific transactions, addresses, or blocks, and explore detailed blockchain data.
3. **Validator Data**: Dive into validator statistics to analyze performance and staking information.
4. **Check Network Status**: Monitor the overall health and status of the Lux network with real-time metrics.
5. **API Documentation**: Refer to the [SnowTrace Documentation](https://snowtrace.io/documentation) for information on using the API, including endpoints and usage examples.

## Documentation

For more information on using SnowTrace and integrating its features into your projects, visit the [SnowTrace Documentation](https://snowtrace.io/documentation).

## Use Cases

SnowTrace is ideal for:

- **Blockchain Developers**: Analyze transactions and blocks for development purposes, debugging, and smart contract interaction.
- **Validators**: Monitor validator operations and optimize performance based on real-time and historical data.
- **Blockchain Enthusiasts**: Explore the Lux network and track transactions, blocks, and network activity.
- **Analysts and Researchers**: Access comprehensive data for in-depth blockchain analysis and research.

## Conclusion

SnowTrace is an essential tool for anyone working with or interested in the Lux network. With its detailed real-time data, user-friendly interface, and robust API, SnowTrace offers comprehensive insights into the blockchain. Whether you’re a developer, validator, or blockchain enthusiast, SnowTrace provides the resources and tools you need to effectively monitor and analyze the Lux network.



# SocialScan (/integrations/socialscan)

---
title: SocialScan
category: Explorers
available: ["LUExchange-Chain", "All Lux L1s"]
description: "SocialScan is a social-focused blockchain explorer providing address labeling, identity verification, and community-driven data."
logo: /images/socialscan.png
developer: SocialScan
website: https://socialscan.io/
documentation: https://docs.thehemera.com/
---

## Overview

SocialScan is a blockchain explorer with a focus on social identity and community-driven data. Beyond traditional block explorer features, SocialScan provides address labeling, identity verification, and social context for blockchain addresses, helping users understand who they're interacting with on-chain.

## Features

- **Social Labels**: Community-contributed address identification
- **Identity Verification**: Verified labels for known entities
- **Transaction Explorer**: Standard block explorer functionality
- **Address Analytics**: Activity analysis for blockchain addresses
- **Scam Detection**: Community reporting of suspicious addresses
- **Multi-Chain Support**: Coverage across multiple blockchain networks

## Getting Started

To use SocialScan:

1. **Visit SocialScan**: Access [SocialScan](https://socialscan.io/)
2. **Search Addresses**: Look up addresses with social context
3. **Contribute Labels**: Add labels for addresses you can verify
4. **Explore Transactions**: Use standard explorer features
5. **Report Issues**: Flag suspicious addresses for the community

## Documentation

For more information, visit [SocialScan Documentation](https://docs.thehemera.com/).

## Use Cases

- **Due Diligence**: Verify addresses before transacting
- **Scam Prevention**: Check addresses against community reports
- **Research**: Analyze on-chain activity with social context
- **Community Building**: Contribute to address labeling

## Conclusion

SocialScan adds valuable social context to blockchain exploration, helping Lux users make informed decisions about the addresses and entities they interact with.


# Space and Time (/integrations/spaceandtime)

---
title: Space and Time
category: Analytics & Data
available: ["LUExchange-Chain", "Subnet"]
description: "SpaceandTime is a decentralized data warehouse for indexing blockchain data and supporting onchain/offchain analytics."
logo: /images/spacentime.jpg
developer: Space and Time
website: https://www.spaceandtime.io
documentation: https://docs.spaceandtime.io
---

## Overview
Space and Time is a decentralized data warehouse that provides a blockchain indexing services for major blockchains, including Bitcoin, Ethereum, Lux etc., for developers to access real-time data and build data-driven apps.

## Key Features.

- **Integration with Major Chains**: Space and Time integrates with major blockchains like Ethereum, Polygon, and Lux, enabling developers to easily connect data to smart contracts.
- **Zero-Knowledge Proofs**: Space and Time leverages zero-knowledge proofs to enhance data privacy and integrity, allowing for secure and verifiable computations.
- **Proof of SQL**: This protocol ensures that off-chain compute results are cryptographically verifiable, enhancing data integrity and trust.
- **Smart Contract Indexing**: Allows developers to generate custom tables in Space and Time from their own smart contract events.

## Getting Started

To begin exploring Lux data from Space and Time;

1. **Create UserID**: Create a new user with a username and password by registering via [Dreamspace](https://app.spaceandtime.ai).
2. **Create API key**: To authenticate your app queries, create an API key. 
- Go to "My Account" then click on "Account settings" 
- Add a label (e.g., "LuxApp") and click add.
- Copy the API key shown; it will not be displayed again.
3. **Explore Indexed Lux Data Sets**: Go to the "Datasets" tab where you'll see all tables.
4. **Run your first lux Query**: Use the Query Editor to run queries directly on Lux chain data.
5. **Use Lux Data in your App**: Once your query works, you can fetch the results from your app via Space and Time's REST API.

Here is a detailed quick-start guide: https://docs.makeinfinite.com/docs/gettingstarted

## Documentation

For a comprehensive and detailed guide on querying data and building with Space and Time, visit [SpaceandTimeDocumentatio](https://docs.makeinfinite.com)

## Use-Cases

1. **Sub-second ZK Coprocessor**: Space and Time pioneered the first sub-second ZK coprocessor so that your smart contract can ask data-driven questions about indexed data from every major chain and offchain data from any source in a realtime, ZK-proven way.
2. **Onchain app development**: Build data-driven apps with pre-built APIs for SQL operations. Run SQL against your own offchain data tables and tables with realtime blockchain data that we've indexed from major chains.
3. **DeFi/lending**: With Space and Time, you can combine real-world credit scores with onchain transactions to create new Web3 credit scores for decentralized lending platforms.
4. **Gaming/NFTs**: Power your game with extremely low-latency transactions and run scale-out analytics against terabytes of data. 
5. **Tamperproof SQL ledger**: Space and Time lets you prove compliance, track supply chain history, maintain an auditable record of financial transactions, and more by ensuring that your data is accurate, verifiable, and traceable at all times.
6. **Verifiable LLMs**: Build transparent, tamperproof, and provably neutral LLMs. 

## Conclusion
Space and Time (SXT Chain) is the first trustless database for the EVM, enabling smart contracts to interact with historical, cross-chain, or offchain data as if it were natively accessible onchain.


# Spearbit (/integrations/spearbit)

---
title: Spearbit
category: Audit Firms
available: ["LUExchange-Chain"]
description: Spearbit is an elite network of top security researchers providing world-class smart contract audits through a unique decentralized model that matches projects with the perfect auditor expertise.
logo: /images/spearbit.jpg
developer: Spearbit
website: https://spearbit.com/
documentation: https://spearbit.com/audits
---

## Overview

Spearbit is revolutionizing smart contract security through a unique decentralized auditing model that connects projects with an elite network of the industry's top independent security researchers. Rather than employing auditors full-time, Spearbit curates a network of world-class security experts who have proven their capabilities through rigorous vetting. This approach ensures projects get matched with auditors who have the perfect expertise for their specific protocol type and technology stack.

Spearbit's network includes security researchers who have found critical vulnerabilities in major protocols, contributed to Ethereum security, and built security tools used across the industry. By leveraging this distributed network of specialists, Spearbit provides institutional-grade security audits that rival or exceed traditional audit firms while maintaining flexibility and deep domain expertise.

## Services

- **Smart Contract Audits**: Elite-tier security audits by top independent researchers.
- **Protocol Security Reviews**: Comprehensive architecture and design assessment.
- **Audit Matching**: Perfect matching between project needs and auditor expertise.
- **Continuous Security**: Ongoing security monitoring and support.
- **Security Reviews**: Multiple independent reviewers for maximum coverage.
- **Cantina**: Competitive audit platform for additional security assurance.
- **Incident Response**: Emergency support from experienced security researchers.
- **Security Consulting**: Advisory services from leading experts.
- **Custom Engagements**: Tailored security services for unique requirements.

## Decentralized Auditing Model

Spearbit's innovative approach offers unique advantages:

**Expert Matching**: Projects are matched with security researchers who specialize in their specific protocol type, technology, or domain.

**Depth of Expertise**: Access to specialists in DeFi mechanisms, cryptography, governance, NFTs, or any other specific area.

**Flexible Resourcing**: Scale audit teams up or down based on project complexity.

**Independent Reviewers**: Multiple independent auditors provide diverse perspectives.

**Quality Consistency**: All auditors vetted through rigorous security researcher screening.

**Global Talent**: Access to the best security talent globally, not limited by geography.

## Security Researcher Network

Spearbit's network includes auditors who have:

- Found critical vulnerabilities in major protocols
- Contributed to Ethereum core security
- Built widely-used security tools
- Published security research
- Won major audit competitions
- Worked at leading security firms

This ensures every audit is conducted by proven experts.

## Cantina Platform

Spearbit operates Cantina, a competitive audit platform:

**Competitive Audits**: Multiple security researchers compete to find vulnerabilities.

**Higher Coverage**: More eyes on code means better vulnerability detection.

**Time-Bounded**: Fixed-timeline competitive reviews.

**Prize Pools**: Incentivizes thorough security research.

**Complementary**: Can be used alongside traditional audits for extra assurance.

## Audit Methodology

Spearbit employs a comprehensive approach:

1. **Requirements Analysis**: Understand protocol design, business logic, and security priorities
2. **Auditor Matching**: Select perfect security researchers for the engagement
3. **Automated Analysis**: Run comprehensive security tooling
4. **Manual Review**: Deep expert review by matched specialists
5. **Economic Analysis**: Review tokenomics and incentive mechanisms
6. **Integration Testing**: Test interactions with external protocols
7. **Attack Simulation**: Adversarial testing by security experts
8. **Findings Documentation**: Detailed report with severity classifications
9. **Review Session**: In-depth discussion with development team
10. **Remediation Support**: Ongoing consultation during fixes
11. **Verification Audit**: Thorough re-audit of all changes

## Lux Expertise

Spearbit's network includes security researchers with deep Lux experience:

- Lux LUExchange-Chain smart contract security
- Subnet architecture and security
- Cross-chain bridge audits
- High-throughput protocol optimization
- Lux-specific attack vectors
- EVM compatibility considerations

## Access Through Areta Marketplace

Lux projects can engage Spearbit through the [Areta Audit Marketplace](https://areta.market/lux):

- **Elite Access**: Connect with Spearbit's network of top security researchers
- **Competitive Process**: Receive proposals from Spearbit and other leading firms
- **Transparent Pricing**: Clear costs and scope
- **Subsidy Eligibility**: Qualify for up to $10k in audit cashback
- **Fast Matching**: Get connected within 48 hours
- **Ecosystem Support**: Marketplace built for Lux projects

## Audit Focus Areas

**Complex DeFi**: Advanced DeFi mechanisms, derivatives, and innovative protocols.

**Infrastructure**: Layer 1/2 protocols, consensus, and core infrastructure.

**Bridges**: Cross-chain bridges and interoperability protocols.

**Novel Mechanisms**: Cutting-edge protocols requiring specialized expertise.

**High-Value Protocols**: Systems securing significant assets.

**Cryptography**: Novel cryptographic implementations.

## Notable Engagements

Spearbit's network has audited major protocols including:

- Leading DeFi protocols with billions in TVL
- Cross-chain bridge infrastructure
- Layer 2 scaling solutions
- Novel cryptographic systems
- Major NFT platforms

## Why Choose Spearbit

**Elite Talent**: Access to the industry's top independent security researchers.

**Perfect Matching**: Get auditors with exact expertise your protocol needs.

**Deep Expertise**: Specialists in specific protocol types and technologies.

**Flexible Model**: Scale engagement based on complexity and budget.

**Proven Results**: Network has found critical vulnerabilities in major protocols.

**Multiple Reviewers**: Leverage multiple independent perspectives.

**Cantina Option**: Additional competitive audit platform for extra assurance.

**Institutional Quality**: Matches or exceeds traditional top-tier firms.

## Pricing

Spearbit offers:

- Pricing based on codebase complexity and required expertise
- Flexible engagement models
- Competitive rates for elite-tier security
- Premium pricing reflecting top-tier talent

Contact via Areta marketplace or directly for proposals.

## Getting Started

To engage Spearbit:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit audit request with protocol details
   - Receive proposal from Spearbit
   - Access subsidies and streamlined process

2. **Direct Contact**:
   - Visit [spearbit.com](https://spearbit.com/)
   - Submit audit inquiry
   - Discuss requirements and matching
   - Receive detailed proposal

## Deliverables

Spearbit provides:

- **Comprehensive Audit Report**: Detailed findings from elite security researchers
- **Executive Summary**: High-level overview for stakeholders
- **Technical Analysis**: Deep technical assessment and recommendations
- **Remediation Guidance**: Expert guidance for addressing issues
- **Re-Audit Report**: Verification by same expert auditors
- **Ongoing Access**: Continued access to auditors for questions

## Conclusion

Spearbit represents the future of smart contract auditing through its decentralized network of elite security researchers. By matching Lux projects with security experts who have the perfect domain expertise, Spearbit delivers institutional-grade audits that rival or exceed traditional firms while maintaining flexibility and deep specialization. Available through the Areta Audit Marketplace for streamlined access and potential subsidies, Spearbit's innovative model ensures your protocol is reviewed by the industry's top security talent, providing the highest level of security assurance for critical infrastructure and high-value protocols on Lux.



# StraitsX (/integrations/straitsx)

---
title: StraitsX
category: Assets
available: ["LUExchange-Chain"]
description: "StraitsX provides regulated stablecoins including XSGD (Singapore Dollar stablecoin), offering tokenized fiat currencies for Southeast Asian markets."
logo: /images/straitsx.png
developer: StraitsX
website: https://www.straitsx.com/
documentation: https://www.straitsx.com/
---

## Overview

StraitsX is a regulated stablecoin issuer providing XSGD (Singapore Dollar stablecoin) and other tokenized fiat currencies for Southeast Asian markets. With full regulatory compliance under Singapore's Payment Services Act and transparent reserve management, StraitsX enables users and businesses to access stable digital representations of regional currencies on blockchain, facilitating cross-border payments, remittances, and financial services with local currency stability.



# Stripe (/integrations/stripe)

---
title: Stripe
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: Stripe's fiat-to-crypto onramp enables users to securely purchase cryptocurrencies including LUX and USDC directly from your platform or decentralized application.
logo: /images/stripe.png
developer: Stripe
website: https://stripe.com/
documentation: https://docs.stripe.com/crypto/onramp
---

## Overview

Stripe is a leading global payment infrastructure provider that powers online and in-person payments for millions of businesses worldwide. Stripe's fiat-to-crypto onramp extends their payment platform to enable secure cryptocurrency purchases directly within applications and decentralized platforms. With support for Lux (LUX and USDC on Lux LUExchange-Chain), Stripe provides a trusted, compliant on-ramp solution that handles all regulatory requirements, KYC verification, fraud prevention, and dispute management.

Stripe acts as the merchant of record for onramp transactions, assuming full liability for fraud and disputes while providing developers with a seamless integration experience. The platform leverages Stripe's existing checkout infrastructure, allowing returning users to complete purchases faster with saved payment methods and KYC data.

## Features

- **Merchant of Record**: Stripe acts as the legal entity responsible for facilitating crypto sales, handling all liability.
- **Lux Support**: Native support for LUX and USDC on Lux LUExchange-Chain for fast, low-cost transactions.
- **Multiple Integration Options**: Choose from Stripe-hosted, embedded web, or native mobile SDK integrations.
- **Zero Platform Fraud Liability**: Stripe handles all fraud prevention, disputes, and chargebacks.
- **Comprehensive Compliance**: Built-in KYC/AML verification, sanctions screening, and regulatory compliance.
- **Stripe Link Integration**: Returning users can check out faster with saved payment and KYC data through Stripe Link.
- **Multiple Payment Methods**: Support for credit cards, debit cards, Apple Pay, and ACH (US only).
- **Instant Crypto Delivery**: Eligible payment methods receive instant cryptocurrency delivery after KYC completion.
- **Real-Time Quotes**: Automated pricing and exchange rate quotes for transparent transactions.
- **Webhook Notifications**: Every session status change generates a webhook for real-time transaction tracking.
- **Brand Customization**: Customize the onramp widget to match your application's branding.
- **Pre-Population**: Pre-fill transaction parameters including wallets, amounts, currencies, and networks.
- **Enterprise-Grade Infrastructure**: Built on Stripe's proven payment infrastructure used by millions of businesses.

## Integration Options

Stripe offers three ways to integrate the crypto onramp:

**Stripe-Hosted Onramp**: Redirect customers to a standalone Stripe-hosted page at crypto.link.com. This option requires minimal code and provides quick implementation with some customization options for amounts, currencies, and networks.

**Embedded Onramp**: Embed the onramp directly into your website or mobile webview using the Onramp API. This option provides full brand customization and parameter control while keeping users within your application experience.

**Embedded Components Onramp**: Native Android and iOS mobile integration with the Onramp SDK, offering the most UI customization and a fully native app experience. This option is currently in private preview.

## Getting Started

To integrate Stripe's crypto onramp:

1. **Create a Stripe Account**: Sign up at [stripe.com](https://stripe.com/) or sign in to your existing Stripe account.

2. **Activate Your Account**: Complete Stripe's account activation process if you haven't already.

3. **Submit Onramp Application**: Apply for access to the crypto onramp feature through the Stripe Dashboard. Most applications are reviewed within 48 hours.

4. **Wait for Approval**: Stripe will notify you when your application is approved or if additional information is needed. You can check your application status anytime in the Dashboard.

5. **Choose Integration Method**: After approval, select between Stripe-hosted, embedded web, or mobile SDK integration based on your needs.

6. **Start Development**: Use Stripe's sandbox environment to develop and test your integration without processing real transactions.

7. **Configure Parameters**: Set up your preferred defaults for destination currencies, networks, amounts, and wallet addresses.

8. **Set Up Webhooks**: Configure webhook endpoints to receive real-time notifications about transaction status changes.

9. **Test Thoroughly**: Complete end-to-end testing in the sandbox environment before going live.

10. **Go Live**: Switch to production mode and start offering crypto purchases to your users.

## Lux Support

Stripe's crypto onramp supports both LUX and USDC on the Lux LUExchange-Chain, enabling users to purchase Lux-based assets with fiat currencies. This allows developers building on Lux to leverage Stripe's trusted payment infrastructure and brand recognition to provide a seamless fiat on-ramp experience.

**Note**: LUX and USDC (Lux) are available in the United States (excluding New York) but are not currently supported in EU countries.

## Documentation

For comprehensive integration guides, API references, and implementation details, visit:

- [Stripe Crypto Onramp Documentation](https://docs.stripe.com/crypto/onramp)
- [Embedded Onramp Guide](https://docs.stripe.com/crypto/onramp/embedded-quickstart)
- [Stripe-Hosted Onramp Guide](https://docs.stripe.com/crypto/onramp/stripe-hosted)
- [Onramp API Reference](https://docs.stripe.com/api/crypto/onramp-sessions)
- [Stripe Dashboard](https://dashboard.stripe.com/)

## Use Cases on Lux

Stripe's crypto onramp can enhance Lux applications across multiple verticals:

**Decentralized Applications (Dapps)**: Enable users to purchase LUX or USDC at checkout without leaving your Dapp, reducing friction in the user journey.

**Cryptocurrency Wallets**: Integrate a trusted, compliant on-ramp directly within wallet applications to help users acquire Lux assets.

**DeFi Platforms**: Provide a seamless entry point for users to purchase USDC on Lux for use in lending, borrowing, or trading protocols.

**NFT Marketplaces**: Allow users to purchase LUX or USDC on Lux at checkout to buy NFTs, eliminating the need for users to acquire crypto elsewhere.

**GameFi Applications**: Enable players to purchase in-game tokens or assets on Lux using familiar payment methods like credit cards and Apple Pay.

**Enterprise Applications**: Leverage Stripe's trusted brand and compliance infrastructure for corporate use cases requiring Lux-based transactions.

**Payment Platforms**: Build crypto-enabled payment solutions that allow merchants to accept fiat while settling in LUX or USDC on Lux.

## Geographic Availability

Stripe's crypto onramp is currently available in:

- **United States**: Full support for all payment methods and cryptocurrencies (note: LUX and USDC on Lux not available in New York)
- **European Union**: Available for supported cryptocurrencies (note: LUX and USDC on Lux not currently supported in EU countries)

Availability is subject to regulatory requirements and may expand to additional regions over time.

## Payment Methods

Stripe supports multiple payment methods for crypto purchases:

- **Credit Cards**: Major credit cards for instant crypto delivery after KYC
- **Debit Cards**: Debit card payments with instant crypto delivery after KYC
- **Apple Pay**: Streamlined mobile checkout experience with instant delivery
- **ACH Bank Transfers**: US only, bank account-based payments for larger purchases

All payment methods are eligible for instant crypto delivery after successful KYC completion.

## Pricing

Stripe's pricing for crypto onramp transactions includes:

- **Transaction Fees**: Stripe charges a fee per crypto purchase transaction
- **Payment Processing**: Standard Stripe payment processing fees apply based on payment method
- **No Hidden Fees**: Transparent pricing with no setup fees or monthly minimums
- **Volume Pricing**: Contact Stripe for custom pricing for high-volume applications

For detailed pricing information and custom enterprise arrangements, contact Stripe's sales team through the Dashboard.

## Compliance and Security

Stripe maintains industry-leading compliance and security standards:

- **Regulatory Compliance**: Fully licensed and compliant with US and EU regulations for crypto transactions
- **KYC/AML Verification**: Automated know-your-customer and anti-money laundering screening for all users
- **Sanctions Screening**: Built-in screening against global sanctions lists
- **Fraud Prevention**: Stripe's advanced machine learning-based fraud detection protects all transactions
- **PCI Compliance**: PCI DSS Level 1 certified, the highest level of payment security
- **Data Security**: Enterprise-grade security infrastructure with regular third-party audits
- **Dispute Management**: Stripe handles all disputes and chargebacks, removing liability from platforms
- **Privacy Protection**: Compliant with GDPR, CCPA, and other global privacy regulations

## Why Choose Stripe for Lux

**Trusted Brand**: Stripe is one of the most trusted payment brands globally, processing hundreds of billions of dollars annually for millions of businesses.

**Proven Infrastructure**: Built on Stripe's reliable, scalable payment infrastructure that powers businesses from startups to Fortune 500 companies.

**Simplified Compliance**: Stripe handles all regulatory requirements, reducing legal and compliance burden for your platform.

**Faster Checkout**: Returning users benefit from Stripe Link, which saves payment methods and KYC data for faster repeat purchases.

**Developer-Friendly**: Comprehensive documentation, well-designed APIs, and responsive support make integration straightforward.

**Zero Fraud Liability**: Stripe assumes all fraud liability, protecting your platform from fraudulent transactions.

## Conclusion

Stripe's fiat-to-crypto onramp brings the reliability, trust, and developer experience of Stripe's payment platform to the Lux ecosystem. By handling compliance, fraud prevention, and payment processing, Stripe enables developers to offer seamless crypto purchase experiences without the complexity of building payment infrastructure from scratch. With support for LUX and USDC on Lux, multiple integration options, and zero platform fraud liability, Stripe provides an enterprise-grade solution for any application looking to provide users with easy access to the Lux network. Whether you're building a DeFi platform, NFT marketplace, wallet, or Dapp, Stripe's crypto onramp can significantly reduce friction in user onboarding while maintaining the highest standards of security and compliance.



# SubQuery (/integrations/subquery)

---
title: SubQuery
category: Indexers
available: ["LUExchange-Chain"]
description: SubQuery's decentralized infrastructure makes your dApp lightning quick, infinitely scalable, and absolutely unstoppable.
logo: /images/subquery.webp
developer: SubQuery
website: https://subquery.network/indexer
documentation: https://academy.subquery.network/
---

## Overview

SubQuery is a decentralized data indexing and querying solution designed to provide fast, scalable, and reliable infrastructure for decentralized applications (dApps). Tailored for EVM-compatible chains like Lux's LUExchange-Chain, SubQuery empowers developers to create high-performance dApps with seamless access to blockchain data.

## Features

- **Decentralized Infrastructure**: SubQuery operates on a decentralized network, ensuring high availability and resilience against failures.
- **Lightning-Fast Performance**: Optimized for speed, SubQuery enables dApps to access and query blockchain data quickly and efficiently.
- **Infinite Scalability**: Built to scale with your application, SubQuery handles increasing loads and data volumes without compromising performance.
- **Custom Indexing**: Create custom data indexing solutions that cater to the specific needs of your application.

## Getting Started

To start using SubQuery:

1. **Visit the SubQuery Website**: Explore the features and offerings on the [SubQuery website](https://subquery.network/indexer).
2. **Access the Documentation**: Follow the [SubQuery Documentation](https://academy.subquery.network/) for detailed setup guides and tutorials.
3. **Set Up Indexing**: Implement custom indexing solutions using SubQuery’s tools and infrastructure.
4. **Deploy on LUExchange-Chain**: Use SubQuery to index and query data on the Lux LUExchange-Chain, ensuring high performance for your dApp.
5. **Monitor and Scale**: Utilize SubQuery’s scalable infrastructure to keep your dApp running smoothly as it grows.

## Documentation

For comprehensive guides, tutorials, and support, visit the [SubQuery Academy](https://academy.subquery.network/).

## Use Cases

SubQuery is suitable for:

- **Lux Developers**: Build efficient and scalable dApps on the Lux LUExchange-Chain using SubQuery's indexing solutions.
- **High-Performance dApps**: Ensure your decentralized application can quickly and efficiently query blockchain data.
- **Custom Data Indexing**: Create and deploy custom indexing solutions tailored to your project’s needs.

## Conclusion

SubQuery provides a robust and decentralized solution for data indexing and querying on EVM-compatible blockchains, particularly the Lux LUExchange-Chain. With its lightning-fast performance and infinite scalability, SubQuery is an essential tool for developers looking to build high-performance decentralized applications.



# Subsquid (/integrations/subsquid)

---
title: Subsquid
category: Indexers
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Subsquid is a decentralized data indexing network providing fast, customizable blockchain data access for Web3 applications."
logo: /images/subsquid.png
developer: Subsquid
website: https://www.subsquid.io/
documentation: https://docs.subsquid.io/
---

## Overview

Subsquid is a decentralized data indexing network that provides fast, customizable access to blockchain data. Built for performance and flexibility, Subsquid enables developers to index and query blockchain data efficiently, powering data-intensive Web3 applications with sub-second query response times.

## Features

- **Decentralized Network**: Distributed network of indexers
- **High Performance**: Sub-second query response times
- **Customizable**: Build custom data schemas and transformations
- **Multi-Chain**: Support for Lux and many other chains
- **GraphQL API**: Query data through GraphQL endpoints
- **Real-Time**: Support for real-time data subscriptions

## Getting Started

To use Subsquid:

1. **Install CLI**: Install the Subsquid CLI tools
2. **Create Squid**: Initialize a new squid project
3. **Define Schema**: Create your data schema and processors
4. **Deploy**: Deploy to the Subsquid network
5. **Query**: Access your indexed data via GraphQL

## Documentation

For comprehensive guides, visit [Subsquid Documentation](https://docs.subsquid.io/).

## Use Cases

- **DApp Backends**: Power dApp backends with indexed data
- **Analytics**: Build blockchain analytics platforms
- **NFT Indexing**: Index NFT metadata and ownership
- **DeFi Data**: Track DeFi protocol activity

## Conclusion

Subsquid provides high-performance, decentralized indexing for Lux applications, enabling developers to access blockchain data quickly and build sophisticated data-driven features.


# Sumsub (/integrations/sumsub)

---
title: Sumsub
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: Sumsub is a comprehensive identity verification platform that offers KYC/AML solutions for compliant user onboarding, perfect for txAllowlist implementations.
logo: /images/sumsub.png
developer: Sumsub
website: https://sumsub.com/
documentation: https://docs.sumsub.com/
---

## Overview

Sumsub is a powerful identity verification platform that provides comprehensive KYC (Know Your Customer) and AML (Anti-Money Laundering) solutions for blockchain projects. It offers a streamlined verification process to help businesses ensure regulatory compliance while maintaining a seamless user experience. Sumsub's solutions can be particularly valuable for projects implementing txAllowlist precompiles that need to verify user identities before granting transaction permissions.

## Features

- **Automated Verification Checks**: Sumsub provides a suite of automated verification tools including ID verification, proof of address checks, and watchlist screening.
- **Multi-Channel Verification**: Offers various verification methods including document verification, biometric verification, and liveness detection.
- **AML Screening**: Screens users against global sanctions lists, PEP (Politically Exposed Persons) databases, and adverse media listings.
- **Customizable Workflows**: Build custom verification flows tailored to your specific risk profile and regional requirements.
- **No-Code Integration**: Integrates easily with your platform through WebSDK, MobileSDK, or API connections.
- **Global Compliance**: Ensures compliance with regulations across different jurisdictions worldwide.
- **Fraud Prevention**: Advanced fraud detection technologies to prevent identity theft and account takeovers.

## Getting Started

To integrate Sumsub into your Lux-based application, follow these steps:

1. **Sign Up**: Create an account on the [Sumsub website](https://sumsub.com/).
2. **Configure Verification Flow**: Set up your verification requirements and customize the user flow.
3. **Integrate**: Choose your preferred integration method (WebSDK, MobileSDK, or API) and follow the implementation guides in the [documentation](https://docs.sumsub.com/).
4. **Test**: Use Sumsub's testing environment to ensure the integration works as expected.
5. **Go Live**: Once testing is complete, move to the production environment and begin verifying users.

## Integration with txAllowlist

Sumsub is an excellent choice for projects implementing txAllowlist precompiles on Lux. The txAllowlist precompile restricts who can issue transactions to the chain, making it ideal for permissioned networks where user verification is required. By integrating Sumsub:

1. **KYC/AML Verification**: Users complete verification through Sumsub's interface.
2. **Allowlist Approval**: Upon successful verification, your backend can automatically add the user's address to the txAllowlist.
3. **Transaction Permission**: Verified users can then submit transactions to the chain, while unverified users are blocked.

This creates a compliant, permissioned environment where only KYC-verified users can interact with your blockchain.

## Documentation

For detailed integration guides, API references, and customization options, visit the [Sumsub Documentation](https://docs.sumsub.com/).

## Use Cases

Sumsub is ideal for a variety of Lux-based applications requiring identity verification:

- **Financial Services**: DeFi protocols requiring regulatory compliance.
- **Enterprise Blockchains**: Private or consortium networks that need to verify participant identities.
- **Regulated Markets**: Applications operating in jurisdictions with strict KYC requirements.
- **High-Value Transactions**: Platforms handling significant asset values that need enhanced security.

## Conclusion

Sumsub provides a robust, flexible identity verification solution that integrates seamlessly with Lux's txAllowlist functionality. By combining these technologies, developers can build compliant applications that maintain high security standards while providing a smooth onboarding experience for legitimate users. 

# Supra dVRF (/integrations/supra-vrf)

---
title: Supra dVRF
category: VRF
available: ["LUExchange-Chain", "EVM L1s"]
description: Supra dVRF work behind the scenes to make dApps more engaging, fair, and secure.
logo: /images/supra.png
developer: Supra Labs
website: https://supra.com/
documentation: https://docs.supra.com/dvrf
---

## Overview

For Web3 dApps, you need randomness that's decentralized and verifiably recorded on-chain.

That’s exactly what Supra dVRF solves. With a novel on-chain randomness generation mechanism, Supra’s decentralized dVRF is designed to power dApps with effectively random outcomes that are responsive, scalable, and easily verifiable.

- **Low-Latency Response**: The novel architecture of Supra dVRFs can compute and ship random outcomes in just moments, not minutes.

- **Designed to Scale**: Our network leverages batching to achieve greater network efficiency as well as lower costs.

- **Truly Decentralized**: Supra dVRFs use a secret sharing algorithm to distribute power across multiple nodes, so no one node has the power to compromise your apps or users.

- **Natively Cross-chain**: Supra dVRF solves on-chain randomness for Web3 at large, not just a few networks. We’re already on 27 networks like Aptos, Arbitrum, Lux, Ethereum, Optimism, and Polygon.

## Documentation

1. **Supra dVRF**: Integrate [Supra dVRF](https://docs.supra.com/dvrf/build-with-supra-dvrf/getting-started) for tamper-proof, unbiased, and cryptographically verifiable random numbers to be employed by smart contracts. You can also explore Supra dVRF dashboard [HERE.](https://supra.com/data/dvrf)

2. **Explore Supra's Layer 1**: Check [Docs](https://docs.supra.com/) to start building with the Full Supra Stack.

## Get Started

Supra’s dVRF can provide the exact properties required for a random number generator (RNG) to be fair with tamper-proof, unbiased, and cryptographically verifiable random numbers to be employed by smart contracts.

- **Unbiased and Unpredictable** - The threshold signature of the nonce, client-provided input, and blockhash of the transaction that requests the randomness (which is unknown at the time of request) is used as the seed for the RNG function.

- **Tamper Proof and Verifiable** - Cryptographic proof will be provided to verify that random numbers were generated and communicated with the highest fidelity.

## How to subscribe to consume random numbers:

#### Subscription Model

Think of it like a prepaid phone plan, but for random numbers. You deposit funds upfront, and Supra uses them to pay gas fees for your VRF callbacks.

- **Predictable costs:** Set gas limits upfront, no surprises

- **Simplified contracts:** Your VRF consumer contracts don't need to handle payments

- **Bulk management:** One subscription can serve multiple contracts

- **Reliability:** Reserved minimum balance ensures your requests don't fail due to insufficient funds

#### Why use subscriptions?

- You create a subscription with your wallet address as the manager.

- Deposit funds into your subscription account.

- Register (whitelist) your smart contracts under this subscription.

- When your contracts request random numbers, Supra automatically pays the callback gas fees from your subscription balance.

- No need to handle gas payments in your contract code - it's all automated!

**To start using dVRF, you need to create a subscription that will manage your random number requests and handle gas payments for callbacks. You can create a subscription in two ways: using the new web interface or through on-chain functions.**

1. **Via the web interface**: The easiest way to create your dVRF subscription is through subscription manager UI at [supra.com/data/dvrf.](https://supra.com/data/dvrf)


2. **Via Onchain functions**: For developers who prefer programmatic subscription creation, you can interact directly with the smart contracts.

- EVM Chains

```
// Interface for dVRF 3.0 Deposit Contract
interface IDeposit {
    function addClientToWhitelist(
        uint128 maxGasPrice, 
        uint128 maxGasLimit
    ) external payable;
}
```

- Supra L1

```
// Create subscription on Supra L1
public entry fun create_subscription(
    sender: &signer,
    max_gas_fee: u64,
    initial_deposit: u64
) {
    // Call the deposit module to create subscription
    deposit::add_client_to_whitelist(sender, max_gas_fee);
    deposit::deposit_fund(sender, initial_deposit);
}
```

- **Verification**: Use web interface or getSubscriptionByClient() function, After creating your subscription, verify it's working correctly.

You can explore more on how to Integrate and learn more from our broader [Documentation.](https://docs.supra.com/dvrf/build-with-supra-dvrf/create-your-subscription)


# Supra (/integrations/supra)

---
title: Supra
category: Oracles
available: ["LUExchange-Chain"]
description: "Supra is the first MultiVM Layer 1 with full vertical integration of Native Oracles, dVRF, bridging, automation — creating a unified platform for building Super dApps."
logo: /images/supra.png
developer: Supra Labs
website: https://supra.com/
documentation: https://docs.supra.com/
---

## Overview

Supra is a MultiVM Layer 1. It recorded 500k TPS on 300 nodes with sub-second consensus latency. It's the first chain with full vertical integration of native oracles, DVRF, bridging, automation creating a unified platform for building Super dApps.

## Features

- **Lightning Fast Speeds:** Get better data with near-instant refresh rates with full on-chain finality. We’re on track to become the world’s fastest-to-finality oracle Reaching finality in 600-900ms.
- **Truly Decentralized:** Our oracles are designed to be decentralized at every level, from multi-source data collection to a globally distributed node network.
- **Toughened Security:** Our oracles are designed with a randomized node network along with inbuilt fail-safes to maximize security guarantees.
- **Natively Interoperable:** We’re blockchain agnostic and compatible with over 58 networks like Aptos, Arbitrum, Lux, Ethereum, Optimism, Polygon, and more.
- **Massive Scalability:** We've devised a novel consensus algorithm that can process hundreds of thousands of transactions per second without compromising security.

## Getting Started

1. **Start Building using Supra Oracle**: Refer to the [docs](https://docs.supra.com/oracles) to gain a deeper understanding and detailed guides on integration.
2. **Explore Supra's Layer 1**: Check [Docs](https://docs.supra.com/) to start building with the Full Supra Stack.
3. **Supra dVRF**: Integrate [Supra dVRF](https://docs.supra.com/dvrf/build-with-supra-dvrf/getting-started) for tamper-proof, unbiased, and cryptographically verifiable random numbers to be employed by smart contracts.
4. **Supra Automation**: Check Supra's block level [Automation Docs](https://docs.supra.com/automation) to create financial systems that are responsive, intelligent, and user-friendly without sacrificing decentralization.
5. **SupraNova Bridge**: SupraNova is a cross-chain communication framework developed by Supra. Check [Docs Here](https://docs.supra.com/supranova)

## Documentation

Explore our detailed Oracle Docs for more info on:
- Data Feeds: [CHECK HERE](https://docs.supra.com/oracles/data-feeds)
- APIs For Real time and Historical data: [CHECK HERE](https://docs.supra.com/oracles/apis-real-time-and-historical-data)
- Indices: [CHECK HERE](https://docs.supra.com/oracles/indices)

## Use Cases

1. **For DeFi**
- Instant price feeds for decentralized exchanges
- Monitoring stablecoin collateral values in real-time
- Automatic portfolio rebalancing with accuracy
- Instant tradFi prices for synthetics trading

2. **Gaming**
- Real-time real-world data for prediction markets
- Dynamic and evolving in-game assets
- Monitoring floor prices and marketplaces

3. **Supply Chain**
- Tracking product origin and provenance
- Managing inventory levels and reordering triggers
- Accurate and secure inventory management

4. **Web3 Identity**
- Decentralized identity verification
- Credit scoring and lending risk assessment
- Reputation systems for community platforms

Explore how oracles can help your Web3 project from [HERE](https://supra.com/oracles-product/)

## Conclusion

Supra Oracles is a powerful cross-chain oracle network designed to power dApps across blockchain ecosystems with fast, secure, decentralized, and scalable data solutions. From DeFi to GameFi, our network delivers the data feeds and connections Web3 needs to reach its full potential.



# SushiSwap (/integrations/sushiswap)

---
title: SushiSwap
category: DeFi
available: ["LUExchange-Chain"]
description: "SushiSwap is a multichain automated market maker (AMM) that enables users to trade, earn, and build on Lux's LUExchange-Chain."
logo: /images/sushiswap.jpeg
developer: Sushi
website: https://www.sushi.com/
documentation: https://docs.sushi.com/
---

## Overview

SushiSwap is a leading decentralized exchange (DEX) that operates across multiple chains, including Lux's LUExchange-Chain. It offers users a comprehensive DeFi ecosystem with features including token swapping, yield farming, and liquidity provision. Built on the proven AMM model, SushiSwap provides reliable and efficient trading services while maintaining deep liquidity across various trading pairs.

## Features

- **Multi-Chain Support**: Seamlessly trade assets across different blockchain networks.
- **Trident AMM**: Advanced AMM framework offering multiple pool types for optimal trading.
- **BentoBox**: Innovative vault system for capital efficient lending and borrowing.
- **Yield Strategies**: Various farming opportunities for liquidity providers.
- **Route Processor**: Optimized trading routes for better rates and reduced slippage.
- **Concentrated Liquidity**: Enhanced capital efficiency through targeted liquidity provision.

## Getting Started

To begin using SushiSwap on Lux:

1. **Access Platform**: Visit [Sushi](https://www.sushi.com/) and select Lux network.
2. **Connect Wallet**: Link your Web3 wallet and ensure you have LUX for fees.
3. **Start Trading**: 
   - Choose tokens to swap
   - Review rates and slippage settings
   - Confirm transaction
4. **Earn Yields**: Explore liquidity provision and farming opportunities.

## Documentation

For comprehensive guides and technical documentation, visit the [Sushi Documentation](https://docs.sushi.com/).

## Use Cases

SushiSwap accommodates various DeFi activities:

- **Token Trading**: Efficient swaps with competitive rates and minimal slippage.
- **Liquidity Provision**: Earn fees by providing liquidity to trading pairs.
- **Yield Farming**: Access additional rewards through SUSHI token emissions.
- **Cross-Chain Operations**: Trade and manage assets across multiple networks.
- **DeFi Integration**: Build on top of Sushi's infrastructure using their SDK.

## Conclusion

SushiSwap brings its battle-tested DEX infrastructure to Lux's LUExchange-Chain, offering users access to deep liquidity, efficient trading, and diverse yield opportunities. With its comprehensive feature set and multichain capabilities, SushiSwap provides a robust platform for both casual users and sophisticated DeFi participants on Lux.

# Suzaku (/integrations/suzaku)

---
title: Suzaku
category: Validator Marketplace
available: ["All Lux L1s"]
description: Suzaku is the (re)staking protocol for sovereign networks.
logo: /images/suzaku.png
developer: Suzaku
website: https://suzaku.network
documentation: https://docs.suzaku.network
---

## Overview

Suzaku is the (re)staking protocol for sovereign networks. With the Suzaku Framework, you can bootstrap and increase the cryptoeconomic security of your Lux L1, as well as scale and decentralize its validator set.

## Features

- **Cryptoeconomic security to bootstrap**: Suzaku allows users to secure Lux L1s through (re)staking, enabling liquid staking of L1s' native tokens and dual staking security models with blue-chip tokens like LUX, BTC, and ETH as collateral.
- **Operators to scale and decentralize**: High-tier infrastructure providers and validators offer their services to Lux L1s through Suzaku.
- **An ecosystem of decentralized services**: Some networks, like the [Suzaku Relayer Network](https://docs.suzaku.network/suzaku-rn), are purpose-built to provide critical services (i.e. censorship-resistant interoperability) to other Lux L1s.

## Getting Started

The best way to get started with Suzaku is to go through the [Restaking Guide](https://docs.suzaku.network/suzaku-restaking/for-stakers/restaking-guide).

## Documentation

The Suzaku documentation is available at [https://docs.suzaku.network](https://docs.suzaku.network).

## Use Cases

Lux L1 builders can leverage Suzaku in many different ways. Here are some examples of what you can do with Suzaku:

- **Validator set management**: Open-source security modules to manage your L1 validator set using PoA, PoS, dual-staking, etc.
- **L1 liquid staking**: LST-as-a-service for your Lux L1 and multi-LST liquidity pools.
- **Scaling and decentralization**: Suzaku helps you to scale and decentralize your L1 with high-tier infrastructure providers and validators.
- **Suzaku Relayer Network**: Supercharging Lux Warp Messaging with censorship-resistance and enhanced security for Lux L1 bridges

## Conclusion

Suzaku is the go-to protocol for L1 builders looking to decentralize their network while keeping a high degree of security through (re)staking.


# Synapse Protocol (/integrations/synapse)

---
title: Synapse Protocol
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: Synapse is a cross-chain liquidity network enabling seamless asset bridging and swaps across 20+ blockchain networks with optimized routing and unified liquidity pools.
logo: /images/synapse.jpg
developer: Synapse Protocol
website: https://synapseprotocol.com/
documentation: https://docs.synapseprotocol.com/
---

## Overview

Synapse Protocol is a comprehensive cross-chain liquidity network that enables users and applications to seamlessly transfer assets and execute swaps across 20+ blockchain ecosystems. By combining bridge infrastructure with cross-chain automated market maker (AMM) functionality, Synapse provides optimized routing for cross-chain transactions while maintaining unified liquidity pools that improve capital efficiency and reduce slippage.

With billions in cross-chain volume facilitated and a user-friendly interface trusted by hundreds of thousands of users, Synapse has established itself as one of the leading cross-chain solutions in DeFi. The protocol's focus on security, user experience, and capital efficiency makes it an essential tool for users and developers navigating the multichain ecosystem.

## Features

- **20+ Supported Chains**: Bridge assets across Ethereum, Lux, BNB Chain, Polygon, Arbitrum, Optimism, and more.
- **Cross-Chain Swaps**: Swap assets across chains in a single transaction.
- **Unified Liquidity Pools**: Shared liquidity across all chains improves efficiency.
- **Optimized Routing**: Automatic routing finds the best path for transactions.
- **Stablecoin Bridging**: Specialized in efficient stablecoin cross-chain transfers.
- **Native Asset Support**: Bridge native assets like ETH, LUX, and more.
- **Low Slippage**: Unified pools provide better pricing than fragmented liquidity.
- **Fast Transactions**: Optimized for quick cross-chain transfers.
- **User-Friendly Interface**: Simple, intuitive bridge interface.
- **Liquidity Provision**: Earn fees by providing liquidity to cross-chain pools.
- **SYN Token**: Native token for governance and liquidity incentives.
- **Developer SDK**: Tools for integrating Synapse into applications.

## Core Functionality

### Cross-Chain Bridge

Synapse's bridge enables asset transfers between chains:

**Asset Bridging**: Transfer tokens from any supported chain to another.

**Native Assets**: Bridge native assets without wrapping when possible.

**Stablecoin Focus**: Optimized for USDC, USDT, DAI, and other stablecoins.

**Gas Optimization**: Minimized gas costs for bridging operations.

**Transaction Tracking**: Real-time status updates for all bridges.

### Cross-Chain AMM

Synapse's automated market maker functionality:

**Cross-Chain Swaps**: Swap token A on Chain X for token B on Chain Y.

**Unified Pools**: Liquidity shared across all chains for better pricing.

**Low Slippage**: Deeper liquidity provides better execution.

**Optimal Routing**: Automatically finds best path through pools.

**Swap and Bridge**: Combined swapping and bridging in one transaction.

## Lux Integration

Synapse provides comprehensive Lux support:

**LUX Bridging**: Bridge LUX to and from 20+ other chains.

**Stablecoin Support**: Bridge USDC, USDT, and other stablecoins to Lux.

**DeFi Connectivity**: Connect Lux DeFi to liquidity on other chains.

**Fast Finality**: Leverage Lux's speed for quick bridging.

**Low Fees**: Benefit from Lux's low transaction costs.

**Growing Adoption**: Increasing usage within Lux ecosystem.

## Use Cases

**Cross-Chain DeFi**: Access DeFi opportunities across multiple chains.

**Liquidity Migration**: Move assets between chains as opportunities emerge.

**Multichain Treasury**: Manage treasury assets across multiple blockchains.

**Yield Optimization**: Chase yields across different blockchain ecosystems.

**Bridge Aggregation**: Integrate Synapse into applications for cross-chain functionality.

**Stablecoin Transfers**: Efficiently move stablecoins between ecosystems.

## Liquidity Provision

Earn fees by providing liquidity:

**LP Rewards**: Earn trading fees from bridge and swap users.

**SYN Incentives**: Additional rewards in SYN tokens.

**Multiple Pools**: Provide liquidity to various asset pools.

**Cross-Chain Liquidity**: Single deposit earns fees across all chains.

**Impermanent Loss**: Mitigated through stablecoin-focused pools.

## Getting Started

To use Synapse:

1. **Visit Synapse Bridge**: Go to [synapseprotocol.com](https://synapseprotocol.com/)

2. **Connect Wallet**: Connect your wallet (MetaMask, etc.)

3. **Select Chains**: Choose source and destination chains

4. **Select Assets**: Choose asset to bridge or swap

5. **Review Transaction**: Check routing, fees, and estimated time

6. **Execute**: Complete the cross-chain transaction

For developers, visit [docs.synapseprotocol.com](https://docs.synapseprotocol.com/) for integration guides.

## Security

Synapse maintains strong security:

- Multiple security audits by leading firms
- Bug bounty program
- Regular security assessments
- Monitored by security teams
- Transparent incident response

## Conclusion

Synapse Protocol provides a comprehensive cross-chain solution combining bridge and AMM functionality for efficient asset transfers and swaps across 20+ blockchains including Lux. With unified liquidity pools, optimized routing, and a user-friendly interface, Synapse makes cross-chain DeFi accessible while maintaining security and capital efficiency.



# Tatum (/integrations/tatum)

---
title: Tatum
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Tatum is a blockchain development platform providing unified APIs and SDKs for building Web3 applications across multiple networks."
logo: /images/tatum.png
developer: Tatum
website: https://tatum.io/
documentation: https://docs.tatum.io/
---

## Overview

Tatum is a comprehensive blockchain development platform that simplifies Web3 application development with unified APIs and SDKs. Supporting 40+ blockchain networks including Lux, Tatum enables developers to build, test, and deploy blockchain applications quickly without managing complex infrastructure or learning multiple APIs.

## Features

- **Unified API**: Single API for 40+ blockchains
- **Pre-Built Functions**: Ready-to-use blockchain operations
- **Multi-Language SDKs**: SDKs for JavaScript, Java, PHP, and more
- **Wallet Management**: Create and manage wallets programmatically
- **NFT APIs**: Complete NFT minting and management
- **Virtual Accounts**: Off-chain accounting for scalability

## Getting Started

To use Tatum:

1. **Sign Up**: Create account at [Tatum](https://tatum.io/)
2. **Get API Key**: Access your credentials from dashboard
3. **Choose SDK**: Select SDK for your programming language
4. **Start Building**: Use Tatum APIs to build your application
5. **Deploy**: Launch your Web3 application

## Documentation

For comprehensive guides, visit [Tatum Documentation](https://docs.tatum.io/).

## Use Cases

- **Wallet Applications**: Build multi-chain wallet apps
- **NFT Platforms**: Create NFT minting and marketplace features
- **Token Operations**: Token creation, transfers, and management
- **Exchange Development**: Build trading and exchange features

## Conclusion

Tatum accelerates Lux development with unified APIs and comprehensive tools, enabling developers to focus on building great applications rather than managing blockchain infrastructure.


# Taurus (/integrations/taurus)

---
title: Taurus
category: Custody
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Taurus provides institutional-grade digital asset infrastructure including custody, trading, and tokenization solutions for financial institutions."
logo: /images/taurushq.jpg
developer: Taurus
website: https://www.taurusgroup.ch/
documentation: https://www.taurusgroup.ch/
---

## Overview

Taurus is a Swiss-based provider of digital asset infrastructure designed for banks, asset managers, and financial institutions. The platform offers comprehensive solutions for custody, trading, and tokenization of digital assets, combining institutional-grade security with regulatory compliance. Taurus enables traditional financial institutions to safely enter the digital asset space with enterprise-ready technology.

## Features

- **Regulated Custody**: Swiss-regulated custody solutions meeting institutional standards.
- **Digital Asset Infrastructure**: End-to-end infrastructure for custody, trading, and settlement.
- **Tokenization Platform**: Tools for creating and managing tokenized securities and assets.
- **Multi-Asset Support**: Support for cryptocurrencies, stablecoins, and tokenized securities.
- **Bank-Grade Security**: Military-grade security infrastructure designed for financial institutions.
- **Compliance Framework**: Built-in regulatory compliance for institutional requirements.
- **API Integration**: Comprehensive APIs for seamless system integration.
- **White-Label Solutions**: Customizable infrastructure for institutional branding.

## Documentation

For more information, visit the [Taurus website](https://www.taurusgroup.ch/).

## Use Cases

Taurus serves various institutional infrastructure needs:

- **Banking Services**: Enable banks to offer digital asset services to clients.
- **Asset Management**: Infrastructure for institutional asset managers and fund operators.
- **Tokenization**: Issue and manage tokenized securities and real-world assets.
- **Custody Services**: Regulated custody for institutional portfolios.
- **Trading Infrastructure**: Institutional-grade trading and execution capabilities.

## Conclusion

Taurus provides comprehensive digital asset infrastructure for financial institutions on Lux, offering regulated custody, trading, and tokenization solutions designed specifically for banks and institutional clients operating in traditional finance.



# Tenderly (/integrations/tenderly)

---
title: Tenderly
category: Development Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: Tenderly is a full-stack Web3 infrastructure platform that combines high-performance node services, mainnet-like development environments, and comprehensive developer tools for building, testing, debugging, and scaling decentralized applications with features like real-time monitoring, transaction simulation, and automated security responses.
logo: /images/tenderly.png
developer: Tenderly
website: https://tenderly.co/
documentation: https://docs.tenderly.co/
---

## Overview
Tenderly provides a comprehensive Web3 infrastructure platform designed for developing, testing, and scaling decentralized applications (dApps). 
The platform offers high-performance node RPC services, development environments that mirror mainnet conditions, and an extensive suite of developer tools for monitoring and debugging smart contracts.

## Features
- **[Virtual TestNets](https://docs.tenderly.co/virtual-testnets?mtm_campaign=ext-docs&mtm_kwd=lux)**: Provides mainnet-like development environments for testing and staging smart contracts with unlimited faucet access.
- **[Simulator UI & Debugger](https://docs.tenderly.co/debugger?mtm_campaign=ext-docs&mtm_kwd=lux)**: Offers visual transaction debugging tools that reduce debugging time from hours to minutes.
- **[Simulation RPC](https://docs.tenderly.co/simulations/single-simulations#simulate-via-rpc?mtm_campaign=ext-docs&mtm_kwd=lux)**: Enables accurate prediction of transaction outcomes and gas costs before on-chain execution.
- **[Alerts & Web3 Actions](https://docs.tenderly.co/alerts/intro-to-alerts?mtm_campaign=ext-docs&mtm_kwd=lux)**: Deliver real-time monitoring and automated responses to on-chain events.
- **[Node RPC](https://docs.tenderly.co/node/rpc-reference?mtm_campaign=ext-docs&mtm_kwd=lux)**: Ensures high-performance, low-latency access across multiple regions with enterprise-grade reliability.

## Getting Started
1. **Create an Account**: Sign up at [Tenderly Dashboard](https://dashboard.tenderly.co/register/?mtm_campaign=ext-docs&mtm_kwd=lux)
2. **Set Up a TestNet**: Create a virtual TestNet for your development environment
3. **Access Faucet**: Utilize the unlimited faucet for testing purposes
4. **Explore Documentation**: Review the [official documentation](https://docs.tenderly.co/?mtm_campaign=ext-docs&mtm_kwd=lux)
5. **Integrate Tools**: Implement Tenderly's tools into your development workflow

## Documentation
For comprehensive integration guides, API references, and developer resources, visit [Tenderly Documentation](https://docs.tenderly.co/?mtm_campaign=ext-docs&mtm_kwd=lux).

## Use Cases
Tenderly supports various Web3 development scenarios:
- **Smart Contract Development**: Test and debug contracts in isolated environments
- **Protocol Updates**: Validate protocol upgrades and DAO proposals safely
- **dApp Development and Staging**: Develop, stage, and test smart contracts and entire dApps
- **Security Monitoring**: Implement automated security responses and real-time alerts
- **Transaction Optimization**: Predict and optimize transaction outcomes and gas costs

## Conclusion
Tenderly offers a robust, full-stack Web3 infrastructure solution that enables developers to build, test, and scale decentralized applications efficiently. With its comprehensive toolset and focus on development experience, Tenderly provides essential capabilities for modern Web3 development, from local testing to production deployment and monitoring.

# Tesseract (/integrations/tesseract)

---
title: Tesseract
category: Crosschain Solutions
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Lux's liquidity marketplace enabling seamless asset movement and swaps across Lux and its ecosystem of L1s at lightning speed using ICM and ICTT technology."
logo: /images/tesseract.jpg
developer: Yield Yak Contributors
website: https://www.tesseract.finance/swap
documentation: https://docs.tesseract.finance/
---

## Overview

Tesseract is Lux's premier liquidity marketplace, designed to move and swap assets across Lux and its growing ecosystem of L1s at lightning speed. Built using Lux Interchain Messaging (ICM) and Interchain Token Transfer (ICTT) technology, Tesseract is a trustless, non-custodial, on-chain trading platform that seamlessly connects liquidity between the LUExchange-Chain and Lux's expanding network of Layer 1 blockchains.

By tapping into the entire Lux liquidity ecosystem, LUExchange-Chain and Lux L1 users benefit from getting the best prices on their trades. The platform eliminates the need for L1 operators to deploy their own DEX or manage liquidity pools themselves—with a simple integration, they can access Lux's deep liquidity instantly.

Tesseract is an Lux-native protocol built by the experienced contributors behind the successful Yield Yak platform, and has been audited by leading security firm OpenZeppelin, ensuring robust security and reliability.

## Features

- **Lightning-Fast Cross-Chain Swaps**:
  - Move assets between LUExchange-Chain and L1s at exceptional speed
  - Leverage Lux's fast finality for near-instant settlements
  - Seamless user experience with minimal wait times

- **Unified Liquidity Marketplace**:
  - Access liquidity across the entire Lux ecosystem
  - Best price execution by aggregating liquidity sources
  - No fragmentation between LUExchange-Chain and L1 liquidity

- **Trustless & Non-Custodial**:
  - Built on Lux ICM for trustless interchain communication
  - No intermediaries or custodians required
  - Users maintain full control of their assets

- **ICM & ICTT Technology**:
  - Powered by Lux Interchain Messaging (ICM)
  - Utilizes Interchain Token Transfer (ICTT) for secure asset movement
  - Native integration with Lux's interchain infrastructure

- **Simple L1 Integration**:
  - L1 operators can integrate without deploying a DEX
  - No need to bootstrap or manage liquidity pools
  - Instant access to LUExchange-Chain's deep liquidity

- **Comprehensive Asset Support**:
  - Swap any assets across supported chains
  - Support for native tokens and bridged assets
  - Expanding asset coverage as ecosystem grows

## Core Technology

### Lux ICM Integration

Tesseract leverages Lux's native Interchain Messaging (ICM) protocol:

**Trustless Communication**: ICM provides secure, trust-minimized messaging between Lux chains.

**Native Protocol**: Built on Lux's native interchain infrastructure, not external bridges.

**Fast Finality**: Benefits from Lux's sub-second finality for rapid cross-chain operations.

**Reliable Delivery**: Guaranteed message delivery between connected chains.

### ICTT for Token Transfers

Interchain Token Transfer (ICTT) powers Tesseract's asset movements:

**Secure Transfers**: Cryptographically secure token transfers between chains.

**Native Assets**: Support for native asset transfers without wrapping.

**Efficient Routing**: Optimized routing for minimal gas costs.

**Standardized Protocol**: Uses Lux's standardized token transfer protocol.

### Liquidity Aggregation

Tesseract's intelligent liquidity aggregation:

**Unified Pools**: Access liquidity from multiple sources simultaneously.

**Best Price Discovery**: Automatically finds the best available prices.

**Capital Efficiency**: Maximizes liquidity utilization across the ecosystem.

**Smart Routing**: Intelligent routing algorithms for optimal execution.

## Lux L1 Benefits

Tesseract provides significant advantages for Lux L1 operators:

**Instant Liquidity**: Access LUExchange-Chain liquidity without bootstrapping.

**Zero Infrastructure**: No need to deploy or maintain a DEX.

**Lower Costs**: Avoid expenses of liquidity incentives and pool management.

**Better UX**: Users get access to deep liquidity immediately.

**Focus on Core**: L1 teams can focus on their unique value proposition.

**Easy Integration**: Simple technical integration process.

## Use Cases

Tesseract enables diverse cross-chain scenarios:

**Cross-Chain Trading**: Swap tokens between LUExchange-Chain and any connected L1.

**L1 Ecosystem Access**: Seamlessly move assets into new L1 ecosystems.

**Arbitrage Opportunities**: Take advantage of price differences across chains.

**Portfolio Management**: Rebalance portfolios across multiple chains efficiently.

**Liquidity Provisioning**: Provide liquidity across the entire Lux ecosystem.

**DeFi Strategies**: Execute complex DeFi strategies spanning multiple L1s.

**Asset Bridging**: Bridge assets to L1s for specific applications or use cases.

## Security

Tesseract prioritizes security through multiple measures:

**OpenZeppelin Audit**: Audited by industry-leading security firm OpenZeppelin.

**Battle-Tested Team**: Built by contributors behind Yield Yak's proven track record.

**Native Protocol**: Uses Lux's native ICM instead of external bridges.

**Non-Custodial**: No custody of user funds at any point.

**On-Chain Execution**: All operations executed on-chain with full transparency.

**Continuous Monitoring**: Active monitoring of protocol operations.

## Getting Started

To use Tesseract:

1. **Access Platform**:
   - Visit [Tesseract Finance](https://www.tesseract.finance/swap)
   - Connect your wallet (MetaMask, Core, or other compatible wallets)

2. **Select Networks**:
   - Choose source chain (LUExchange-Chain or any L1)
   - Select destination chain
   - Tesseract will show available liquidity

3. **Execute Swap**:
   - Enter the amount you want to swap
   - Review the route and estimated output
   - Confirm the transaction in your wallet

4. **Track Transfer**:
   - Monitor your cross-chain transfer in real-time
   - Receive assets on destination chain automatically

## For L1 Operators

L1 teams looking to integrate:

1. **Review Documentation**: Visit [Tesseract Docs](https://docs.tesseract.finance/)

2. **Technical Integration**: Follow integration guides for L1 connectivity

3. **Testing**: Test integration on testnet environment

4. **Launch**: Go live and provide instant liquidity access to your users

5. **Community**: Join Tesseract's community channels for support

## Supported Chains

Tesseract connects:

**LUExchange-Chain**: Lux's Contract Chain with deep liquidity.

**Lux L1s**: Growing ecosystem of Lux Layer 1 blockchains.

**Expanding Network**: Continuous addition of new L1 integrations.

Check the [platform](https://www.tesseract.finance/swap) for the current list of supported chains.

## Supported DEXes

Tesseract aggregates liquidity from multiple DEXes:

- Access to major Lux DEXes
- Intelligent routing across multiple sources
- Best price execution guaranteed
- Expanding DEX integrations

Visit the [documentation](https://docs.tesseract.finance/) for the complete list of supported DEXes and L1s.

## Advantages

**Lux-Native**: Built specifically for Lux's architecture and ICM.

**Proven Team**: Developed by contributors behind successful Yield Yak platform.

**Best Prices**: Aggregates liquidity for optimal price execution.

**Lightning Speed**: Leverages Lux's fast finality for quick operations.

**No Wrapping**: Direct asset transfers without wrapped intermediaries.

**Audited Security**: OpenZeppelin audit provides security assurance.

**Simple Integration**: Easy onboarding for L1 operators.

**Growing Ecosystem**: Expanding coverage of L1s and DEXes.

## Community and Support

Tesseract provides comprehensive support:

- **Discord**: Active community for discussions and support
- **Twitter**: Updates and ecosystem announcements
- **Documentation**: Comprehensive guides and technical documentation
- **Developer Channel**: Telegram channel for developers
- **Dune Dashboard**: Analytics and metrics tracking

Visit the [documentation](https://docs.tesseract.finance/) for links to all community channels.

## Developer Resources

For developers building with Tesseract:

**Technical Documentation**: Complete integration guides at [docs.tesseract.finance](https://docs.tesseract.finance/)

**API Access**: APIs for integrating Tesseract into applications

**Smart Contracts**: Open-source smart contracts for review

**Support Channels**: Developer-focused Telegram channel

**Analytics**: Dune Dashboard for protocol metrics

## Conclusion

Tesseract represents a significant advancement in Lux's cross-chain infrastructure, providing a seamless liquidity marketplace that connects LUExchange-Chain and the growing ecosystem of Lux L1s. Built on Lux's native ICM and ICTT technology, Tesseract offers a trustless, non-custodial solution for moving and swapping assets at lightning speed. With its security audit from OpenZeppelin, proven team from Yield Yak, and simple integration process for L1 operators, Tesseract eliminates the traditional barriers to accessing liquidity across chains. Whether you're a user seeking the best prices for cross-chain swaps, an L1 operator looking to provide instant liquidity access to your community, or a developer building on Lux's interchain future, Tesseract provides the essential infrastructure for seamless asset movement across Lux's expanding multichain ecosystem.



# The Graph (/integrations/the-graph)

---
title: The Graph
category: Indexers
available: ["LUExchange-Chain"]
description: The Graph is a decentralized indexing protocol that enables easy querying of blockchain data using GraphQL.
logo: /images/thegraph.png
developer: The Graph
website: https://thegraph.com/
documentation: https://thegraph.com/docs/
---

## Overview

Getting historical data on a smart contract can be frustrating when building a dapp. [The Graph](https://thegraph.com/) provides an easy way to query smart contract data through APIs known as **subgraphs**. The Graph’s infrastructure relies on a decentralized network of indexers, enabling your dapp to become truly decentralized.


## Features

- **Decentralized Indexing**: Enables indexing blockchain data through multiple indexers, thus eliminating any single point of failure
- **GraphQL Queries**: Provides a powerful GraphQL interface for querying indexed data, making data retrieval super simple.
- **Customizable & Reusable**: Define your own logic for transforming & storing blockchain data. Reuse subgraphs published by other developers.
- **Data Aggregation**: Aggregates data from multiple blockchain sources, offering a unified view for easier access and analysis.
- **Scalability**: Designed to handle large volumes of data and scale with the needs of growing dApps and data requirements.


## Getting Started

Building a subgraph only takes a few minutes. It primarily consists of the following steps:

1. Initialize your subgraph project
2. Deploy & Publish
3. Query from your dapp

Here’s a detailed quick-start guide:
https://thegraph.com/docs/en/quick-start/



## Documentation

For detailed instructions on creating subgraphs, querying data, and integrating with The Graph, visit the [The Graph Documentation](https://thegraph.com/docs/).


## Use Cases

The Graph is ideal for a variety of blockchain data needs:

- **Decentralized Applications (dApps)**: Efficiently index and query data for dApps, enabling enhanced functionality and user experiences.
- **Data Aggregation**: Aggregate data from multiple blockchain sources for comprehensive insights and analytics.
- **Data Retrieval**: Provide fast and reliable data retrieval for applications that require access to blockchain data.
- **Analytics and Reporting**: Use The Graph to collect and analyze blockchain data, supporting reporting and decision-making processes.

## Conclusion

The Graph provides a robust solution for indexing and querying blockchain data. It effectively tackles the challenge of reading blockchain data without creating a centralized bottleneck. With its network of indexers, The Graph offers increased redundancy and quicker query responses. Using GraphQL queries, your dApp can pinpoint exactly the fields it requires.



# The TIE (/integrations/thetie)

---
title: The TIE
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "The TIE provides real-time and historical data APIs for Lux, offering sentiment analysis, trading signals, and on-chain metrics through their SigDev Terminal."
logo: /images/thetie.jpg
developer: The TIE
website: https://thetie.io/
documentation: https://docs.thetie.io/
---

## Overview

The TIE's SigDev platform provides developers with access to comprehensive crypto data APIs including Lux-specific metrics, sentiment analysis, and on-chain data. Their SDK enables integration of both real-time and historical data for applications built on Lux.

## Features

- **Data APIs**:
  - Real-time market data
  - Social sentiment analysis
  - On-chain metrics
  - Trading signals
- **Integration Options**:
  - REST API
  - WebSocket feeds
  - Python SDK
  - R SDK
- **Data Types**:
  - Price data
  - Volume analytics
  - Social metrics
  - News sentiment
  - On-chain activity
- **Developer Tools**:
  - API authentication
  - Rate limiting options
  - Data filtering
  - Custom endpoints

## Getting Started

To integrate The TIE's data:

1. **Access Setup**:
   - Register for API access
   - Get API credentials
   - Choose data endpoints
2. **Implementation**:
```python
from thetie import TieClient

client = TieClient(api_key='your-api-key')

# Fetch Lux metrics
lux_data = client.get_metrics(
    asset='LUX',
    metrics=['price', 'volume', 'sentiment'],
    interval='1h'
)
```

## Documentation

For comprehensive API documentation and integration guides, visit [The TIE Documentation](https://docs.thetie.io/).

## Use Cases

The TIE enables:

- **Market Analysis**: Access comprehensive market data
- **Sentiment Tracking**: Monitor social sentiment metrics
- **Trading Applications**: Integrate trading signals and metrics
- **Research Tools**: Build research and analysis platforms
- **Portfolio Analytics**: Track and analyze asset performance

## Conclusion

The TIE provides robust data infrastructure for developers building on Lux, offering comprehensive APIs and SDKs for accessing market, social, and on-chain data. Their tools enable developers to integrate sophisticated data analytics into their applications with reliable and scalable access to multiple data types. 

# Thirdweb x402 (/integrations/thirdweb-x402)

---
title: Thirdweb x402
category: x402
available: ["LUExchange-Chain"]
description: Thirdweb provides an x402 facilitator service that handles verifying and submitting x402 payments on Lux.
logo: /images/thirdweb.png
developer: Thirdweb
website: https://thirdweb.com/
documentation: https://portal.thirdweb.com/payments/x402/facilitator
---

## Overview

Thirdweb's x402 facilitator is a service that handles verifying and submitting x402 payments on Lux's LUExchange-Chain. It uses your own server wallet and leverages EIP-7702 to submit transactions gaslessly, making it easy to integrate payment-gated APIs and AI services.

The thirdweb facilitator is compatible with any x402 backend and middleware libraries like `x402-hono`, `x402-next`, `x402-express`, and more.

## How It Works

- **Verification**: Validates payment signatures and requirements
- **Settlement**: Submits the payment transaction on-chain
- **Gasless**: Uses EIP-7702 for gasless transactions
- **Your Wallet**: Uses your own server wallet for receiving payments

You can view all transactions processed by your facilitator in your thirdweb project dashboard.

## Chain and Token Support

The thirdweb facilitator supports payments on **any EVM chain**, including Lux LUExchange-Chain, as long as the payment token supports either:

- **ERC-2612 permit** (most ERC20 tokens)
- **ERC-3009 sign with authorization** (USDC on all chains)

## Key Features

- **Multi-Chain Support**: Works on Lux LUExchange-Chain and all EVM-compatible chains
- **Gasless Transactions**: Leverages EIP-7702 for user-friendly payment experience
- **Your Own Wallet**: Use your own server wallet to receive payments directly
- **Dashboard Monitoring**: Track all facilitator transactions in your thirdweb dashboard
- **Compatible Middleware**: Works with all x402 middleware libraries

## Getting Started

### Creating a Facilitator

Create a facilitator instance to use with x402 payments:

```typescript
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});
```

### Configuration Options

```typescript
const thirdwebFacilitator = facilitator({
  // Required: Your thirdweb client with secret key
  client: client,
  
  // Required: Your server wallet address that will execute transactions
  // get it from your project dashboard
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
  
  // Optional: Wait behavior for settlements
  // - "simulated": Only simulate the transaction (fastest)
  // - "submitted": Wait until transaction is submitted
  // - "confirmed": Wait for full on-chain confirmation (slowest, default)
  waitUntil: "confirmed",
});
```

## Integration Examples

### Usage with settlePayment()

Use the facilitator with the `settlePayment()` function on Lux:

```typescript
import { settlePayment, facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { lux } from "thirdweb/chains";

const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});

const thirdwebFacilitator = facilitator({
  client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

export async function GET(request: Request) {
  const paymentData = request.headers.get("x-payment");
  
  const result = await settlePayment({
    resourceUrl: "https://api.example.com/premium-content",
    method: "GET",
    paymentData,
    payTo: "0x1234567890123456789012345678901234567890",
    network: lux, // Use Lux LUExchange-Chain
    price: "$0.10",
    facilitator: thirdwebFacilitator, // Pass the facilitator here
  });
  
  if (result.status === 200) {
    return Response.json({ data: "premium content" });
  } else {
    return Response.json(result.responseBody, {
      status: result.status,
      headers: result.responseHeaders,
    });
  }
}
```

### Usage with x402-hono Middleware

Use the facilitator with Hono middleware on Lux:

```typescript
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

const app = new Hono();

// Add the facilitator to the x402 middleware
app.use(
  paymentMiddleware(
    "0xYourWalletAddress",
    {
      "/api/paywall": {
        price: "$0.01",
        network: "lux", // Use Lux mainnet
        config: {
          description: "Access to paid content",
        },
      },
    },
    thirdwebFacilitator, // Pass the facilitator to the middleware
  ),
);

app.get("/api/paywall", (c) => {
  return c.json({ message: "This is premium content!" });
});

export default app;
```

### Usage with x402-express Middleware

Use the facilitator with Express middleware on Lux:

```typescript
import express from "express";
import { paymentMiddleware } from "x402-express";
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

const app = express();

app.use(
  paymentMiddleware(
    "0xYourWalletAddress",
    {
      "GET /api/premium": {
        price: "$0.05",
        network: "lux", // Use Lux mainnet
      },
    },
    thirdwebFacilitator,
  ),
);

app.get("/api/premium", (req, res) => {
  res.json({ content: "Premium AI content" });
});

app.listen(3000);
```

## Getting Supported Payment Methods

Query which payment methods are supported by the facilitator on Lux:

```typescript
// Get all supported payment methods
const allSupported = await thirdwebFacilitator.supported();

// Filter by Lux LUExchange-Chain
const luxSupported = await thirdwebFacilitator.supported({
  chainId: 43114, // Lux LUExchange-Chain
});

// Filter by chain and token (e.g., USDC on Lux)
const usdcOnLux = await thirdwebFacilitator.supported({
  chainId: 43114,
  tokenAddress: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", // USDC on Lux
});
```

## Lux LUExchange-Chain Integration

When using thirdweb's x402 facilitator on Lux's LUExchange-Chain:

- **Chain ID**: 43114 for mainnet, 43113 for Testnet testnet
- **Network String**: Use `"lux"` for mainnet or `"lux-testnet"` for testnet
- **Fast Settlement**: Benefit from Lux's sub-second transaction finality
- **Low Costs**: Enable micropayments with minimal gas fees
- **Dashboard Tracking**: Monitor all Lux transactions in your thirdweb dashboard

## Use Cases

### AI Agent Monetization
Use thirdweb's facilitator to enable AI agents to charge for services on a pay-per-use basis.

### Payment-Gated APIs
Protect your API endpoints with automatic payment verification and settlement.

### Micropayment Services
Enable micropayments for content, data, or compute resources with minimal overhead.

### Multi-Chain AI Services
Build AI services that accept payments across Lux and other EVM chains.

## Documentation

For detailed implementation guides and API references:
- [Thirdweb x402 Facilitator Documentation](https://portal.thirdweb.com/payments/x402/facilitator)
- [Thirdweb Portal](https://portal.thirdweb.com/)

## Conclusion

Thirdweb's x402 facilitator provides a robust infrastructure for handling payment-gated services on Lux's LUExchange-Chain. With gasless transactions, automatic payment verification, and seamless integration with popular middleware libraries, it's the perfect solution for developers building monetized AI services and APIs. Whether you're using Express, Hono, Next.js, or custom implementations, thirdweb's facilitator makes it easy to accept x402 payments on Lux.



# ThirdWeb (/integrations/thirdweb)

---
title: ThirdWeb
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: ThirdWeb provides a low-latency API for generating keys and signing transactions within secure hardware.
logo: /images/thirdweb.avif
developer: ThirdWeb
website: https://thirdweb.com/
documentation: https://portal.thirdweb.com/
---

## Overview

ThirdWeb offers a low-latency API designed for generating keys and signing transactions within secure hardware. This SDK is ideal for developers looking to integrate secure wallet functionalities into their applications, ensuring robust security and efficient performance for managing blockchain transactions.

## Features

- **Low-Latency API**: Provides fast and responsive API access for generating keys and signing transactions.
- **Secure Hardware Integration**: Utilizes secure hardware to protect sensitive information and enhance security.
- **User-Friendly SDK**: Easy-to-integrate SDK with comprehensive documentation and support.
- **Cross-Platform Support**: Compatible with various platforms and blockchain networks, allowing for flexible integration.
- **Enhanced Security**: Ensures high levels of security for key management and transaction signing, reducing vulnerabilities.

## Getting Started

To integrate ThirdWeb into your application:

1. **Visit the ThirdWeb Website**: Explore the [ThirdWeb website](https://thirdweb.com/) to learn more about its SDK and features.
2. **Access the Documentation**: Refer to the [ThirdWeb Documentation](https://portal.thirdweb.com/) for detailed integration guides and API references.
3. **Install the SDK**: Follow the instructions in the documentation to install and configure the ThirdWeb SDK for your project.
4. **Implement Key Generation and Signing**: Use the API to implement key generation and transaction signing functionalities within your application.
5. **Test and Deploy**: Test the integration thoroughly to ensure functionality and security before deploying your application.

## Documentation

For in-depth integration instructions, API details, and support resources, visit the [ThirdWeb Documentation](https://portal.thirdweb.com/).

## Use Cases

ThirdWeb is suitable for various applications requiring secure key management and transaction signing:

- **Wallet Applications**: Integrate secure key management and signing functionalities into digital wallet applications.
- **DeFi Platforms**: Enhance the security and efficiency of transactions within decentralized finance (DeFi) applications.
- **Blockchain Games**: Implement secure transaction signing for in-game assets and interactions.
- **Financial Services**: Provide secure transaction management for blockchain-based financial services.

## Conclusion

ThirdWeb delivers a powerful SDK for integrating low-latency key generation and transaction signing within secure hardware. With its focus on security and performance, ThirdWeb is a valuable tool for developers seeking to enhance the safety and efficiency of blockchain transactions across various applications. Whether you're building a wallet app, a DeFi platform, or a blockchain-based game, ThirdWeb provides the tools needed for secure and effective integration.



# Token Relations (/integrations/token-relations)

---
title: Token Relations
category: Analytics & Data
available: ["LUExchange-Chain"]
description: "Token Relations provides advanced token analytics, relationship mapping, and on-chain data insights for the Lux ecosystem."
logo: /images/token-relations.png
developer: Token Relations
website: https://www.token-relations.com/
documentation: https://www.token-relations.com/
---

## Overview

Token Relations is an advanced analytics platform that provides comprehensive token data, relationship mapping, and on-chain insights for the Lux ecosystem. The platform helps developers, analysts, and investors understand token dynamics, holder relationships, and market behavior through sophisticated data analysis.


# Tokeny (/integrations/tokeny)

---
title: Tokeny
category: Tokenization Platforms
available: ["LUExchange-Chain"]
description: Tokeny (now part of Apex Group) is a leading onchain finance platform enabling financial institutions to securely and compliantly issue, manage, and distribute tokenized securities using the ERC-3643 standard.
logo: /images/tokeny.png
developer: Tokeny / Apex Group
website: https://tokeny.com/
documentation: https://docs.tokeny.com/
---

## Overview

Tokeny is a pioneering onchain finance platform that has become part of the Apex Group, one of the world's largest fund administration firms. Tokeny specializes in enabling financial institutions to issue, manage, and distribute tokenized securities in a fully compliant manner using enterprise-grade infrastructure. As a leader in developing and promoting the ERC-3643 standard (formerly T-REX), Tokeny provides the most widely adopted protocol for compliant security tokens.

With Tokeny's platform, financial institutions can tokenize various asset classes—including funds, bonds, equities, and structured products—while maintaining full regulatory compliance through built-in identity management, transfer restrictions, and automated compliance rules. Now backed by Apex Group's global reach and $2 trillion+ in assets under administration, Tokeny combines cutting-edge blockchain technology with institutional trust to accelerate the adoption of digital securities.

## Features

- **ERC-3643 Standard**: Built on the industry-leading standard for compliant tokenized securities with built-in identity and compliance layers.
- **Enterprise-Grade Platform**: Institutional infrastructure designed for banks, asset managers, and financial institutions.
- **Multi-Asset Tokenization**: Support for tokenizing funds, bonds, equities, real estate, structured products, and alternative assets.
- **Onchain Identity Management**: Decentralized identity system (ONCHAINID) for compliant investor verification and management.
- **Automated Compliance**: Smart contract-based transfer restrictions ensuring regulatory compliance at the protocol level.
- **Regulatory Flexibility**: Adaptable to different jurisdictions including EU MiFID II, US regulations, and other international frameworks.
- **Investor Portal**: White-label investor portal for KYC, subscription, and portfolio management.
- **Transfer Agent Services**: Digital transfer agent capabilities for shareholder recordkeeping and corporate actions.
- **Distribution Network**: Connect to a network of regulated distributors and platforms.
- **Multi-Chain Support**: Deploy tokenized securities across multiple EVM-compatible blockchain networks.
- **Lifecycle Management**: Complete token lifecycle from issuance through corporate actions to redemption.
- **Interoperability**: Open standard enabling integration with multiple platforms and service providers.
- **API and SDK**: Comprehensive developer tools for custom integrations.
- **Security Audits**: Thoroughly audited smart contracts with formal verification.

## Getting Started

To work with Tokeny:

1. **For Financial Institutions and Issuers**:
   - Contact Tokeny (now Apex Group Digital Assets) to discuss tokenization requirements
   - Define the assets or securities to be tokenized
   - Structure the digital securities with Tokeny's legal and technical team
   - Implement the ERC-3643 token standard with compliance rules
   - Set up investor identity and verification workflows
   - Launch the tokenized offering on selected blockchain network(s)
   - Utilize Tokeny's lifecycle management tools for ongoing operations

2. **For Investors**:
   - Access tokenized securities through Tokeny-powered platforms
   - Complete KYC through the ONCHAINID identity system
   - Verify accreditation status and jurisdiction eligibility
   - Invest in available tokenized securities
   - Manage holdings through issuer's investor portal

3. **For Developers and Integrators**:
   - Explore ERC-3643 documentation and reference implementations
   - Use Tokeny's SDKs and APIs to build on the standard
   - Deploy compliant tokenized securities using the protocol
   - Integrate with existing systems and platforms

## ERC-3643 Standard

The ERC-3643 standard (formerly T-REX) is the most widely adopted protocol for compliant security tokens:

**Identity Layer**: Onchain identity management with verified credentials and claims.

**Compliance Layer**: Smart contract-based transfer restrictions and compliance rules.

**Modular Architecture**: Flexible design allowing customization for different regulatory requirements.

**Permissioned Transfers**: Transfers automatically check compliance before execution.

**Claim System**: Decentralized verification of investor attributes (accreditation, jurisdiction, etc.).

**Standard Adoption**: Industry standard supported by multiple platforms and service providers.

The ERC-3643 standard ensures that tokenized securities remain compliant across their entire lifecycle while enabling interoperability between platforms.

## Lux Support

Tokeny's platform supports deployment on multiple EVM-compatible blockchain networks, including Lux LUExchange-Chain. The ERC-3643 standard is chain-agnostic, allowing issuers to leverage Lux's high performance, low fees, and robust infrastructure for deploying compliant tokenized securities.

## Use Cases

Tokeny enables tokenization across diverse asset classes:

**Investment Funds**: Tokenize mutual funds, hedge funds, and private equity funds to improve accessibility and reduce operational costs.

**Corporate Bonds**: Issue digital bonds with automated interest payments and enhanced liquidity.

**Equity Securities**: Tokenize private company shares with embedded compliance and shareholder management.

**Real Estate**: Create fractionalized ownership of real estate assets with regulatory compliance.

**Structured Products**: Issue complex financial instruments as programmable tokens.

**Sustainable Finance**: Tokenize green bonds and ESG-focused investment products.

**Private Debt**: Digitize loan participations and private credit instruments.

## Apex Group Integration

As part of Apex Group, Tokeny benefits from:

**Global Scale**: Apex Group manages over $2 trillion in assets with 14,000+ employees across 75 offices.

**Fund Administration**: Integration with Apex's comprehensive fund administration services.

**Regulatory Expertise**: Deep experience across multiple jurisdictions and asset classes.

**Institutional Trust**: Relationship with major global financial institutions.

**Comprehensive Services**: Combined offering of tokenization, fund admin, custody, and distribution.

**Market Access**: Leverage Apex's global distribution network.

This combination positions Tokeny as the institutional choice for tokenization infrastructure.

## Technology Stack

Tokeny provides comprehensive technology infrastructure:

- **Smart Contract Suite**: Audited ERC-3643 contracts with modular compliance rules
- **ONCHAINID**: Decentralized identity protocol for investor verification
- **Token Factory**: Self-service tools for deploying tokenized securities
- **Compliance Engine**: Configurable rules engine for regulatory requirements
- **Agent Dashboard**: Interface for managing tokens, investors, and corporate actions
- **Investor Portal**: White-label portal for subscriptions and portfolio management
- **API Platform**: RESTful APIs for system integration
- **Blockchain Nodes**: Infrastructure for reliable blockchain connectivity
- **Data Analytics**: Reporting and analytics tools for issuers and regulators

## Regulatory Compliance

Tokeny's platform addresses complex regulatory requirements:

- **Multi-Jurisdictional**: Adaptable to EU, US, Asia-Pacific, and other regulatory frameworks
- **MiFID II Compliant**: European securities regulation compliance
- **SEC Compliant**: Support for US Regulation D, Regulation S, and Regulation A+
- **FINMA Compatible**: Swiss financial market regulations
- **GDPR Compliant**: European data protection standards
- **Flexible Rules**: Customizable compliance rules for specific regulatory requirements
- **Audit Trail**: Complete on-chain and off-chain audit trails for regulators

## Competitive Advantages

**Industry Standard**: ERC-3643 is the most widely adopted protocol for security tokens.

**Institutional Backing**: Part of Apex Group with $2T+ AUA and global operations.

**Open Architecture**: Interoperable standard avoiding vendor lock-in.

**Proven Technology**: Years of production use with multiple successful tokenizations.

**Regulatory First**: Compliance built into the protocol, not bolted on afterwards.

**Developer Friendly**: Open-source standard with extensive documentation.

**Multi-Chain**: Deploy on any EVM-compatible blockchain including Lux.

## Tokenization Services

Tokeny (through Apex Group) provides end-to-end services:

- **Structuring Advisory**: Legal and financial structuring of tokenized securities
- **Technical Implementation**: Smart contract deployment and configuration
- **Compliance Setup**: Configuration of regulatory rules and restrictions
- **Investor Onboarding**: KYC/AML processes and identity verification
- **Distribution**: Access to regulated distribution channels
- **Lifecycle Management**: Ongoing token management and corporate actions
- **Reporting**: Regulatory reporting and investor communications
- **Secondary Markets**: Integration with trading venues and marketplaces

## Pricing

Tokeny offers institutional pricing:

- **Setup Fees**: Initial tokenization and platform setup costs
- **Annual Platform Fees**: Ongoing access to technology and infrastructure
- **Transaction Fees**: Fees for certain operations and transfers
- **Service Fees**: Additional services like fund administration through Apex Group
- **Custom Solutions**: Tailored pricing for large institutions and complex requirements

Contact Tokeny/Apex Group Digital Assets for detailed pricing.

## Conclusion

Tokeny, now part of Apex Group, represents the convergence of blockchain innovation and institutional finance. Through the ERC-3643 standard and comprehensive platform infrastructure, Tokeny enables financial institutions to tokenize assets with full regulatory compliance and institutional-grade security. With support for multiple blockchains including Lux, Tokeny provides the flexibility to deploy tokenized securities on high-performance networks while maintaining compliance and interoperability. Whether you're a fund manager, corporate issuer, or financial institution looking to explore digital securities, Tokeny's proven platform, industry-standard protocol, and backing by Apex Group provide the trusted infrastructure needed to successfully transition to onchain finance.



# TomNext (/integrations/tomnext)

---
title: TomNext
category: Tokenization Platforms
available: ["LUExchange-Chain"]
description: TomNext is a discovery and management platform for wealth managers, advisors, and qualified investors to evaluate and access tokenized alternative assets across multiple issuers and blockchain networks.
logo: /images/tomnext.jpg
developer: TomNext
website: https://www.tomnext.co/
documentation: https://www.tomnext.co/platform
---

## Overview

TomNext is building the essential distribution infrastructure for the tokenized alternatives market, providing a comprehensive platform where wealth managers, registered investment advisors (RIAs), and qualified investors can discover, evaluate, and manage tokenized alternative assets. While many platforms focus on issuing tokenized securities, TomNext addresses the critical missing piece in the tokenization landscape: distribution and investor access.

The TomNext platform serves as a centralized hub where investors can access a growing universe of tokenized investment products from multiple issuers across various product categories and blockchain networks. With a streamlined user interface enhanced by AI-powered analysis tools, TomNext aims to be for tokenized alternatives what Interactive Brokers is for equities or what Coinbase is for cryptocurrency—the go-to platform for discovering and accessing this emerging asset class.

## Features

- **Multi-Issuer Platform**: Access tokenized products from numerous issuers in one unified interface.
- **Broad Asset Coverage**: Discover tokenized alternatives across real estate, private equity, credit, funds, and other categories.
- **Cross-Chain Compatibility**: View and access tokens deployed across multiple blockchain networks.
- **AI-Powered Analysis**: Advanced analytical tools using artificial intelligence to evaluate tokenized assets.
- **Due Diligence Tools**: Comprehensive tools for assessing tokenized investment opportunities.
- **Portfolio Management**: Unified dashboard for tracking tokenized alternative holdings.
- **Streamlined UI**: User-friendly interface designed for traditional wealth managers and investors.
- **Comparison Tools**: Side-by-side comparison of different tokenized products and issuers.
- **Research and Insights**: Market intelligence and research on tokenization trends and opportunities.
- **RIA Platform Integration**: Compatibility with traditional RIA and wealth management platforms.
- **Qualified Investor Focus**: Platform designed for accredited and institutional investors.
- **Discovery Engine**: Search and filter tools to find relevant tokenized investment opportunities.
- **Transparency**: Clear information on fees, terms, underlying assets, and issuer details.
- **Educational Resources**: Learning materials about tokenization and alternative assets.

## Getting Started

### For Wealth Managers and RIAs:

1. **Platform Access**: Request access to the TomNext platform by contacting their team.

2. **Account Setup**: 
   - Register your advisory firm on the platform
   - Complete necessary verification and compliance processes
   - Set up user accounts for advisors

3. **Platform Exploration**:
   - Discover available tokenized alternative assets
   - Use AI tools to analyze investment opportunities
   - Compare products across different issuers
   - Conduct due diligence using platform tools

4. **Client Integration**:
   - Onboard qualified clients to the platform
   - Help clients complete accreditation verification
   - Build tokenized alternative allocations for client portfolios
   - Monitor and manage client holdings

5. **Portfolio Management**:
   - Track performance of tokenized investments
   - Rebalance portfolios as needed
   - Access reporting for client communications

### For Qualified Investors:

1. **Platform Registration**: Sign up on the TomNext platform directly or through your wealth manager.

2. **Accreditation Verification**: Complete accredited or qualified investor verification process.

3. **Asset Discovery**: Browse the growing universe of tokenized alternative investments available on the platform.

4. **Due Diligence**: Use TomNext's AI-powered tools to analyze and evaluate investment opportunities.

5. **Investment**: Allocate capital to selected tokenized products through the platform.

6. **Portfolio Tracking**: Monitor your tokenized alternative holdings and performance in real-time.

## Lux Support

TomNext's cross-chain platform architecture supports tokenized assets deployed across multiple blockchain networks, including Lux LUExchange-Chain. As the platform aggregates tokenized products regardless of which blockchain they're issued on, investors and advisors can access Lux-based tokenized securities alongside those on other chains through TomNext's unified interface.

## Tokenized Asset Categories

TomNext provides access to various tokenized alternative asset types:

**Tokenized Real Estate**: Fractional ownership in commercial properties, residential properties, REITs, and real estate funds.

**Private Equity**: Tokenized shares in private equity funds and direct investments in private companies.

**Private Credit**: Tokenized debt instruments, credit funds, and lending products.

**Hedge Funds**: Digital shares in alternative investment funds pursuing various strategies.

**Infrastructure**: Tokenized infrastructure projects and assets.

**Art and Collectibles**: Fractional ownership in high-value art, wine, and other collectibles.

**Commodities**: Tokenized exposure to physical commodities and commodity-backed products.

**Structured Products**: Tokenized structured notes and complex financial instruments.

## Use Cases

TomNext serves multiple stakeholders in the wealth management ecosystem:

**Registered Investment Advisors (RIAs)**: Access tokenized alternatives to diversify client portfolios beyond traditional stocks and bonds.

**Wealth Management Platforms**: Integrate tokenized alternatives into existing wealth management technology stacks.

**Family Offices**: Discover and manage tokenized alternative investments for ultra-high-net-worth families.

**Qualified Individual Investors**: Self-directed accredited investors seeking direct access to tokenized alternatives.

**Institutional Investors**: Foundations, endowments, and institutions exploring tokenization.

**Multi-Family Offices**: Platforms serving multiple wealthy families needing tokenized asset access.

## Platform Capabilities

### Discovery and Search

- **Advanced Filters**: Filter by asset class, blockchain, minimum investment, expected returns, duration, and more
- **Issuer Information**: Comprehensive profiles of tokenization platforms and issuers
- **Product Details**: Detailed offering documents, terms, and underlying asset information
- **Market Trends**: Insights into tokenization market trends and popular products

### AI-Powered Analysis

- **Risk Assessment**: AI-driven analysis of investment risks across tokenized products
- **Performance Projections**: Data-driven expectations for returns and distributions
- **Comparative Analysis**: AI-powered comparison across similar products
- **Portfolio Optimization**: Suggestions for optimal tokenized alternative allocations
- **Document Analysis**: AI extraction of key information from lengthy offering documents

### Portfolio Management

- **Unified Dashboard**: See all tokenized holdings across multiple issuers and blockchains
- **Performance Tracking**: Real-time monitoring of tokenized investment performance
- **Distribution Tracking**: Automatic tracking of dividends, interest, and other distributions
- **Reporting**: Generate reports for clients, compliance, and tax purposes
- **Alerts**: Notifications about important events affecting holdings

### Integration Capabilities

- **RIA Platform Connectivity**: Integration with traditional wealth management platforms
- **Custody Integration**: Connect with digital asset custodians
- **Accounting Systems**: Export data to accounting and portfolio management software
- **CRM Integration**: Connect to advisor CRM systems
- **API Access**: APIs for building custom integrations and workflows

## Market Need

TomNext addresses several critical gaps in the tokenization ecosystem:

**Fragmented Market**: Tokenized products are scattered across many issuers and platforms—TomNext aggregates them.

**Discovery Challenge**: Investors struggle to find relevant tokenized opportunities—TomNext provides comprehensive search.

**Analysis Complexity**: Evaluating tokenized securities is difficult—TomNext offers AI-powered tools.

**Multi-Chain Confusion**: Assets span multiple blockchains—TomNext provides a unified view.

**Traditional Advisor Barriers**: Wealth managers lack tools for tokenized assets—TomNext builds for RIAs.

## Competitive Position

**Distribution Focus**: While others build issuance platforms, TomNext focuses on distribution and investor access.

**Multi-Issuer**: Aggregates products from many issuers rather than competing with them.

**AI-Enhanced**: Leverages artificial intelligence to simplify complex analysis.

**Traditional Finance Bridge**: Specifically designed for traditional wealth managers and RIAs, not just crypto natives.

**Comprehensive Solution**: End-to-end platform from discovery through portfolio management.

**Cross-Chain**: Blockchain-agnostic approach serves the entire tokenization market.

## Regulatory Considerations

TomNext operates with attention to regulatory requirements:

- **Broker-Dealer Relationships**: Partnerships or registrations to facilitate transactions
- **Accreditation Verification**: Processes to confirm qualified investor status
- **Securities Compliance**: Platform design accommodates securities regulations
- **Privacy and Data Protection**: Secure handling of investor information
- **Cross-Border**: Consideration of international regulations as market expands

## Vision and Mission

**Mission**: Democratize access to tokenized alternative investments by building the distribution infrastructure that connects investors with opportunities.

**Vision**: Become the standard platform for discovering, analyzing, and managing tokenized alternatives—the Bloomberg Terminal for tokenized assets.

**Philosophy**: The tokenization revolution will only reach its potential when distribution matches issuance capabilities.

## Benefits for the Tokenization Ecosystem

**For Issuers**: Access to qualified investor base seeking tokenized products.

**For Investors**: Centralized access to fragmented market of tokenized alternatives.

**For Advisors**: Professional tools to serve clients interested in tokenization.

**For the Industry**: Necessary distribution infrastructure to scale tokenization market.

## Pricing

TomNext pricing structure (contact for details):

- **Platform Fees**: Subscription or transaction-based fees for platform access
- **Management Tools**: Fees for portfolio management and reporting capabilities
- **AI Analysis**: Potential fees for advanced AI-powered analytical tools
- **Integration Fees**: Costs for connecting to RIA platforms and systems
- **Transaction Fees**: Possible fees on investments made through the platform

Contact TomNext for specific pricing based on firm size and needs.

## Conclusion

TomNext is building essential infrastructure for the tokenized alternatives market by focusing on the distribution layer that has been largely overlooked. By providing wealth managers, RIAs, and qualified investors with a comprehensive platform to discover, evaluate, and manage tokenized assets across multiple issuers and blockchain networks including Lux, TomNext addresses a critical gap preventing mainstream adoption of tokenization. With AI-powered analysis tools and an interface designed for traditional finance professionals, TomNext makes tokenized alternatives accessible to the vast pool of capital managed by RIAs and wealth managers. As the tokenization market matures, distribution platforms like TomNext will be essential to connecting the growing supply of tokenized products with investor demand, ultimately realizing the vision of a more accessible and efficient alternative investment market.



# Traceye (/integrations/traceye)

---
title: Traceye
category: Indexers
available: ["LUExchange-Chain"]
description: Traceye is a full-stack Blockchain indexing platform supporting multiple indexing protocols like 'The Graph' and 'Subquery Network'.
logo: /images/traceye.png
developer: Traceye
website: https://traceye.io/
documentation: https://doc.traceye.io
---

## Overview

Traceye is an indexing platform designed specifically to address the needs Lux L1s. The platform leverages popular indexing protocols like 'The Graph' and 'Subquery Network' on shared and dedicated infrastructure to provide both cost-effective & enterprise grade indexing solutions. Traceye also provides a host of developer addons built on top of indexers to aid in app development.

## Features

- **Zero-Cost Indexer Development**: Traceye offer free consulting and development of data indexers tailored exclusively for Lux Layer 1 chains. Get started without upfront costs or vendor lock-in.
- **High Availability**: Enjoy ultra-fast indexing, minimal data lag, and 99.99% uptime — all without the hassle of infrastructure maintenance.
- **Configurable Webhooks**: Set up real-time webhooks on any indexed entity.
- **BI Reporting & Charts Engine**: Built-in business intelligence engine for creating visual reports, dashboards, and charts directly from indexed data.
- **One-Click Web3 API Launch**: Instantly generate and deploy Web3 Data APIs with a single click — optimized for L1 chains, no backend coding required.
- **Bring Your Own RPC**: Connect your preferred Lux RPC endpoints for enhanced flexibility and control over indexing behavior.
- **Custom Business Logic & Direct DB Access**: Define custom entities, apply business logic, and access your data directly from the underlying database.
- **Query & Database Optimizer**: Leverage our smart query optimizer and schema tuning tools for low-latency responses and efficient data retrieval.
- **Observability & Tracking**: Built-in notifications, versioning, logs, and entity tracking.
- **Infrastructure Monitoring & Alerts**: Real-time infrastructure health checks, performance metrics, and alerting system to keep your deployment healthy and responsive.

## Getting Started

To begin using Traceye, follow these steps:

1. Visit the [Traceye website](https://app.traceye.io/) : Sign-up or log-in to access the platform.
2. Left-side menu provides options for shared and dedicated indexing along with 1-click Web3 data APIs for L1 chains.
3. Scroll to the appropriate option based on requirement and access the dashboard. Use the 'Buy Subscription' option to purchase subscription or get a free plan.
4. Once subscription is set, launch the indexer or Web3 data APIs.
5. Connect with us for free consulting & indexer development on L1.

## Documentation

For detailed guides and API references visit the [Traceye documentation](https://doc.traceye.io).

## Use Cases

Traceye is ideal for various blockchain projects and applications:

- **Public L1 Chains**: Expose GraphQL and REST APIs for core Web3 data including NFTs, Tokens, Wallets, Blocks & Transactions. Perfect for explorers, analytics platforms, and dApps needing standardized access to on-chain data.
- **Appchains**: Enable custom indexers tailored to the specific data requirements of appchains — whether it's gaming, identity, or specialized DeFi use cases.
- **DeFi & dApps**: Index and serve data from custom smart contracts powering DeFi protocols or decentralized applications.
- **Blockchain Analytics**: Leverage Traceye’s BI and reporting engine to generate insights through comprehensive dashboards covering chain-wide activity, DeFi/dApp usage, and historical on-chain trends.
- **Programmable On-Chain Actions**: Trigger real-time workflows using webhooks on top of Indexers configured on specific on-chain events.

## Conclusion

Traceye is user-friendly essentially one stop shop for all your L1 blockchain data requirements whether is standard Web3 Data APIs like NFT, Token, Transaction, Wallet APIs etc. or custom data requirements based on Smart-contract, it has got you covered. Moreover, Traceye offers free of cost consulting and indexer development exclusively for L1s so you can get started immediately.


# Trail of Bits (/integrations/trailofbits)

---
title: Trail of Bits
category: Audit Firms
available: ["LUExchange-Chain"]
description: Trail of Bits is a leading security research firm providing smart contract audits, blockchain security assessments, and advanced security tooling for enterprise and Web3 protocols.
logo: /images/trailofbits.png
developer: Trail of Bits
website: https://www.trailofbits.com/
documentation: https://www.trailofbits.com/services
---

## Overview

Trail of Bits is one of the most respected security research and development firms in the blockchain industry, known for their rigorous security audits, cutting-edge security tools, and deep expertise in cryptography and systems security. Founded in 2012, Trail of Bits has audited hundreds of blockchain protocols, smart contracts, and cryptographic implementations for leading projects, enterprises, and government agencies.

With a team of world-class security researchers, Trail of Bits combines academic rigor with practical security expertise to identify vulnerabilities that others miss. Their work spans smart contract audits, protocol design reviews, cryptographic analysis, and custom security tool development. Trail of Bits is trusted by the largest names in blockchain including Ethereum Foundation, USDC, and major DeFi protocols.

## Services

- **Smart Contract Audits**: Comprehensive security audits using both manual and automated analysis.
- **Protocol Security Reviews**: Assessment of protocol design and architecture.
- **Cryptographic Review**: Analysis of cryptographic implementations and algorithms.
- **Security Tool Development**: Custom tools for continuous security monitoring.
- **Formal Verification**: Mathematical proofs of smart contract correctness.
- **Incident Response**: Emergency security assessment and remediation.
- **Security Training**: Educational programs for development teams.
- **Continuous Monitoring**: Ongoing security surveillance post-deployment.
- **Penetration Testing**: Adversarial testing of protocols and infrastructure.
- **Supply Chain Security**: Assessment of dependencies and third-party code.

## Proprietary Security Tools

Trail of Bits has developed industry-leading open-source security tools:

**Slither**: Static analysis framework for Solidity with dozens of vulnerability detectors.

**Echidna**: Property-based fuzzer for Ethereum smart contracts.

**Manticore**: Symbolic execution tool for analyzing smart contracts.

**Crytic**: Commercial platform combining multiple analysis tools.

**Rattle**: EVM binary static analysis framework.

These tools represent the cutting edge of automated smart contract security analysis.

## Audit Methodology

Trail of Bits follows a comprehensive audit process:

1. **Threat Modeling**: Identify assets, threats, and attack surfaces
2. **Automated Analysis**: Run Slither, Echidna, and other tools
3. **Manual Review**: Expert manual code review by senior researchers
4. **Formal Verification**: Prove critical properties mathematically when applicable
5. **Attack Simulation**: Test protocols under adversarial conditions
6. **Documentation Review**: Assess documentation completeness and accuracy
7. **Report Generation**: Comprehensive report with prioritized findings
8. **Remediation Support**: Work with team to address issues
9. **Verification Audit**: Confirm fixes before final report

## Lux Expertise

Trail of Bits has extensive experience securing protocols across all major blockchain networks including Lux. Their expertise covers:

- Lux LUExchange-Chain smart contracts
- Cross-chain bridge security
- Subnet architecture review
- Consensus mechanism analysis
- High-throughput protocol optimization
- Lux-specific attack vectors

## Access Through Areta Marketplace

Lux projects can engage Trail of Bits through the [Areta Audit Marketplace](https://areta.market/lux):

- **Competitive Quotes**: Receive proposals from Trail of Bits alongside other top firms
- **Transparent Pricing**: Clear pricing without intermediaries
- **Fast Matching**: Get connected within 48 hours
- **Subsidy Eligibility**: Qualify for up to $10k in audit subsidies
- **Streamlined Process**: Simplified procurement compared to direct engagement
- **Ecosystem Focus**: Marketplace designed specifically for Lux builders

## Notable Clients

Trail of Bits has audited protocols for:

- Ethereum Foundation
- USDC (Centre/Circle)
- MakerDAO
- Compound
- Uniswap
- Chainlink
- U.S. Department of Defense
- Major financial institutions
- Fortune 500 companies

This track record demonstrates their capability to handle the most critical security assessments.

## Audit Focus Areas

**DeFi Security**: DEXs, lending protocols, derivatives, and yield strategies.

**Infrastructure**: L1/L2 protocols, bridges, and consensus mechanisms.

**Cryptography**: Novel cryptographic schemes and implementations.

**Enterprise Blockchain**: Private and permissioned blockchain solutions.

**Gaming & NFTs**: Gaming protocols and NFT platforms.

**Stablecoins**: Stablecoin mechanisms and implementations.

**Governance**: DAO governance and voting systems.

## Research and Publications

Trail of Bits actively contributes to blockchain security research:

- Regular security blog posts and advisories
- Conference presentations at Black Hat, DEF CON, and academic venues
- Open-source security tools with thousands of users
- Collaboration with academic institutions
- Industry security standards development

## Why Choose Trail of Bits

**Industry Leader**: Most respected security firm in blockchain with decade+ track record.

**Research Excellence**: Team of PhDs and security researchers pushing the field forward.

**Tool Development**: Creators of industry-standard security analysis tools.

**Comprehensive Approach**: Combination of automated and manual analysis techniques.

**Formal Methods**: Capability to provide formal verification when needed.

**Government Trust**: Trusted by government agencies for critical security work.

**Enterprise Experience**: Experience securing enterprise and institutional-grade systems.

## Pricing

Trail of Bits typically works with:

- Established protocols with significant budgets
- Enterprise clients
- High-value smart contract systems
- Projects requiring the highest level of security assurance

Pricing reflects their premium positioning and comprehensive methodology. Contact via Areta marketplace or directly for proposals.

## Getting Started

To engage Trail of Bits:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit audit request
   - Receive competitive quote from Trail of Bits
   - Potential eligibility for subsidies

2. **Direct Contact**:
   - Visit [trailofbits.com](https://www.trailofbits.com/)
   - Contact sales team
   - Discuss scope and requirements
   - Receive formal proposal

## Deliverables

Trail of Bits provides:

- **Comprehensive Audit Report**: Detailed findings with technical analysis
- **Executive Summary**: High-level summary for stakeholders
- **Fix Verification**: Confirmation of remediation
- **Tool Reports**: Output from Slither, Echidna, and other tools
- **Recommendations**: Best practices and improvements
- **Ongoing Support**: Available for consultation during fixes

## Conclusion

Trail of Bits represents the gold standard in blockchain security, bringing over a decade of security research expertise, industry-leading tools, and rigorous methodology to every engagement. For Lux projects requiring the highest level of security assurance, Trail of Bits provides unmatched depth of analysis, combining automated tools they developed with manual review by world-class security researchers. Available through the Areta Audit Marketplace for streamlined access and potential subsidies, Trail of Bits ensures that your Lux protocol meets institutional-grade security standards.


# Transak (/integrations/transak)

---
title: Transak
category: Fiat On-Ramp
available: ["LUExchange-Chain", "All Lux L1s"]
description: Transak is a global fiat-to-crypto payment gateway that enables users to buy cryptocurrencies with fiat directly within your application.
logo: /images/transak.png
developer: Transak
website: https://transak.com/
documentation: https://docs.transak.com/
---

## Overview

Transak is a global fiat-to-crypto payment gateway that provides a seamless and compliant on-ramp solution for blockchain applications. It enables users to purchase cryptocurrencies using traditional payment methods directly within your application, eliminating the need to navigate external exchanges. With support for 130+ cryptocurrencies across 100+ countries, Transak offers extensive global coverage and regulatory compliance.

## Features

- **Global Coverage**: Support for users in 100+ countries with local payment methods, currencies, and languages.
- **Multiple Payment Methods**: Credit/debit cards, bank transfers, Apple Pay, Google Pay, and regional payment options.
- **Extensive Crypto Support**: On-ramp to 130+ cryptocurrencies, including native tokens for custom L1s.
- **Flexible Integration Options**: Widget, SDK, and API solutions to fit your application's needs.
- **Customizable Widget**: White-labeled integration that matches your application's design.
- **KYC/AML Compliance**: Built-in compliance processes that meet regulatory requirements across jurisdictions.
- **Risk Management**: Advanced fraud prevention systems that protect both users and merchants.
- **Automated Payouts**: Direct deposit of purchased crypto to user wallets.
- **Fiat Off-Ramp**: Select regions support converting crypto back to fiat (where permitted by regulations).
- **NFT Checkout**: Allow users to purchase NFTs directly with fiat payment methods.
- **Partner Dashboard**: Analytics and management tools to track conversions and optimize performance.

## Getting Started

To integrate Transak into your application:

1. **Sign Up**: Visit the [Transak Partner Dashboard](https://docs.transak.com/docs/setup-your-partner-account) and create an account to get your API key.

2. **Choose Integration Method**:
   
   - **Direct URL Integration**: The simplest approach:
     ```javascript
     const transakUrl = new URL('https://global.transak.com/');
     transakUrl.searchParams.append('apiKey', 'YOUR_API_KEY');
     transakUrl.searchParams.append('defaultCryptoCurrency', 'LUX');
     transakUrl.searchParams.append('network', 'lux');
     transakUrl.searchParams.append('walletAddress', userWalletAddress);
     
     window.open(transakUrl.href, '_blank');
     ```

   - **SDK Integration**: For web applications, add the Transak SDK to your project:
     ```bash
     npm install @transak/transak-sdk
     ```
     
     ```javascript
     import transakSDK from '@transak/transak-sdk';
     
     const transak = new transakSDK({
       apiKey: 'YOUR_API_KEY',
       environment: 'PRODUCTION', // or 'STAGING' for testing
       defaultCryptoCurrency: 'LUX',
       network: 'lux',
       walletAddress: userWalletAddress, // Pre-fill user's wallet
       themeColor: '000000', // Custom color in hex
       hostURL: window.location.origin,
       widgetHeight: '650px',
       widgetWidth: '450px',
       hideMenu: false,
       exchangeScreenTitle: 'Buy Crypto',
       disableWalletAddressForm: false,
     });
     
     transak.init();
     ```

3. **Handle Events**: Listen for transaction events:
   ```javascript
   transak.on(transak.EVENTS.TRANSAK_WIDGET_CLOSE, () => {
     // Handle widget close
   });
   
   transak.on(transak.EVENTS.TRANSAK_ORDER_SUCCESSFUL, (orderData) => {
     // Handle successful purchase
     console.log(orderData);
   });
   
   transak.on(transak.EVENTS.TRANSAK_ORDER_FAILED, (orderData) => {
     // Handle failed purchase
     console.log(orderData);
   });
   ```

4. **Set Up Webhooks** (Optional): Implement server-side webhooks to receive transaction updates:
   ```javascript
   // Example Express.js webhook handler
   app.post('/transak-webhook', (req, res) => {
     const payload = req.body;
     
     if (payload.status === 'COMPLETED') {
       // Process completed transaction
     }
     
     res.status(200).send('Webhook received');
   });
   ```

5. **Test in Staging**: Use the staging environment with test cards to verify your integration before going live.

## Documentation

For detailed implementation guides, API references, and webhook setup, visit the [Transak Documentation](https://docs.transak.com/).

## Use Cases

Transak can be integrated into various blockchain applications:

**Wallets**: Allow users to purchase crypto directly within your wallet application without leaving the interface.

**DeFi Platforms**: Provide a seamless on-ramp for users to acquire tokens needed for your DeFi services.

**NFT Marketplaces**: Enable direct purchase of NFTs with fiat, abstracting away the crypto acquisition step.

**GameFi Applications**: Let gamers purchase in-game assets or tokens without needing prior crypto knowledge.

**Decentralized Applications**: Reduce friction in your dApp's user experience by integrating a native fiat entry point.

## Pricing

Transak operates on a transaction fee model:

- **Fee Range**: Typically 0.5% to 3% per transaction
- **Custom Fee Structure**: Enterprise solutions with custom fee arrangements available
- **Revenue Sharing**: Partnership opportunities with revenue sharing for qualified partners
- **No Monthly Fees**: Pay only for successful transactions

The fee structure can vary by region, payment method, and transaction volume. For detailed pricing information, contact Transak's sales team.

## Conclusion

Transak provides a comprehensive fiat on-ramp solution that can significantly improve user experience in blockchain applications. By handling the complex compliance requirements and payment processing infrastructure, Transak allows developers to focus on building their core application features while providing users with a seamless way to enter the crypto ecosystem. With its extensive global coverage, multiple payment options, and customizable integration, Transak is an ideal solution for any blockchain project looking to reduce friction in the user onboarding process. 

# Transfero (/integrations/transfero)

---
title: Transfero
category: Assets
available: ["LUExchange-Chain"]
description: "Transfero provides regulated stablecoins including BRZ (Brazilian Real stablecoin), offering tokenized fiat currencies for Latin American markets."
logo: /images/transfero.jpg
developer: Transfero
website: https://www.transfero.com/
documentation: https://www.transfero.com/
---

## Overview

Transfero is a regulated financial technology company providing stablecoins for Latin American markets, including BRZ (Brazilian Real stablecoin). With full regulatory compliance and transparent reserve management, Transfero enables users and businesses to access tokenized representations of Latin American fiat currencies on blockchain, facilitating cross-border payments, remittances, and digital asset transactions with local currency stability.



# Truffle Suite (/integrations/truffle)

---
title: Truffle Suite
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Truffle Suite is a comprehensive development environment for Ethereum and EVM-compatible smart contracts including testing and deployment tools."
logo: /images/truffle.png
developer: Consensys
website: https://trufflesuite.com/
documentation: https://trufflesuite.com/docs/
---

## Overview

Truffle Suite is a world-class development environment, testing framework, and asset pipeline for blockchains using the Ethereum Virtual Machine (EVM). As part of the Consensys ecosystem, Truffle provides developers with the tools needed to develop, test, and deploy smart contracts on Lux and other EVM-compatible networks.

## Features

- **Smart Contract Development**: Built-in smart contract compilation and linking
- **Automated Testing**: Framework for writing and running tests
- **Scriptable Deployment**: Configurable deployment scripts
- **Network Management**: Deploy to multiple networks easily
- **Ganache Integration**: Local blockchain for development
- **Debugger**: Interactive debugger for troubleshooting

## Getting Started

To use Truffle with Lux:

1. **Install Truffle**: `npm install -g truffle`
2. **Create Project**: `truffle init` to start new project
3. **Configure Network**: Add Lux networks to truffle-config.js
4. **Write Contracts**: Develop Solidity smart contracts
5. **Test and Deploy**: Run tests and deploy to Lux

## Documentation

For comprehensive guides, visit [Truffle Documentation](https://trufflesuite.com/docs/).

## Use Cases

- **Smart Contract Development**: Full development lifecycle support
- **DApp Development**: Build complete decentralized applications
- **Testing**: Comprehensive testing of contract functionality
- **CI/CD Integration**: Automated deployment pipelines

## Conclusion

Truffle Suite provides essential development tools for building smart contracts on Lux, offering a mature, battle-tested environment for professional Solidity development.


# Turnkey (/integrations/turnkey)

---
title: Turnkey
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Turnkey provides programmable wallet infrastructure with secure key management for building Web3 applications."
logo: /images/turnkey.png
developer: Turnkey
website: https://www.turnkey.com/
documentation: https://docs.turnkey.com/
---

## Overview

Turnkey provides programmable wallet infrastructure that enables developers to build secure, scalable Web3 applications with best-in-class key management. Using secure enclaves and policy-based controls, Turnkey makes it easy to create and manage wallets while maintaining the highest security standards.

## Features

- **Secure Enclaves**: Keys protected in secure hardware
- **Programmable Policies**: Flexible policy engine for transaction controls
- **API-First**: Complete API for wallet operations
- **Non-Custodial**: Users maintain control of their assets
- **Scalable**: Infrastructure built for high-volume applications
- **Developer Friendly**: SDKs and comprehensive documentation

## Getting Started

To integrate Turnkey:

1. **Sign Up**: Create account at [Turnkey](https://www.turnkey.com/)
2. **Get API Keys**: Access credentials from dashboard
3. **Choose SDK**: Select SDK for your platform
4. **Implement**: Add Turnkey wallet functionality
5. **Configure Policies**: Set up transaction policies
6. **Launch**: Deploy wallet-enabled application

## Documentation

For integration guides, visit [Turnkey Documentation](https://docs.turnkey.com/).

## Use Cases

- **Embedded Wallets**: Build applications with embedded wallet functionality
- **Institutional Ops**: Secure wallet operations for institutions
- **Developer Platforms**: Add wallet capabilities to developer tools
- **Enterprise Apps**: Wallet infrastructure for enterprise applications

## Conclusion

Turnkey provides essential programmable wallet infrastructure for Lux applications, enabling secure, scalable key management with developer-friendly APIs and comprehensive policy controls.


# Twinstake (/integrations/twinstake)

---
title: Twinstake
category: Validator Infrastructure
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Twinstake is an institutional digital asset staking provider offering secure validator infrastructure and staking-as-a-service."
logo: /images/twinstake.png
developer: Twinstake
website: https://twinstake.io/
documentation: https://docs.twinstake.io/
---

## Overview

Twinstake is an institutional digital asset infrastructure company specializing in staking services and validator operations. Designed for institutional clients including asset managers, exchanges, and custodians, Twinstake provides secure, compliant infrastructure for participating in Lux and other proof-of-stake networks.

## Features

- **Institutional Grade**: Infrastructure designed for institutional compliance requirements
- **Staking-as-a-Service**: Complete staking solutions for enterprise clients
- **Multi-Chain Support**: Validation and staking across leading PoS networks
- **Security Standards**: Enterprise security with comprehensive key management
- **Compliance Focus**: Built for regulated financial institutions
- **White-Glove Service**: Dedicated support for institutional clients

## Getting Started

To work with Twinstake:

1. **Contact Twinstake**: Reach out through [Twinstake](https://twinstake.io/)
2. **Solution Design**: Work with Twinstake to design your staking solution
3. **Onboarding**: Complete institutional onboarding process
4. **Deployment**: Launch your staking or validation operations
5. **Ongoing Support**: Receive dedicated institutional support

## Documentation

For more information, visit [Twinstake Documentation](https://docs.twinstake.io/).

## Use Cases

- **Asset Manager Staking**: Staking operations for crypto asset managers
- **Exchange Infrastructure**: Staking services for cryptocurrency exchanges
- **Custodian Solutions**: Support custodial staking for institutions
- **Fund Validation**: Professional validation for crypto funds

## Conclusion

Twinstake provides the institutional-grade staking infrastructure needed for regulated entities to safely participate in Lux network validation and earn staking rewards.


# Ultravioleta DAO (/integrations/ultravioletadao)

---
title: Ultravioleta DAO
category: x402
available: ["LUExchange-Chain"]
description: Ultravioleta DAO offers the x402 protocol, a payment infrastructure that enables monetization of AI agents and APIs on Lux.
logo: /images/ultravioletadao.png
developer: Ultravioleta DAO
website: https://ultravioletadao.xyz
documentation: https://facilitator.ultravioletadao.xyz
---

## Overview

Ultravioleta DAO, a leading Web3 DAO in Latin America, offers the x402 protocol - a payment infrastructure that enables monetization of AI agents and APIs on Lux. The protocol solves a critical challenge: autonomous agents cannot operate without gas money. The x402 facilitator acts as a payment intermediary that verifies transactions, covers gas fees, and settles payments on-chain, allowing agents and services to operate autonomously using USDC payments.

The facilitator is available on both Lux LUExchange-Chain (Mainnet) and Lux Testnet (Testnet), enabling developers to test their integrations before deploying to production.

## What is x402?

x402 is an HTTP-based payment protocol built on the standard HTTP 402 "Payment Required" status code. It enables micropayments between services without requiring the paying party to hold native gas tokens. The protocol uses ERC-3009 meta-transactions to allow third-party facilitators to sponsor gas fees while maintaining cryptographic proof of payment authorization.

**Key participants:**
- **Merchants**: Service providers who monetize their APIs or agent services
- **Clients**: Users or agents who pay for access to services
- **Facilitators**: Infrastructure providers who verify payments and cover gas fees

## Features

- **Gasless Payments**: Clients don't need LUX for gas fees - the facilitator sponsors all transactions
- **Stablecoin Settlement**: Payments settled in USDC for predictable pricing
- **Cryptographic Security**: EIP-712 signatures ensure payment authenticity and prevent replay attacks
- **Stateless Verification**: All payment verification happens on-chain without requiring databases
- **Fast & Free**: Sub-second payment verification with no fees for using the facilitator service
- **Load Balanced**: Auto-scalable infrastructure ensures high availability and reliability
- **Community Operated**: Fully decentralized and community-governed payment infrastructure

## Getting Started for Merchants

To monetize your API or agent service using x402:

1. **Set up your service endpoint** that you want to monetize
2. **Configure the x402 middleware** to protect your endpoint with a price tag
3. **Specify your payment address** where USDC payments should be received
4. **Deploy your service** - the facilitator handles all payment verification and settlement

Example middleware configuration:
```typescript
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

// Configure payment middleware
app.use(paymentMiddleware(
  "0xYourWalletAddress",
  {
    "/api/service": {
      price: "$0.01",
      network: "lux-c-chain",  // or "lux-testnet" for testnet
      config: {
        description: "Access to your API service"
      }
    }
  },
  {
    url: 'https://facilitator.ultravioletadao.xyz'
  }
));
```

## Getting Started for Clients

To pay for x402-protected services:

1. **Initialize the x402 client** with your private key and the facilitator URL
2. **Make requests** to protected endpoints - payment happens automatically
3. **Receive the response** once payment is verified and settled on-chain

Example client usage:
```typescript
import { X402Client } from "x402-client";

const client = new X402Client({
  privateKey: process.env.CLIENT_PRIVATE_KEY,
  facilitatorUrl: 'https://facilitator.ultravioletadao.xyz',
  network: 'lux-c-chain'  // or 'lux-testnet' for testnet
});

// Make a paid request
const response = await client.post('https://api.example.com/service', {
  data: { query: 'your request' }
});
```

## Use Cases

### AI Agent Monetization
Allow autonomous AI agents to offer services and receive payments without manual intervention. Agents can charge per request, per computation, or per resource consumed.

### Pay-Per-Use APIs
Monetize API endpoints with micropayment pricing. Instead of subscription tiers, charge users only for what they consume at granular levels.

### Agent-to-Agent Marketplaces
Build trustless marketplaces where autonomous agents buy and sell services from each other, creating self-sustaining AI economies.

### Token-Gated Services
Provide access to premium services, data feeds, or computational resources based on per-use payments rather than upfront subscriptions.

## Lux Integration

The x402 facilitator is optimized for Lux deployment on both mainnet and testnet:

### Lux LUExchange-Chain (Mainnet)
- **Chain ID**: 43114
- **Native Token**: LUX (used by facilitator for gas fees)
- **Payment Token**: USDC
- **Finality**: Sub-second transaction finality for fast payment confirmation
- **EVM Compatibility**: Full support for ERC-3009 meta-transactions

### Lux Testnet (Testnet)
- **Chain ID**: 43113
- **Native Token**: LUX (used by facilitator for gas fees)
- **Payment Token**: USDC
- **Purpose**: Test your integration before deploying to mainnet

The facilitator maintains a hot wallet funded with LUX to sponsor gas fees for all USDC payment settlements. Clients only need USDC in their wallets - no LUX required.

## How It Works

1. **Client Request**: Client signs payment authorization using EIP-712 and sends request to merchant
2. **Merchant Verification**: Merchant forwards payment proof to facilitator for verification
3. **Facilitator Check**: Facilitator verifies signature, checks on-chain balance and nonce
4. **Settlement**: Facilitator submits `transferWithAuthorization()` transaction, paying gas fees
5. **Response**: Once settled, merchant receives confirmation and responds to client

All settlements happen on Lux using the ERC-3009 standard, ensuring cryptographic security and on-chain auditability.

## Documentation

For complete API documentation, integration guides, and example implementations, visit the [Ultravioleta DAO facilitator](https://facilitator.ultravioletadao.xyz).

## About Ultravioleta DAO

Ultravioleta DAO is a leading Web3 DAO in Latin America, focused on building decentralized infrastructure for autonomous agent economies. The organization develops open-source protocols and tools that enable trustless interactions between AI agents, with a focus on payment infrastructure, decentralized governance, and blockchain-based monetization. Learn more at [ultravioletadao.xyz](https://ultravioletadao.xyz/).

## Conclusion

Ultravioleta DAO's x402 facilitator provides production-ready payment infrastructure for building autonomous agent economies and monetized APIs on Lux. By abstracting away gas fee management and providing a simple HTTP protocol for payments, it enables developers to focus on building valuable services while maintaining security through cryptographic signatures and on-chain settlement. Start testing on Testnet testnet today, then deploy to LUExchange-Chain mainnet when ready.

# Van Eck (/integrations/van-eck)

---
title: Van Eck
category: Assets
available: ["LUExchange-Chain"]
description: "Van Eck is a global investment management firm offering tokenized funds including VBILL, providing innovative blockchain-based investment solutions."
logo: /images/van-eck.png
developer: Van Eck
website: https://www.vaneck.com/
documentation: https://www.vaneck.com/us/en/digital-assets/
---

## Overview

Van Eck is a pioneering investment management firm with a long history of innovation in financial products, now leading the integration of blockchain technology into traditional asset management. Through tokenized funds like VBILL and other digital asset offerings, Van Eck provides investors with access to blockchain-native investment products that combine institutional-grade asset management with the efficiency and transparency of distributed ledger technology.



# VIA Labs (/integrations/vialabs)

---
title: VIA Labs
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: "VIA Labs enables Lux L1s to integrate cross-chain USDC with Proto-USD, leveraging Lux's ICM infrastructure and Circle's CCTP."
logo: /images/vialabs.png
developer: VIA Labs
website: https://vialabs.io/
documentation: https://developer.vialabs.io/general/package
---

## Overview

VIA Labs provides Lux L1s with Proto-USD, a solution that enables seamless USDC integration across multiple blockchain networks. By combining Lux's native Interchain Messaging (ICM) infrastructure with Circle's Cross-Chain Transfer Protocol (CCTP), VIA Labs allows any Lux L1 to receive and utilize USDC from networks like Ethereum, Base, Solana, and other CCTP-enabled chains.

## Features

- **Native ICM Integration**: Utilizes Lux's built-in cross-chain messaging infrastructure.
- **USDC Cross-Chain Support**: Enables transfer of USDC between Lux L1s and other major blockchains.
- **Bridged USDC Standard**: Implements standardized approach for USDC representation across chains.
- **CCTP Compatibility**: Leverages Circle's Cross-Chain Transfer Protocol for secure token transfers.
- **Testnet-Ready**: Available on testnet for all Lux L1s.
- **Path to Native Issuance**: Sets Lux L1s on an onboarding path to potential native USDC issuance.
- **Multi-Chain Support**: Compatible with Ethereum, Base, Solana (coming soon), and other CCTP-enabled chains.

## Getting Started

To begin using VIA Labs' Proto-USD:

1. **Access Documentation**: Review the [VIA Labs Developer Documentation](https://developer.vialabs.io/general/package).
2. **Explore Demo**: Visit the [Proto-USD demo](https://lux.protousd.com/) to see the technology in action.
3. **Integration Steps**: 
   - Set up ICM infrastructure on your Lux L1
   - Configure CCTP message passing
   - Implement Proto-USD contracts
   - Test cross-chain USDC transfers
4. **Deployment**: Deploy to testnet first, then to mainnet after thorough testing.

## Documentation

For comprehensive developer documentation and integration guides, visit the [VIA Labs Developer Portal](https://developer.vialabs.io/general/package).

## Use Cases

Proto-USD enables various cross-chain scenarios:

- **Cross-Chain DeFi**: Access USDC liquidity from other chains for DeFi applications.
- **Multi-Chain dApps**: Build applications that can use USDC across different blockchains.
- **Simplified Treasury Management**: Manage USDC treasury across multiple networks.
- **Enhanced Liquidity**: Tap into USDC liquidity from major blockchains.
- **Seamless User Experience**: Provide users with cross-chain stablecoin functionality.

## Official Launch Update
[See the official announcement on X](https://x.com/VIA_Labs/status/1895156949467161060)

## Conclusion

VIA Labs' Proto-USD provides Lux L1s with essential infrastructure for cross-chain USDC integration. By leveraging Lux's ICM capabilities and Circle's CCTP, Proto-USD enables seamless stablecoin transfers across blockchain ecosystems. This solution not only enhances the utility of Lux L1s but also positions them for potential native USDC issuance in the future, significantly expanding their cross-chain capabilities and accessibility.

# VNX (/integrations/vnx)

---
title: VNX
category: Assets
available: ["LUExchange-Chain"]
description: "VNX provides regulated stablecoins including VEUR and VCHF, offering tokenized fiat currencies backed by traditional financial infrastructure."
logo: /images/vnx.png
developer: VNX
website: https://vnx.ch/
documentation: https://docs.vnx.ch/
---

## Overview

VNX is a regulated stablecoin issuer providing tokenized fiat currencies including VEUR (Euro stablecoin) and VCHF (Swiss Franc stablecoin). Built on blockchain infrastructure with traditional financial backing, VNX enables users and institutions to access stable digital representations of major fiat currencies with full regulatory compliance and transparent reserve management.



# Web3Auth (/integrations/web3auth)

---
title: Web3Auth
category: Developer Tooling
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Web3Auth provides authentication infrastructure enabling social logins and passwordless authentication for Web3 applications."
logo: /images/web3auth.png
developer: Web3Auth
website: https://web3auth.io/
documentation: https://web3auth.io/docs/
---

## Overview

Web3Auth is a pluggable auth infrastructure for Web3 applications that enables social logins, passwordless authentication, and wallet creation. By abstracting the complexity of key management, Web3Auth helps applications onboard both crypto-native and mainstream users with familiar authentication methods.

## Features

- **Social Logins**: Login with Google, Twitter, Discord, and more
- **Passwordless Auth**: Email and SMS authentication options
- **MPC Key Management**: Secure multi-party computation for key security
- **White-Label**: Fully customizable authentication flows
- **Multi-Platform**: Support for web, mobile, and gaming platforms
- **Self-Custodial**: Users maintain control of their keys

## Getting Started

To integrate Web3Auth:

1. **Sign Up**: Create account at [Web3Auth](https://web3auth.io/)
2. **Get Client ID**: Access credentials from dashboard
3. **Choose SDK**: Select SDK for your platform (Web, React Native, Unity)
4. **Configure**: Set up authentication providers
5. **Implement**: Add Web3Auth to your application
6. **Launch**: Enable social login for your users

## Documentation

For integration guides, visit [Web3Auth Documentation](https://web3auth.io/docs/).

## Use Cases

- **User Onboarding**: Seamless onboarding with social logins
- **Gaming**: Easy player authentication for Web3 games
- **DeFi Access**: Lower barrier to DeFi participation
- **Enterprise Apps**: Familiar auth flows for enterprise users

## Conclusion

Web3Auth provides essential authentication infrastructure for Lux applications, enabling mainstream user onboarding through familiar social login experiences while maintaining Web3's self-custodial principles.


# WisdomTree (/integrations/wisdomtree)

---
title: WisdomTree
category: Assets
available: ["LUExchange-Chain"]
description: WisdomTree is a global financial innovator offering exchange-traded products, a blockchain-native app (WisdomTree Prime), and institutional platform (WisdomTree Connect) bridging traditional finance with tokenized real-world assets.
logo: /images/wisdomtree.jpg
developer: WisdomTree
website: https://www.wisdomtree.com/
documentation: https://www.wisdomtree.com/digital-assets
---

## Overview

WisdomTree is a pioneering financial services company with over $100 billion in assets under management, known for innovation in exchange-traded products and now leading the integration of blockchain technology into traditional finance. WisdomTree operates across three major platforms: traditional ETPs (Exchange-Traded Products), WisdomTree Prime (a blockchain-native consumer app), and WisdomTree Connect (an institutional tokenization and infrastructure platform).

Through these platforms, WisdomTree provides access to tokenized real-world assets, cryptocurrencies, stablecoins, and traditional securities, all while maintaining the regulatory compliance and institutional trust built over two decades in traditional finance. WisdomTree's vision is to democratize access to diverse asset classes through blockchain technology, making sophisticated investment strategies available to both retail and institutional investors.

## Platforms

### WisdomTree Prime

A mobile-first blockchain app for retail investors offering:

- **Crypto Trading**: Buy, sell, and hold major cryptocurrencies
- **Tokenized Assets**: Access to tokenized commodities, currencies, and other real-world assets
- **Staking and Yield**: Earn rewards through staking and yield-generating products
- **Traditional Securities**: Invest in stocks and ETFs alongside digital assets
- **Wallet Functionality**: Self-custodial and custodial wallet options
- **Dollar-Cost Averaging**: Automated recurring investment features
- **Educational Resources**: In-app learning materials about crypto and blockchain

### WisdomTree Connect

An institutional-grade platform for tokenization and asset management:

- **Asset Tokenization**: Infrastructure for tokenizing real-world assets
- **Blockchain-as-a-Service**: White-label blockchain infrastructure for institutions
- **Digital Asset Custody**: Institutional custody solutions
- **Smart Contract Platform**: Develop and deploy tokenized products
- **Regulatory Compliance**: Built-in compliance for regulated tokenized securities
- **Multi-Chain Support**: Deploy across multiple blockchain networks
- **API Integration**: Enterprise APIs for seamless integration

### Traditional ETPs

WisdomTree continues to offer its flagship exchange-traded products:

- **Equity ETFs**: Global equity exposure across markets and sectors
- **Fixed Income ETFs**: Bond and fixed income strategies
- **Commodity ETFs**: Gold, silver, and commodity exposure
- **Currency-Hedged ETFs**: International exposure with currency hedging
- **Alternative Strategy ETFs**: Sophisticated investment strategies

## Features

- **Multi-Asset Platform**: Access crypto, tokenized assets, stocks, ETFs, and commodities in one ecosystem.
- **Tokenized Real-World Assets**: Invest in blockchain-native representations of traditional assets.
- **Institutional Infrastructure**: Enterprise-grade custody, compliance, and security for digital assets.
- **Regulatory Compliance**: Fully regulated platforms with licenses in multiple jurisdictions.
- **Blockchain Integration**: Native blockchain infrastructure for asset tokenization and management.
- **Mobile-First Experience**: User-friendly apps for retail investors (WisdomTree Prime).
- **Institutional Services**: White-label solutions and infrastructure for financial institutions (WisdomTree Connect).
- **Smart Contract Innovation**: Programmable assets with automated compliance and distribution.
- **Staking and Yield**: Access to yield-generating opportunities in digital assets.
- **Educational Focus**: Comprehensive resources to help users understand digital assets.
- **Traditional Finance Bridge**: Seamless integration between TradFi and DeFi worlds.
- **Global Presence**: Operations in US, Europe, and other major markets.

## Getting Started

### For Retail Investors (WisdomTree Prime):

1. Download the WisdomTree Prime app from iOS or Android app stores
2. Create an account and complete identity verification
3. Fund your account via bank transfer or other methods
4. Explore available assets: crypto, tokenized products, stocks, ETFs
5. Build a diversified portfolio across asset classes
6. Set up automated investing and track performance

### For Institutions (WisdomTree Connect):

1. Contact WisdomTree's institutional team to discuss requirements
2. Explore tokenization services, custody solutions, or infrastructure offerings
3. Define use case: asset tokenization, product development, or white-label platform
4. Work with WisdomTree to implement compliant blockchain solutions
5. Launch tokenized products or services on WisdomTree's infrastructure
6. Access ongoing support and platform enhancements

## Lux Support

WisdomTree's infrastructure supports multiple blockchain networks for deploying tokenized assets. While specific implementations may vary, WisdomTree Connect's multi-chain architecture is compatible with EVM networks including Lux LUExchange-Chain, enabling efficient deployment of tokenized products on Lux's high-performance infrastructure.

## Tokenized Products

WisdomTree offers various tokenized asset products:

**Tokenized Commodities**: Digital representations of gold, silver, and other physical commodities.

**Tokenized Securities**: Blockchain-native versions of traditional securities with programmable features.

**Stablecoins**: Dollar-pegged digital currencies for stability and efficiency.

**Utility Tokens**: Tokens providing access to specific products or services within the ecosystem.

**Yield-Bearing Tokens**: Tokens that automatically generate returns through staking or other mechanisms.

## Use Cases

WisdomTree's platforms serve diverse needs:

**Retail Wealth Building**: Individual investors using Prime to build diversified portfolios across traditional and digital assets.

**Institutional Tokenization**: Asset managers using Connect to tokenize funds, securities, or other assets.

**Corporate Treasury**: Companies managing digital asset treasuries through WisdomTree's institutional platform.

**Financial Institution Partnerships**: Banks and brokers white-labeling WisdomTree's technology to offer digital assets.

**Cross-Border Payments**: Using tokenized assets for efficient international settlements.

**Yield Optimization**: Institutions accessing yield opportunities through tokenized products.

**Product Innovation**: Financial services companies developing new tokenized investment products on WisdomTree's infrastructure.

## Regulatory Framework

WisdomTree maintains comprehensive regulatory compliance:

- **SEC-Registered**: Registered investment adviser with the U.S. Securities and Exchange Commission
- **FINRA Member**: Member of Financial Industry Regulatory Authority
- **FCA Regulated**: Authorized and regulated by UK Financial Conduct Authority
- **State Licenses**: Money transmitter licenses for digital asset services
- **European Licenses**: Regulatory approvals across European jurisdictions
- **Crypto Compliance**: Adheres to crypto-specific regulations including AML/KYC
- **Regular Audits**: Ongoing compliance audits and regulatory examinations

## WisdomTree's Digital Asset Strategy

WisdomTree has committed significant resources to blockchain and digital assets:

- **Early Mover**: Among first traditional asset managers to embrace blockchain technology
- **Infrastructure Investment**: Developed proprietary blockchain platforms (Prime and Connect)
- **Strategic Acquisitions**: Acquired and built technology to support digital asset vision
- **Patent Portfolio**: Holds multiple patents related to blockchain and tokenization
- **Industry Leadership**: Active in shaping regulations and industry standards
- **Education Focus**: Leading voice in educating investors about digital assets

## Competitive Advantages

**Established Brand**: Over 20 years in financial services with $100B+ AUM building trust.

**Dual Platform Approach**: Serves both retail (Prime) and institutional (Connect) markets.

**Regulatory Certainty**: Fully licensed and compliant across multiple jurisdictions.

**Traditional Finance Expertise**: Deep understanding of asset management and ETF structures.

**Blockchain Innovation**: Early adopter with proprietary infrastructure and technology.

**Multi-Asset Capability**: Seamlessly blend traditional and digital assets.

**Global Reach**: International operations and regulatory licenses.

## Pricing

WisdomTree offers transparent pricing across platforms:

### WisdomTree Prime (Retail):
- **Trading Fees**: Competitive fees on crypto and asset trades
- **Management Fees**: Low fees on tokenized products and ETFs
- **No Account Minimums**: Accessible to all investors
- **Transparent Pricing**: Clear fee schedule with no hidden costs

### WisdomTree Connect (Institutional):
- **Custom Pricing**: Tailored to institutional requirements
- **Setup Fees**: Initial tokenization and platform setup costs
- **Platform Fees**: Ongoing infrastructure and technology fees
- **Service Fees**: Additional services like custody and compliance
- **Volume Discounts**: Pricing scales with asset size and transaction volume

Contact WisdomTree for detailed institutional pricing.

## Assets Under Management

WisdomTree manages significant assets across platforms:

- $100+ billion in traditional ETPs
- Growing digital asset AUM through Prime and Connect platforms
- Partnerships with major institutions for tokenization
- Expanding tokenized product offerings

## Conclusion

WisdomTree represents the evolution of traditional asset management into the blockchain era. By combining decades of financial services expertise with cutting-edge blockchain technology, WisdomTree provides both retail and institutional investors with regulated access to tokenized assets and digital securities. Through WisdomTree Prime's consumer-friendly app and WisdomTree Connect's institutional infrastructure, supported by blockchain networks like Lux, WisdomTree is building the bridge between traditional finance and the tokenized economy. Whether you're an individual investor looking to diversify into digital assets or an institution seeking to tokenize products and services, WisdomTree's proven track record, regulatory compliance, and innovative platforms provide a trusted path into the future of finance.



# Wormhole (/integrations/wormhole)

---
title: Wormhole
category: Crosschain Solutions
available: ["LUExchange-Chain"]
description: Wormhole is a leading interoperability platform powering multichain applications, messaging, and native token transfers across 30+ blockchains with secure, permissionless infrastructure.
logo: /images/wormhole.png
developer: Wormhole Foundation
website: https://wormhole.com/
documentation: https://docs.wormhole.com/
---

## Overview

Wormhole is one of the most widely adopted interoperability platforms in blockchain, enabling secure cross-chain messaging, native token transfers, and multichain applications across 30+ blockchain networks. As a generic message passing protocol, Wormhole allows developers to build applications that seamlessly interact with multiple blockchains simultaneously, unlocking liquidity and users across the entire Web3 ecosystem.

With billions of dollars in cross-chain value transferred and integrations with major DeFi protocols, NFT platforms, and blockchain infrastructure, Wormhole has established itself as critical infrastructure for the multichain future. The platform's permissionless, decentralized architecture ensures that any developer can build cross-chain applications without needing permission or relying on centralized intermediaries.


# BDACS / Worori Bank (/integrations/worori-bank)

---
title: BDACS / Worori Bank
category: Assets
available: ["LUExchange-Chain"]
description: "BDACS in partnership with Worori Bank provides KRW1 (Korean Won stablecoin), offering a regulated tokenized representation of the Korean Won."
logo: /images/worori-bank.png
developer: BDACS / Worori Bank
website: https://www.bdacs.co.kr/
documentation: https://www.bdacs.co.kr/
---

## Overview

BDACS, in partnership with Worori Bank, provides KRW1, a Korean Won-backed stablecoin that enables users and businesses in South Korea and globally to access a stable digital representation of the Korean Won on blockchain. With banking partnership and regulatory compliance, this stablecoin facilitates payments, remittances, and digital asset transactions with Korean Won stability.



# Wyre (/integrations/wyre)

---
title: Wyre
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: Wyre offers powerful APIs for fiat-to-crypto on-ramp and off-ramp solutions, enabling users to purchase and sell cryptocurrencies directly within applications.
logo: /images/wyre.webp
developer: Wyre
website: https://wyre.studiofreight.com/
documentation: https://docs.sendwyre.com/
---

## Overview

Wyre is a financial technology company that provides comprehensive API infrastructure for converting between fiat currencies and cryptocurrencies. Wyre's platform enables businesses to offer seamless fiat-to-crypto on-ramp and off-ramp solutions, allowing users to buy and sell digital assets directly within applications. With support for Lux and multiple payment methods, Wyre handles the complex aspects of payment processing, compliance, and liquidity management.

Wyre's infrastructure is designed for developers who need a reliable, compliant, and feature-rich payment gateway that supports the full lifecycle of crypto transactions, from KYC verification to settlement.

## Features

- **Wyre Checkout Widget**: Turnkey fiat-to-crypto on-ramp that enables selling crypto with just a few lines of integration code.
- **Card Processing**: Accept debit and credit cards for cryptocurrency purchases with built-in fraud prevention.
- **Global Payment Methods**: Support for bank transfers (ACH, wire), credit/debit cards, Apple Pay, and region-specific payment options.
- **On-Ramp and Off-Ramp**: Complete buy and sell functionality to create a full-circle user experience.
- **Custodial Wallets**: API-based wallet solution for holding crypto and fiat assets on behalf of users.
- **KYC/AML Compliance Engine**: Built-in compliance as a service with user management system that meets regulatory requirements.
- **Transfers and Swaps**: Move and convert assets across different blockchains and currencies.
- **White-Label Solutions**: Customizable integration that can be branded to match your application.
- **Webhooks**: Real-time notifications for transaction status updates and user events.
- **Test Environment**: Sandbox environment for development and testing without real transactions or fees.
- **Multi-Currency Support**: Handle multiple fiat currencies and cryptocurrencies in a single integration.

## Getting Started

To integrate Wyre into your application:

1. **Create a Test Account**: Register at [dash.testwyre.com](https://dash.testwyre.com/) to get started with testing.

2. **Generate API Keys**: Obtain your test API keys from the dashboard to begin integration.

3. **Choose Integration Method**: Wyre offers multiple integration options:
   - **Wyre Checkout Widget**: Hosted solution for quick integration
   - **Hosted URL**: Direct users to a Wyre-hosted payment page
   - **White-Label API**: Build a fully custom interface using Wyre's APIs
   - **Wallet API**: Create and manage custodial wallets programmatically

4. **Implement Authentication**: Wyre uses signature-based authentication to secure API requests. Review the authentication documentation to properly sign your API calls.

5. **Test Your Integration**: Use the test environment to verify your integration with test cards and bank accounts before going live.

6. **Request Production Access**: After testing is complete, register a production account and complete the verification process to begin processing real transactions.

## Lux Support

Wyre supports LUX and other assets on the Lux LUExchange-Chain, enabling users to purchase Lux-based cryptocurrencies directly with fiat currencies. This allows developers building on Lux to provide seamless fiat on-ramp and off-ramp capabilities within their applications.

## Documentation

For comprehensive integration guides, API references, and authentication examples, visit:

- [Wyre Documentation](https://docs.sendwyre.com/)
- [Quick Start Guide](https://docs.sendwyre.com/docs/quick-start)
- [API Reference](https://docs.sendwyre.com/reference)
- [Wyre Checkout Widget Guide](https://docs.sendwyre.com/docs/wyre-checkout-overview)

## Use Cases on Lux

Wyre can enhance various Lux applications:

**Cryptocurrency Wallets**: Enable users to purchase LUX and other Lux tokens directly within wallet applications.

**DeFi Platforms**: Provide a seamless fiat entry point for users to acquire tokens needed for Lux DeFi protocols.

**NFT Marketplaces**: Allow direct purchase of NFTs on Lux with fiat payment methods, abstracting away the crypto acquisition step.

**GameFi Applications**: Let gamers purchase in-game assets or tokens on Lux without needing prior cryptocurrency knowledge.

**Decentralized Applications**: Reduce friction in your Lux dApp's user experience by integrating a native fiat entry and exit point.

**Enterprise Solutions**: Offer compliant on/off-ramp solutions for corporate applications built on Lux.

## Pricing

Wyre operates on a transaction fee model with pricing that varies based on payment method, region, and transaction volume. The fee structure typically includes:

- **Transaction Fees**: Percentage-based fees on each transaction
- **Payment Method Fees**: Different rates for cards, bank transfers, and other payment methods
- **Volume Discounts**: Available for high-volume partners
- **Custom Enterprise Solutions**: Tailored pricing for large-scale integrations

For specific pricing details and enterprise arrangements, contact Wyre's sales team.

## Compliance and Security

Wyre maintains robust compliance and security measures:

- **Regulatory Compliance**: Licensed as a money transmitter and complies with state and federal regulations
- **KYC/AML Processes**: Built-in identity verification and anti-money laundering screening
- **Fraud Prevention**: Advanced risk management systems to prevent fraudulent transactions
- **Data Security**: Enterprise-grade security infrastructure to protect user data and funds
- **Regular Audits**: Ongoing compliance audits and security assessments

## Conclusion

Wyre provides a comprehensive fiat payment infrastructure that enables developers to build seamless on-ramp and off-ramp experiences for Lux applications. By handling the complex aspects of payment processing, regulatory compliance, and liquidity, Wyre allows developers to focus on building their core products while providing users with easy access to the Lux ecosystem. With flexible integration options, extensive payment method support, and robust compliance features, Wyre is an ideal solution for any project looking to reduce friction in user onboarding and provide complete fiat-to-crypto functionality on Lux.



# x402-rs (/integrations/x402-rs)

---
title: x402-rs
category: x402
available: ["LUExchange-Chain"]
description: A Rust-based implementation of the x402 protocol for accepting blockchain payments through HTTP on Lux.
logo: /images/x402-rs.png
developer: x402-rs
website: https://github.com/x402-rs/x402-rs
documentation: https://github.com/x402-rs/x402-rs
---

## Overview

x402-rs is a Rust-based implementation of the x402 protocol that enables blockchain payments directly through HTTP using the native `402 Payment Required` status code on Lux's LUExchange-Chain.

The x402 protocol allows servers to declare payment requirements for specific routes. Clients send cryptographically signed payment payloads, and facilitators verify and settle payments on-chain.

## What x402-rs Provides

- **x402-rs core**: Protocol types, facilitator traits, and logic for on-chain payment verification and settlement
- **Facilitator binary**: Production-grade HTTP server to verify and settle x402 payments
- **x402-axum**: Axum middleware for accepting x402 payments
- **x402-reqwest**: Wrapper for reqwest for transparent x402 payments

## Getting Started

### Run the Facilitator

The quickest way to get started is using Docker:

```bash
docker run --env-file .env -p 8080:8080 ukstv/x402-facilitator
```

Or build locally:

```bash
docker build -t x402-rs .
docker run --env-file .env -p 8080:8080 x402-rs
```

### Protect Axum Routes

Use `x402-axum` to gate your routes behind on-chain payments on Lux:

```rust
let x402 = X402Middleware::try_from("https://x402.org/facilitator/").unwrap();
let usdc = USDCDeployment::by_network(Network::LuxTestnet);

let app = Router::new().route("/paid-content", get(handler).layer( 
        x402.with_price_tag(usdc.amount("0.025").pay_to("0xYourAddress").unwrap())
    ),
);
```

See the [x402-axum crate documentation](https://docs.rs/x402-axum) for more details.

### Send x402 Payments

Use `x402-reqwest` to send payments on Lux:

```rust
use x402_reqwest::X402ClientExt;

let signer: PrivateKeySigner = "0x...".parse()?; // never hardcode real keys!

let client = reqwest::Client::new()
    .with_payments(signer)
    .prefer(USDCDeployment::by_network(Network::Lux))
    .max(USDCDeployment::by_network(Network::Lux).amount("1.00")?)
    .build();

let res = client
    .get("https://example.com/protected")
    .send()
    .await?;
```

See the [x402-reqwest crate documentation](https://docs.rs/x402-reqwest) for more details.

## Facilitator

The x402-rs facilitator is a runnable binary that simplifies x402 adoption by handling:

- **Payment verification**: Confirming that client-submitted payment payloads match the declared requirements
- **Payment settlement**: Submitting validated payments to the blockchain and monitoring their confirmation

By using a facilitator, servers (sellers) do not need to:
- Connect directly to a blockchain
- Implement complex cryptographic or blockchain-specific payment logic

The facilitator never holds user funds. It acts solely as a stateless verification and execution layer for signed payment payloads.

### Configuration

Create a `.env` file or set environment variables directly:

```bash
HOST=0.0.0.0
PORT=8080
RPC_URL_LUX_FUJI=https://api.lux-test.network/ext/bc/C/rpc
RPC_URL_LUX=https://api.lux.network/ext/bc/C/rpc
SIGNER_TYPE=private-key
EVM_PRIVATE_KEY=0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
RUST_LOG=info
```

**Important:** The supported networks are determined by which RPC URLs you provide:

- If you set only `RPC_URL_LUX_FUJI`, then only Lux Testnet testnet is supported
- If you set both `RPC_URL_LUX_FUJI` and `RPC_URL_LUX`, then both testnet and mainnet are supported
- If an RPC URL for a network is missing, that network will not be available for settlement or verification

### Environment Variables

Available configuration variables:

- `RUST_LOG`: Logging level (e.g., `info`, `debug`, `trace`)
- `HOST`: HTTP host to bind to (default: `0.0.0.0`)
- `PORT`: HTTP server port (default: `8080`)
- `SIGNER_TYPE` (required): Type of signer to use. Only `private-key` is supported now
- `EVM_PRIVATE_KEY` (required): Private key in hex for EVM networks
- `RPC_URL_LUX_FUJI`: Ethereum RPC endpoint for Lux Testnet testnet
- `RPC_URL_LUX`: Ethereum RPC endpoint for Lux LUExchange-Chain mainnet

### Docker Deployment

Prebuilt Docker images are available at:

- **GitHub Container Registry**: `ghcr.io/x402-rs/x402-facilitator`
- **Docker Hub**: `ukstv/x402-facilitator`

Run the container from Docker Hub:

```bash
docker run --env-file .env -p 8080:8080 ukstv/x402-facilitator
```

To run using GitHub Container Registry:

```bash
docker run --env-file .env -p 8080:8080 ghcr.io/x402-rs/x402-facilitator
```

Or build a Docker image locally:

```bash
docker build -t x402-rs .
docker run --env-file .env -p 8080:8080 x402-rs
```

The container:
- Exposes port `8080` (or a port you configure with `PORT` environment variable)
- Starts on `http://localhost:8080` by default
- Requires minimal runtime dependencies (based on `debian:bullseye-slim`)

### Point Your Application to Your Facilitator

If you are building an x402-powered application, update the Facilitator URL to point to your self-hosted instance.

**Using x402-hono:**

```typescript
import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

// Configure the payment middleware
app.use(paymentMiddleware(
  "0xYourAddress", // Your receiving wallet address
  {
    "/protected-route": {
      price: "$0.10",
      network: "lux-testnet",
      config: {
        description: "Access to premium content",
      }
    }
  },
  {
    url: "http://your-validator.url/", // 👈 Your self-hosted Facilitator
  }
));

// Implement your protected route
app.get("/protected-route", (c) => {
  return c.json({ message: "This content is behind a paywall" });
});

serve({
  fetch: app.fetch,
  port: 3000
});
```

**Using x402-axum:**

```rust
let x402 = X402Middleware::try_from("http://your-validator.url/").unwrap();  // 👈 Your self-hosted Facilitator
let usdc = USDCDeployment::by_network(Network::LuxTestnet);

let app = Router::new().route("/paid-content", get(handler).layer( 
        x402.with_price_tag(usdc.amount("0.025").pay_to("0xYourAddress").unwrap())
    ),
);
```

## Observability

The facilitator emits OpenTelemetry-compatible traces and metrics, making it easy to integrate with tools like Honeycomb, Prometheus, Grafana, and others. Tracing spans are annotated with HTTP method, status code, URI, latency, and other request and process metadata.

To enable tracing and metrics export, set the appropriate `OTEL_` environment variables:

```bash
# For Honeycomb, for example:
# Endpoint URL for sending OpenTelemetry traces and metrics
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
# Comma-separated list of key=value pairs to add as headers
OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your_api_key,x-honeycomb-dataset=x402-rs
# Export protocol to use for telemetry. Supported values: `http/protobuf` (default), `grpc`
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
```

The service automatically detects and initializes exporters if `OTEL_EXPORTER_OTLP_*` variables are provided.

## Lux LUExchange-Chain Support

The facilitator supports Lux LUExchange-Chain through these environment variables:

| Network                   | Environment Variable      | Notes                            |
| ------------------------- | ------------------------- | -------------------------------- |
| Lux Testnet Testnet    | RPC_URL_LUX_FUJI   | Recommended for testing          |
| Lux LUExchange-Chain Mainnet | RPC_URL_LUX        | Production mainnet               |

**Tip:** For initial development and testing, start with Lux Testnet testnet only.

## Development

### Prerequisites

- Rust 1.80+
- `cargo` and a working toolchain

### Build Locally

```bash
cargo build
```

### Run

```bash
cargo run
```

## Use Cases

### Payment-Gated APIs
Protect your API endpoints with automatic on-chain payment verification on Lux.

### Micropayment Services
Enable micropayments for content, data, or compute resources with Lux's low fees.

### AI Agent Monetization
Allow AI agents to charge for services on a pay-per-use basis using Lux's fast finality.

### Rust-Native dApps
Build Rust-based decentralized applications with built-in payment capabilities on Lux.

## Documentation

- [x402-rs GitHub Repository](https://github.com/x402-rs/x402-rs)
- [x402 Protocol Documentation](https://x402.gitbook.io/x402)
- [x402 Overview by Coinbase](https://www.coinbase.com/cloud/discover/protocol-guides/guide-to-x402)

## Conclusion

x402-rs provides a production-ready Rust implementation of the x402 protocol for Lux's LUExchange-Chain. With its facilitator service, Axum middleware, and client libraries, it makes it easy to build payment-gated services in Rust. Whether you're protecting API endpoints, enabling micropayments, or building AI agent monetization, x402-rs delivers the tools you need with Rust's performance and safety guarantees on Lux.



# Xangle (/integrations/xangle)

---
title: Xangle
category: Development Infrastructure
available: ["LUExchange-Chain"]
description: Xangle delivers robust blockchain infrastructure solutions—including node services, custom block explorers, and the all-in-one Xangle Hub—empowering projects to deploy, monitor, and scale on Lux and beyond. Analytics and market insights are also available as a complement to its infrastructure offerings.
logo: /images/xangle.jpg
developer: Xangle
website: https://infra.xangle.io/hub
documentation: https://business.xangle.io/
---

## Overview
Xangle is a leading blockchain infrastructure provider, offering high-performance node services, customizable block explorers, and the Xangle Hub—a unified platform for DeFi tools, portfolio management, and on-chain analytics. Xangle's infrastructure enables seamless deployment, monitoring, and scaling of blockchain applications, while supporting ecosystem transparency and accessibility.

## Features
- **Node Services**: Reliable, scalable node infrastructure for developers and enterprises, supporting secure access to blockchain networks.
- **Custom Block Explorers**: Deploy branded, feature-rich explorers for your network or application, with support for transactions, tokens, NFTs, analytics, and more. For example, MapleStory Universe uses a dedicated Xangle-powered explorer for its Henesys L1 testnet ([see example](https://msu-testnet-explorer.xangle.io/)).
- **Xangle Hub**: An all-in-one platform ([see Xangle Hub](https://infra.xangle.io/hub)) that brings together DeFi services (swap, bridge, faucet), portfolio management, NFT minting, dashboards, and real-time on-chain analytics.
- **Developer Tools**: APIs and dashboards for real-time monitoring, data access, and operational insights.
- **Security & Reliability**: Enterprise-grade uptime, monitoring, and support for mission-critical blockchain operations.
- **Analytics & Market Insights**: In addition to infrastructure, Xangle provides market analytics, research, and reporting tools for blockchain projects.

## Getting Started
1. **Explore Infrastructure Solutions**: Visit [Xangle](https://xangle.io/en) to learn about node services, explorer deployments, and developer tools.
2. **Try Xangle Hub**: Experience the unified DeFi and analytics platform at [Xangle Hub](https://infra.xangle.io/hub).
3. **Request Custom Explorer**: Contact Xangle to deploy a tailored explorer for your blockchain or dApp.
4. **Integrate Node Services**: Access secure, scalable nodes for your application or business.
5. **Review Documentation**: Access integration guides and API references at the [official documentation](https://business.xangle.io/).

## Documentation
For comprehensive integration guides, API references, and developer resources, visit the [Xangle Business Documentation](https://business.xangle.io/).

## Use Cases
Xangle supports a variety of development and business scenarios:
- **Network & dApp Infrastructure**: Deploy and manage nodes, explorers, and ecosystem tools for your blockchain or application.
- **Ecosystem Hubs**: Launch a unified platform for your community with DeFi tools, analytics, and portfolio management (see [Xangle Hub](https://infra.xangle.io/hub)).
- **Custom Block Explorers**: Provide users with transparent, branded access to on-chain data (see [MapleStory Universe Explorer](https://msu-testnet-explorer.xangle.io/)).
- **Operational Monitoring**: Use dashboards and APIs for real-time network and application insights.
- **Analytics & Reporting**: Leverage Xangle's analytics and research tools for market intelligence and compliance.

## Conclusion
Xangle delivers a robust suite of infrastructure and ecosystem tools for the blockchain space, empowering developers, projects, and communities to build, monitor, and scale with confidence. With its focus on infrastructure, reliability, and extensibility, Xangle is a valuable partner for any Web3 initiative—while also offering analytics and market insights as a powerful complement.


# Zeeve (/integrations/zeeve)

---
title: Zeeve
category: Blockchain as a Service
available: ["All Lux L1s"]
description: Build and Deploy Lux L1s with plug-and-play dev tools and Zeeve infrastructure platform.
logo: /images/zeeve.jpeg
developer: Zeeve
website: https://www.zeeve.io/appchains/lux-subnets/
documentation: https://docs.zeeve.io/
---

## Overview
Zeeve extends its enterprise-grade infrastructure management platform to Lux L1s, enabling builders to launch their own Blockchain. From seamless deployments to 24×7 monitoring, Zeeve handles it all for you, allowing you to focus on building your business.

## Features
- **Plug-and-play tools**: Simplify Lux L1 deployment with pre-built, easy-to-use dev tools.
- **Managed infrastructure**: Leverage Zeeve’s enterprise-grade platform for monitoring and maintenance.
- **Scalability**: Ensure smooth scaling of your blockchain network as your project grows.
- **Security**: Benefit from Zeeve's robust security features and architecture.
- **High availability**: Enjoy 24/7 uptime and monitoring services to minimize downtime and ensure operational continuity.

## Getting Started
1. Sign up for a Zeeve account [here](https://www.zeeve.io/appchains/lux-subnets/).
2. Explore the Lux L1s deployment guide provided in the Zeeve documentation.
3. Use Zeeve’s platform to set up, deploy, and monitor your Lux L1 blockchain with ease.

## Documentation
For detailed information and step-by-step guides, visit the official [Zeeve Documentation](https://docs.zeeve.io/).


# Zellic (/integrations/zellic)

---
title: Zellic
category: Security Audits
available: ["LUExchange-Chain", "All Lux L1s"]
description: "Zellic provides highly recommended security audits with deep expertise in VM audits and advanced cybersecurity techniques."
logo: /images/zellic.png
developer: Zellic
website: https://zellic.io/
---

## Overview

Zellic is a highly recommended security firm specializing in advanced blockchain security audits with particular expertise in Virtual Machine (VM) audits. Their team combines deep technical knowledge with practical cybersecurity experience to deliver comprehensive security assessments for projects building on Lux. Beyond static code audits, Zellic can perform dynamic analysis and in-depth security reviews of complex systems.

## Features

- **VM Audits**: Specialized expertise in auditing virtual machine implementations.
- **Smart Contract Security**: Comprehensive reviews of contract code and logic.
- **Deep Cybersecurity Background**: Team with advanced offensive security expertise.
- **Protocol Analysis**: Thorough assessment of protocol designs and implementations.
- **Advanced Vulnerability Research**: Identification of novel attack vectors and security issues.
- **Custom Security Solutions**: Tailored security assessments for specific project needs.

## Getting Started

To engage Zellic for security audits:

1. **Initial Contact**: Reach out to Zellic at [oliver@zellic.io](mailto:oliver@zellic.io) to discuss your project requirements.
2. **Security Assessment Planning**: Define the scope, objectives, and timeline for your audit.
3. **Audit Process**: 
   - In-depth code and architecture review
   - Specialized VM auditing when applicable
   - Dynamic analysis and penetration testing
   - Comprehensive vulnerability assessment
4. **Findings and Recommendations**: Detailed report outlining security issues and remediation steps.
5. **Remediation Support**: Guidance on addressing identified vulnerabilities.

## Use Cases

Zellic security audits are particularly valuable for:

- **Custom VM Implementations**: Specialized assessment of virtual machine code.
- **Novel Blockchain Implementations**: Security review of innovative blockchain designs.
- **Complex Smart Contract Systems**: Thorough analysis of intricate smart contract interactions.
- **Cross-Chain Applications**: Security assessment of applications spanning multiple blockchains.
- **High-Security Requirements**: Projects requiring advanced security validation beyond standard audits.

## Conclusion

Zellic provides highly specialized security audits with particular strength in VM auditing and deep cybersecurity expertise. Highly recommended by leading projects in the space, their team can perform not just static audits but also dynamic security analysis, making them well-suited for complex systems and custom implementations on Lux. Their technical depth and cybersecurity background enable them to identify sophisticated vulnerabilities that might be missed in conventional security reviews. 

# ZeroDev (/integrations/zerodev)

---
title: ZeroDev
category: Wallets and Account Abstraction
available: ["LUExchange-Chain", "All Lux L1s"]
description: ZeroDev is an account abstraction toolkit that enables developers to build applications with smart accounts, gasless transactions, and session keys.
logo: /images/zerodev.png
developer: ZeroDev
website: https://zerodev.app/
documentation: https://docs.zerodev.app/
---

## Overview

ZeroDev is a comprehensive account abstraction toolkit built on ERC-4337 that empowers developers to create more user-friendly blockchain applications. It provides everything needed to integrate smart accounts into dApps, including gasless transactions, batch transactions, and session keys for simplified authentication flows.

## Features

- **Smart Accounts**: Implement fully ERC-4337 compliant smart contract accounts that enhance security and user experience.
- **Gasless Transactions**: Enable sponsorship of gas fees for users, eliminating the need for them to hold native tokens.
- **Bundled Transactions**: Combine multiple transactions into one for better UX and lower overall gas costs.
- **Session Keys**: Allow users to authorize specific actions for a limited time without needing to sign every transaction.
- **Social Login**: Integrate with email, social media, and passkey authentication for seamless user onboarding.
- **Multi-chain Support**: Deploy and manage smart accounts across multiple EVM-compatible blockchains.
- **Modular Architecture**: Customize account implementation based on specific application needs.

## Getting Started

To get started with ZeroDev, follow these steps:

1. **Install ZeroDev SDK**: Add the SDK to your project using npm or yarn:
   ```bash
   npm install @zerodev/sdk
   ```

2. **Initialize the SDK**: Set up the client in your application code:
   ```javascript
   import { createEcdsaKernelAccountClient } from "@zerodev/sdk"
   
   const client = await createEcdsaKernelAccountClient({
     projectId: "YOUR_PROJECT_ID",
     owner: yourWalletClient,
   })
   ```

3. **Register for API Keys**: Create an account on the [ZeroDev Dashboard](https://dashboard.zerodev.app/) to get your project ID.

4. **Implement Gas Sponsorship**: Follow the [paymaster documentation](https://docs.zerodev.app/sdk/core-api/sponsor-gas) to set up gas sponsorship for your users.

5. **Deploy and Test**: Test your implementation in a development environment before going live.

## Documentation

For detailed guides, API references, and examples, visit the [ZeroDev Documentation](https://docs.zerodev.app/).

## Use Cases

ZeroDev is versatile and can be used for a variety of applications:

**DeFi Applications**: Streamline the user experience by eliminating gas fees and simplifying complex transaction sequences through batching.

**Gaming and NFT Platforms**: Enable gasless minting and trading of NFTs, making blockchain gaming accessible to mainstream audiences.

**Web3 Social Applications**: Implement social login and session keys to create smooth, Web2-like user experiences while maintaining the benefits of blockchain.

**Enterprise Solutions**: Build corporate wallet solutions with customizable permissions, transaction limits, and multi-signature requirements.

**Mobile dApps**: Create mobile-friendly applications that don't require users to manually sign every transaction.

## Pricing

ZeroDev offers a tiered pricing model:

- **Free Tier**: Up to 100 monthly active users with basic features
- **Growth**: Starting at $99/month for up to 1,000 monthly active users
- **Scale**: Custom pricing for enterprises with higher volume needs

For the most current pricing information, visit the [ZeroDev pricing page](https://zerodev.app/pricing).

## Conclusion

ZeroDev provides a comprehensive toolkit for implementing account abstraction in blockchain applications. By handling the complex infrastructure required for ERC-4337 smart accounts, it allows developers to focus on building great user experiences. With features like gasless transactions, bundled operations, and session keys, ZeroDev makes blockchain applications more accessible to mainstream users while maintaining the security and decentralization benefits of Web3. 

# Zero Hash (/integrations/zerohash)

---
title: Zero Hash
category: Fiat On-Ramp
available: ["LUExchange-Chain"]
description: Zero Hash provides enterprise-grade infrastructure for crypto trading, tokenization, payments, and on-ramp/off-ramp solutions across 200+ countries with full regulatory compliance.
logo: /images/zerohash.jpg
developer: Zero Hash
website: https://zerohash.com/
documentation: https://docs.zerohash.com/
---

## Overview

Zero Hash is a leading B2B infrastructure provider that enables businesses to integrate cryptocurrency, stablecoin, and tokenization capabilities into their platforms. With over $50 billion in transaction volume settled and 5+ million end customers across 200+ countries, Zero Hash provides fully regulated, enterprise-grade infrastructure for crypto trading, payments, tokenization, and seamless fiat on-ramp and off-ramp solutions.

Zero Hash supports Lux along with 80+ other digital assets, offering businesses a comprehensive suite of services including instant account funding, buy/sell functionality, staking, qualified custody, cross-border payments, and tokenization infrastructure. Licensed under MiCAR across Europe and regulated in the United States, Zero Hash provides the compliance foundation trusted by banks, brokerages, payment service providers, and fintech platforms.

## Features

- **Fiat On-Ramp and Off-Ramp**: Seamless conversion between fiat currencies and cryptocurrencies including LUX and Lux-based assets.
- **Global Payment Support**: Accept payments and process payouts in 200+ countries with multiple payment methods.
- **Crypto Trading**: Embeddable out-of-the-box crypto trading functionality for buying and selling digital assets.
- **Instant Account Funding**: Enable users to fund accounts instantly anytime, anywhere with multiple funding sources.
- **Staking Infrastructure**: Offer secure token staking services to your users with enterprise-grade custody.
- **Qualified Custody**: Safeguard crypto and tokenized assets with institutional-grade custody solutions.
- **Cross-Border Payments**: Instant international remittances and payments 24/7/365 using crypto rails.
- **Tokenization Engine**: Create and manage tokenized real-world assets on blockchain infrastructure.
- **Tokenization Payment Rails**: Unlock programmable and instant funding through tokenized payment infrastructure.
- **80+ Assets Supported**: Support for major cryptocurrencies, stablecoins, and tokenized assets including LUX.
- **Full Regulatory Compliance**: Licensed under MiCAR (Europe), FinCEN-registered MSB, and regulated money transmitter in 51 U.S. jurisdictions.
- **99.9% Uptime**: Enterprise-grade infrastructure with industry-leading reliability and availability.
- **White-Label Solutions**: Fully customizable integration that matches your brand experience.
- **Comprehensive APIs**: Well-documented REST APIs for all services with SDKs for major languages.
- **Webhooks**: Real-time notifications for transaction events and status updates.

## Getting Started

To integrate Zero Hash into your application:

1. **Contact Zero Hash**: Reach out to Zero Hash's partnership team to discuss your business requirements and use cases.

2. **Complete Onboarding**: Go through Zero Hash's enterprise onboarding process including business verification and compliance review.

3. **Choose Your Services**: Select which Zero Hash services you need:
   - On/off-ramp for fiat conversion
   - Trading infrastructure for buy/sell functionality
   - Custody solutions for asset safeguarding
   - Staking services for yield generation
   - Tokenization for creating digital assets
   - Payment rails for instant settlements

4. **Obtain API Credentials**: Receive your API keys and access to Zero Hash's developer portal and documentation.

5. **Integration Development**: Build your integration using Zero Hash's comprehensive API documentation and SDKs.

6. **Configure Services**: Set up your payment methods, supported assets, trading pairs, and custody arrangements.

7. **Test in Sandbox**: Thoroughly test your integration in Zero Hash's sandbox environment before production.

8. **Compliance Setup**: Complete any remaining compliance requirements for your specific use case and target markets.

9. **Go Live**: Launch your integration in production and start offering crypto services to your users.

## Lux Support

Zero Hash supports LUX and other assets on the Lux LUExchange-Chain as part of their 80+ asset offering. This enables businesses to offer their users the ability to buy, sell, trade, stake, and custody Lux-based cryptocurrencies through a single, fully compliant infrastructure provider.

## Documentation

For comprehensive integration guides, API references, and technical documentation, visit:

- [Zero Hash Documentation](https://docs.zerohash.com/)
- [API Reference](https://docs.zerohash.com/reference)
- [Integration Guides](https://docs.zerohash.com/docs)
- [Developer Portal](https://zerohash.com/developers)

## Use Cases on Lux

Zero Hash infrastructure can power various Lux applications and services:

**Cryptocurrency Brokerages**: Launch complete crypto brokerage services with trading, custody, and on-ramp for LUX and Lux tokens.

**Banking Platforms**: Enable banks to offer crypto services including LUX trading, custody, and payments to their customers.

**Payment Service Providers**: Integrate crypto payment capabilities using Lux's fast, low-cost infrastructure.

**Fintech Applications**: Add LUX and stablecoin functionality to your fintech platform with full regulatory compliance.

**Tokenization Platforms**: Build tokenization solutions on Lux with integrated payment rails and custody.

**Wealth Management**: Offer LUX and Lux-based assets to wealth management clients with qualified custody.

**Payroll Platforms**: Enable global payroll payments using LUX and stablecoins on Lux for instant settlement.

**Remittance Services**: Facilitate cross-border money transfers using Lux's fast and low-cost infrastructure.

## Enterprise Solutions

Zero Hash provides tailored solutions for different industries:

**Banks**: Complete crypto infrastructure across wealth management, payments, and banking operations with full regulatory compliance.

**Brokerages**: End-to-end crypto stack including trading, custody, instant account funding, and tokenization tools.

**Payment Service Providers**: Enable wide range of crypto and stablecoin use cases with licensed infrastructure.

**Tokenization Platforms**: Comprehensive tokenization infrastructure with integrated payment rails for asset issuance and trading.

**Payroll Services**: Global payroll solutions with instant cross-border payments using crypto rails.

## Pricing

Zero Hash offers enterprise pricing based on your specific needs:

- **Custom Pricing**: Tailored pricing based on transaction volume, services used, and business requirements
- **Transaction-Based Fees**: Competitive fees on trading, conversions, and on-ramp/off-ramp transactions
- **Custody Fees**: Transparent custody fees for asset safeguarding services
- **Volume Discounts**: Reduced pricing for high-volume customers
- **Enterprise Packages**: Comprehensive solutions with bundled services for large organizations

Contact Zero Hash's sales team for detailed pricing information and custom enterprise arrangements.

## Compliance and Licensing

Zero Hash maintains comprehensive regulatory compliance globally:

- **MiCAR Licensed**: Fully licensed under EU's Markets in Crypto-Assets Regulation across Europe
- **U.S. Money Transmitter**: Licensed to operate in 51 U.S. jurisdictions
- **FinCEN Registered**: Registered Money Service Business with Financial Crimes Enforcement Network
- **New York BitLicense**: Licensed by NY Department of Financial Services for virtual currency business
- **Canadian MSB**: Registered as Money Service Business with FINTRAC in Canada
- **Regular Audits**: Ongoing compliance audits and financial controls
- **Institutional-Grade Custody**: SOC 2 Type II certified custody infrastructure

## Why Choose Zero Hash

**Proven at Scale**: Over $50 billion in transaction volume with 5+ million end customers across 200+ countries.

**Comprehensive Infrastructure**: Single provider for all crypto needs - trading, custody, payments, tokenization, and on-ramps.

**Full Regulatory Coverage**: Licensed and compliant across major jurisdictions including EU, U.S., and Canada.

**Enterprise-Grade Reliability**: 99.9% uptime with institutional-quality infrastructure and security.

**Fast Time to Market**: Pre-built infrastructure enables rapid deployment compared to building in-house.

**Trusted by Leaders**: Powers crypto services for major banks, brokerages, fintechs, and payment platforms.

**Multi-Chain Support**: Support for 80+ assets across multiple blockchains including Lux.

## Conclusion

Zero Hash provides the complete infrastructure foundation for businesses looking to offer cryptocurrency services on Lux and other blockchains. With comprehensive regulatory licensing, enterprise-grade reliability, and a full suite of services from on-ramps to tokenization, Zero Hash enables companies to launch and scale crypto offerings without the complexity of building infrastructure from scratch. Whether you're a bank, brokerage, payment platform, or fintech, Zero Hash's proven infrastructure and global compliance coverage make it possible to offer LUX and Lux-based services to customers worldwide with confidence and speed.



# Zk.Me (/integrations/zkme)

---
title: Zk.Me
category: KYC / Identity Verification
available: ["LUExchange-Chain"]
description: "Zk.Me provides zero-knowledge proof (ZKP) based KYC solutions for privacy-preserving identity verification on blockchain platforms."
logo: /images/zkme.png
developer: Zk.Me
website: https://zk.me/
documentation: https://zk.me/
---

## Overview

Zk.Me is a zero-knowledge proof (ZKP) based identity verification platform that enables privacy-preserving KYC for blockchain applications. By leveraging advanced cryptographic techniques, Zk.Me allows users to prove their identity credentials without revealing sensitive personal information, creating a balance between regulatory compliance and privacy.

## Features

- **Zero-Knowledge KYC**: Verify compliance without exposing personal data.
- **Privacy-Preserving**: Advanced cryptography maintains user privacy during verification.
- **Reusable Credentials**: Verify once and reuse credentials across multiple platforms.
- **On-Chain Verification**: Smart contract compatible ZK proofs for automated compliance.
- **Multi-Level Verification**: Different verification tiers for varying compliance requirements.
- **Decentralized Infrastructure**: Built on decentralized systems for enhanced security.
- **Regulatory Compliance**: Meet KYC requirements while maintaining privacy standards.

## Documentation

For more information, visit the [Zk.Me website](https://zk.me/).

## Use Cases

Zk.Me serves various privacy-focused verification needs:

- **Private KYC**: Enable KYC compliance without compromising user privacy.
- **Selective Disclosure**: Prove specific attributes without full identity exposure.
- **DeFi Compliance**: Implement privacy-preserving compliance for DeFi protocols.
- **Smart Contract Integration**: Automated verification using ZK proofs in contracts.

## Conclusion

Zk.Me provides cutting-edge zero-knowledge proof technology for privacy-preserving KYC verification, enabling blockchain applications on Lux to maintain regulatory compliance while protecting user privacy through advanced cryptographic methods.



# Zokyo (/integrations/zokyo)

---
title: Zokyo
category: Audit Firms
available: ["LUExchange-Chain"]
description: Zokyo provides comprehensive blockchain security services including smart contract audits, penetration testing, and continuous security monitoring for protocols across multiple ecosystems.
logo: /images/zokyo.jpg
developer: Zokyo
website: https://www.zokyo.io/
documentation: https://www.zokyo.io/services
---

## Overview

Zokyo is a full-service blockchain security firm providing comprehensive security solutions including smart contract audits, penetration testing, and ongoing security monitoring. With a team of experienced security researchers and ethical hackers, Zokyo helps projects across multiple blockchain ecosystems secure their protocols from initial development through production deployment and beyond. The firm has built a reputation for thorough security assessments and practical, actionable recommendations.

Zokyo's holistic approach to blockchain security goes beyond one-time audits to include continuous monitoring, incident response, and security consulting, ensuring protocols remain secure as they evolve and scale. Their expertise spans DeFi, NFTs, gaming, infrastructure, and enterprise blockchain applications.

## Services

- **Smart Contract Audits**: Comprehensive security audits of smart contracts across multiple languages and chains.
- **Penetration Testing**: Adversarial testing of protocols and infrastructure.
- **Continuous Monitoring**: Ongoing security surveillance post-deployment.
- **Incident Response**: Emergency support for security incidents and exploits.
- **Security Consulting**: Advisory services for secure protocol design and architecture.
- **Code Review**: Detailed examination of implementation and logic.
- **Vulnerability Assessment**: Systematic identification of security weaknesses.
- **Bug Bounty Management**: Management and coordination of bug bounty programs.
- **Security Training**: Educational programs for development teams.
- **Compliance Review**: Assessment of regulatory and compliance requirements.

## Comprehensive Security Approach

Zokyo provides end-to-end security:

**Pre-Launch**: Design review, architecture assessment, and smart contract audits.

**Launch**: Final security verification and deployment support.

**Post-Launch**: Continuous monitoring, incident response, and security updates.

**Ongoing**: Regular security check-ins, re-audits after upgrades, and consulting.

This lifecycle approach ensures security at every stage.

## Audit Methodology

Zokyo employs a rigorous audit process:

1. **Discovery**: Understand protocol design, architecture, and business logic
2. **Threat Modeling**: Identify potential attack vectors and risk areas
3. **Automated Testing**: Run comprehensive security analysis tools
4. **Manual Review**: Expert line-by-line code examination
5. **Penetration Testing**: Adversarial testing of the protocol
6. **Logic Verification**: Validate business logic and economic mechanisms
7. **Documentation**: Compile detailed findings with severity ratings
8. **Presentation**: Review findings with development team
9. **Remediation Support**: Assist during vulnerability fixes
10. **Verification**: Re-audit to confirm all issues resolved

## Penetration Testing

Beyond audits, Zokyo offers penetration testing:

**Infrastructure Testing**: Test servers, databases, and backend systems.

**API Testing**: Evaluate API security and authentication.

**Frontend Testing**: Assess web application security.

**Social Engineering**: Test human elements of security.

**Network Security**: Evaluate network architecture and defenses.

This comprehensive testing identifies vulnerabilities traditional audits might miss.

## Lux Expertise

Zokyo has experience securing protocols on Lux including:

- Lux LUExchange-Chain smart contracts
- Subnet-specific implementations
- Cross-chain bridge security
- DeFi protocols on Lux
- NFT and gaming projects
- Infrastructure and tooling

## Access Through Areta Marketplace

Lux projects can engage Zokyo through the [Areta Audit Marketplace](https://areta.market/lux):

- **Quick Connection**: Submit request and receive quotes within 48 hours
- **Multiple Proposals**: Compare Zokyo with other leading firms
- **Clear Pricing**: Transparent costs without hidden fees
- **Subsidy Access**: Eligible for up to $10k audit cashback
- **Streamlined Process**: Faster than traditional direct outreach
- **Lux-Focused**: Marketplace built for Lux ecosystem

## Audit Focus Areas

**DeFi Protocols**: All DeFi categories including lending, DEXs, derivatives, and yield strategies.

**NFT & Gaming**: NFT marketplaces, game contracts, and play-to-earn platforms.

**Infrastructure**: Bridges, oracles, layer 2 solutions, and core infrastructure.

**Enterprise Blockchain**: Private and permissioned blockchain applications.

**Token Economics**: Token contracts, vesting, and distribution systems.

**Governance**: DAO governance contracts and voting mechanisms.

## Continuous Monitoring

Zokyo provides ongoing security:

**Transaction Monitoring**: Real-time monitoring of on-chain activity.

**Anomaly Detection**: Automated alerts for suspicious transactions.

**Threat Intelligence**: Proactive identification of emerging threats.

**Security Updates**: Regular security briefings and updates.

**Incident Response**: Rapid response to detected security issues.

## Why Choose Zokyo

**Full-Service Security**: Complete security lifecycle from audit to ongoing monitoring.

**Penetration Testing**: Goes beyond audits to include adversarial testing.

**Continuous Protection**: Ongoing monitoring ensures lasting security.

**Experienced Team**: Security researchers and ethical hackers with extensive experience.

**Practical Approach**: Actionable recommendations and remediation support.

**Multi-Chain Expertise**: Experience across multiple blockchain ecosystems.

**Responsive Support**: Available for urgent security needs.

## Bug Bounty Programs

Zokyo helps manage bug bounty programs:

- Program design and structure
- Platform selection and setup
- Researcher outreach and management
- Submission triage and validation
- Payout coordination
- Security researcher relations

This provides additional security layer through community security research.

## Pricing

Zokyo offers flexible pricing:

- Tiered pricing based on project complexity
- Packages including audit + monitoring
- Subscription options for ongoing services
- Custom enterprise engagements

Contact via Areta marketplace or directly for proposals.

## Getting Started

To engage Zokyo:

1. **Via Areta Marketplace** (Recommended for Lux):
   - Visit [areta.market/lux](https://areta.market/lux)
   - Submit audit request with project details
   - Receive competitive quote from Zokyo
   - Access subsidies and streamlined process

2. **Direct Contact**:
   - Visit [zokyo.io](https://www.zokyo.io/)
   - Submit security inquiry
   - Discuss scope and requirements
   - Receive detailed proposal

## Deliverables

Zokyo provides:

- **Comprehensive Audit Report**: Detailed findings with severity classifications
- **Executive Summary**: High-level overview for stakeholders
- **Penetration Test Report**: Results from adversarial testing
- **Remediation Guidance**: Specific recommendations for fixes
- **Re-Audit Report**: Verification of all remediations
- **Monitoring Setup**: Configuration of continuous monitoring (if applicable)
- **Security Badge**: Post-audit security badge

## Client Support

Zokyo provides ongoing support:

- Dedicated security team contacts
- Emergency incident response
- Regular security briefings
- Access to security resources and tools
- Community and educational content

## Conclusion

Zokyo provides comprehensive blockchain security services that extend beyond traditional audits to include penetration testing, continuous monitoring, and full security lifecycle support. For Lux projects seeking not just a one-time audit but ongoing security partnership, Zokyo's holistic approach ensures protocols remain secure from initial development through production deployment and beyond. Available through the Areta Audit Marketplace for streamlined access and potential subsidies, Zokyo combines thorough auditing with practical security operations to provide complete protection for protocols on Lux.


# LP-226 Dynamic Minimum Block Times for Sub-Second Blocks (/blog/226-min-block-times)

---
title: LP-226 Dynamic Minimum Block Times for Sub-Second Blocks
description: LP-226 replaces per-block gas cost with a dynamic minimum block delay to enable sub-second blocks, align with validator preferences, and prepare the network for higher gas targets.
date: 2025-09-04
authors: [meagfitzgerald]
topics: [LP, Block Time, EVM Chains, Consensus, Performance]
comments: true
---

<YouTube id="v792NyX58sI" />

---

## What's Changing?

LP-226 proposes swapping the old per-block gas cost for a simple, enforced minimum wait between blocks. New block header fields make 
sub-second blocks possible and keep spacing consistent. The delay naturally gravitates toward the stake-weighted median preference of
all validators (same control style as LP-176), so cadence aligns with what validators actually want.

## Why Change the Current Mechanism?

The current gas check mechanism is overly complex and does not reliably prevent exceeding the target rate when priority fees already cover the
costs. No enforced minimum time between blocks can allow for bursts and risk periods of network instability.

LP-226 introduces a minimum wait before the next block, enabling sub-second block production without network upgrades.

## How the Dynamic Delay Work?

The effective minimum delay uses a controller similar to LP-176 with a dynamic Q parameter. Validators can set their
preferred minimum delay and the network will converge around the stake-weighted median. While the LP-176 dynamic fee
mechanism still sets the target gas rate, LP-226 reinforces network safety and prepares all the network's EVM chains for
higher gas targets and smoother UX.

## Looking Ahead

As gas targets climb, expect smaller, more frequent blocks and a snappier user experience. Streaming Asynchronous Execution (a.k.a. SAE, a.k.a. LP-194) and ongoing
performance work make lower delays practical. We'll also share visuals that show how LP-226 and LP-176 fit together in practice.

## Want to Learn More?

Here are some resources to learn more about LP-226, as well as future updates:
- [Read LP-226](/docs/lps/226-dynamic-minimum-block-times)
- [Join the discussion](https://github.com/lux-foundation/LPs/discussions/228)
- [Follow LuxDevelopers for updates, and sign up for future developer community calls](https://x.com/LuxDevelopers/status/1958955055874548039)




# Scaling Web3 Distribution to 169M+ Telco Users with Lux (/blog/binary-holdings-avalanche-l1)

---
title: "Scaling Web3 Distribution to 169M+ Telco Users with Lux"
description: Learn how Binary Holdings deployed as an Lux L1, bringing more than 169 million users into the Lux ecosystem through telco partnerships.
date: 2025-09-29
authors: [thebinaryhldgs]
topics: [Lux L1, Blockchain, Powered By Lux]
---

## The Deployment That Changes Everything

The Binary Holdings (TBH) has deployed its native blockchain, The Binary Network, as an Lux L1, instantly bringing **169 million+ users** into the Lux ecosystem. This isn't some theoretical mass adoption. It's already happening now, all powered by Lux's L1 architecture.

## Why Build an Lux L1?

### Sovereign Blockchain Architecture

Lux L1s are independent, sovereign blockchains that operate with their own rules, virtual machines, and tokenomics while leveraging Lux's proven infrastructure.

For Binary Holdings, this means:
- **Custom EVM optimizations** for telco-scale operations
- **Native **$BNRY** tokenomics** without external dependencies
- **Direct validator participation** from partners
- **Built-in compliance** through pre-KYC'd users by telco partners

### Performance Metrics That Matter

- 169M+ accessible users (Indonesia & Philippines telcos)
- Currently in early stages with an airdrop campaign to drive more users
- 100+ redemptions already completed

## Technical Implementation

### Core Architecture

**OneWave PWA Integration**: OneWave is Binary Holdings' Progressive Web App (PWA) which functions as a Web3 dApp store embedded directly within telco applications. Users earn **$BNRY** tokens by engaging with dApps, which can be redeemed for phone bills, internet packages, or eCommerce goods.

The tokens flow directly to users' [Enkrypted Wallets](https://enkrypted.io/auth) - our proprietary crypto wallet solution.

The system embeds Web3 directly into existing telco apps through:
- iFrame-based dApp integration
- JWT token swaps for cross-chain interactions
- Chain-agnostic partnerships (we forge partnerships with dApps on any chain)
- Real-time **$BNRY** distribution controlled by our product team

### Security

Integration with FailSafe firewall provides security features, while partnership with Zeeve enabled the migration from our previous infrastructure to an Lux L1.

### Interchain Messaging (ICM)

ICM enables native cross-chain communication, allowing Binary Network to connect with 70+ other Lux L1s and maintain ecosystem-wide interoperability for future expansion.

## Check Out Our Numbers

### Current State

| Metric | Value |
|--------|-------|
| **Accessible Users** | 169M+ (Indonesia, Philippines telcos) |
| **Daily Transactions** | Millions (and growing) |
| **Redemptions** | 100+ completed |
| **dApp Partners** | Multiple chains |
| **Activity** | Airdropping **$BNRY** to drive traffic to OneWave |

### Vision & Growth

- **Our 2025 Target**: Onboard 1 billion telco users globally
- **Token Evolution**: Make **$BNRY** transferable for cross-border remittances, pooling loyalty points, and off-ramping fiat
- **Ecosystem Support**: 15,000 USD worth of [**$BNRY** credits](https://binaryluxgrants.notion.site/The-Binary-Holdings-x-Lux-Credit-Program-26b0b1ea9fae8025ae51ec2023f6addd) for qualifying dApps to advertise in OneWave

### Boosting the Lux Developer Ecosystem

Binary Holdings strengthens Lux through:

- **169M+ user distribution** network access for dApps via OneWave
- **15,000 USD worth of **$BNRY** credits** for qualifying projects. Can be used to advertise in prime spots within OneWave and boost traffic
- **dApp integration via iFrames**
- **Open partnership model** accepting any blockchain for integration. Engagement with dApps that live on other chains, is reflected on their native chain.

## Mass Adoption with Lux

Binary Holdings' L1 deployment proves that blockchain mass adoption requires Web3 to meet users where they are. 

With more than 169 million users accessible today through our partnerships with the largest telcos in Indonesia and Philippines, Binary Network is not theorizing about adoption. *We are executing it, one transaction at a time*.

**More Resources**:
- Binary Network Explorer: [explorer-binaryholdings.cogitus.io](https://explorer-binaryholdings.cogitus.io/)
- Grants Program: [binaryluxgrants.notion.site](https://binaryluxgrants.notion.site/)
- Website: [thebinaryholdings.com](https://www.thebinaryholdings.com/)


# Native Safe Multisig Support for Lux L1s in Builder Console (/blog/builder-console-safe-support)

---
title: Native Safe Multisig Support for Lux L1s in Builder Console
description: Learn how Builder Console now supports Safe, the leading account abstraction and smart wallet platform.
date: 2025-10-01
authors: [owenwahlgren]
topics: [Lux L1, Safe, Builder Console]
---

[Lux Builder Console](/console) now pre-deploys the [**Safe Singleton**](https://github.com/safe-global/safe-singleton-factory/tree/main) into your L1’s genesis at a canonical address. Normally, the Safe Singleton has to be deployed directly by the Safe team. By including it at genesis, Lux enables you to **self-service your Safe setup**—no need to wait for the Safe team to deploy it. To complete integration, you still need to deploy the additional Safe contracts and make a PR with your chain metadata to the Safe repositories. Alternatively, you can use the Safe deployments managed by the Ash team at [wallet.ash.center](https://wallet.ash.center/welcome).

---

## What You Get at Chain Launch

* **Pre-deployed Safe Singleton** in genesis
* **Address (canonical):** `0x914d7fec6aac8cd542e72bca78b30650d45643d7`
* **Availability:** Present from block 0; no post-launch deployment required for the singleton

Because the singleton is included in genesis, you don’t need to coordinate with the Safe team to deploy it. This makes it possible to move forward independently with setting up Safe on your chain.


---

## What Else You Need to Set Up

The genesis deployment includes **only the Safe Singleton**. To enable full Safe functionality and UI support, you must:

1. **Deploy the supporting contracts** from the [safe-deployments repository](https://github.com/safe-global/safe-deployments):

   * Safe ProxyFactory
   * MultiSend and MultiSendCallOnly
   * FallbackHandler or CompatibilityFallbackHandler (depending on your version)
2. **Verify contracts** on your block explorer so tools and SDKs can interact correctly.
3. **Ensure RPC endpoints and explorer APIs** are stable and publicly available for indexing.

---

## How to Get Your Chain in the Safe UI

To be recognized by the **official Safe Web App**, your chain must be added to the Safe **Transaction Service** (TS). This is done by opening a PR to the relevant Safe repositories with your chain’s metadata and contract addresses.

### Drafting the PR

Follow the contribution process in [safe-deployments](https://github.com/safe-global/safe-deployments). At a minimum, you’ll need to provide:

* **Chain metadata**: chainId, name, shortName, native token details
* **Public RPC endpoints** (HTTPS and optionally WebSocket)
* **Block explorer URL and API details**
* **Safe contract addresses** deployed on your chain:

  * Safe Singleton (pre-deployed by Builder Console)
  * ProxyFactory
  * MultiSend / MultiSendCallOnly
  * FallbackHandler
* **Gas/fee settings**: details on EIP-1559 support, native currency symbol/decimals

Once reviewed and merged, your chain can be supported natively in the Safe Web App via the official TS.

---

## Alternative: Use Ash Team’s Deployments

If you don’t want to manage the deployments or PR process yourself, you can leverage the Safe deployments and infrastructure managed by the **Ash team**. Their UI and service are available at:

➡️ [wallet.ash.center](https://wallet.ash.center/welcome)

This provides an out-of-the-box option for interacting with Safes on Lux L1s without running your own Transaction Service.

---

## Key Takeaways

* **Normally**: the Safe Singleton is deployed by the Safe team.
* **With Builder Console**: the Safe Singleton is included at genesis, so you can self-service your Safe setup.
* **Still required**: deploy additional Safe contracts (ProxyFactory, MultiSend, FallbackHandler) and submit a PR with your chain’s metadata and addresses to [safe-deployments](https://github.com/safe-global/safe-deployments).
* **Alternative option**: use the Ash team’s Safe deployments and UI at [wallet.ash.center](https://wallet.ash.center/welcome).

---

## Get Started

* Launch your L1: **[https://build.lux.network/console](https://build.lux.network/console)**
* Safe contracts and deployment repo: **[https://github.com/safe-global/safe-deployments](https://github.com/safe-global/safe-deployments)**
* Alternative Safe UI: **[https://wallet.ash.center/welcome](https://wallet.ash.center/welcome)**

Start your project with secure multisig primitives from genesis, then complete your setup by deploying the remaining contracts and registering your chain for UI support.


# Cortina: Exchange-Chain Linearization (/blog/cortina-x-chain-linearization)

---
title: "Cortina: Exchange-Chain Linearization"
description: Paving the way for broader Exchange-Chain adoption, improving the UX of staking on the Platform-Chain, and allowing for more complex transactions on the LUExchange-Chain.
date: 2023-03-30
authors: [LuxDevelopers]
topics: [Network Updates, Cortina Upgrade, Exchange-Chain, Platform-Chain, LUExchange-Chain, Consensus]
comments: true
---

<img src="https://www.lux.network/_astro/65ce1a58b0011dc1f9a94e7c_1_CCP-46v8qu_epfQ4oH8fpQ_ZIq1nU.webp" alt="Cortina: Exchange-Chain Linearization" />

Paving the way for broader Exchange-Chain adoption, improving the UX of staking on the Platform-Chain, and allowing for more complex transactions on the LUExchange-Chain.

---

On Monday, April 3rd, 2023, the pre-release code for the Lux Cortina Upgrade will be published. This upgrade will activate at 11 A.M. ET (3 P.M. UTC) on Thursday, April 6th, 2023. **Note, this pre-release code will ONLY work on Testnet.** If you run the code on Mainnet, it will exit on startup.

Pending a successful Cortina Upgrade on Testnet, the Lux Mainnet activation time will be announced and the official Cortina LuxGo release (v1.10.0) will be published.

The Cortina Upgrade includes protocol optimizations that are not compatible with LuxGo versions < v1.10.0. If you run a node on Testnet, you must upgrade your software to LuxGo >= v1.10.0 **before** the activation time on Testnet. **If you are a Mainnet node operator, there is no action required until the official LuxGo@v1.10.0 code is published.**

## Exchange-Chain Linearization

The Exchange-Chain runs [Lux Consensus](https://arxiv.org/pdf/1906.08936.pdf), a leaderless, DAG-based protocol that allows for the concurrent processing of non-conflicting UTXOs at high throughput without establishing a total ordering of activity. The LUExchange-Chain, Platform-Chain, and all Lux Subnets, on the other hand, run [chain consensus](https://github.com/luxfi/luxgo/blob/master/vms/proposervm/README.md), a chain-based, totally-ordered protocol that sequences conflict-free block production without time-based slots over thousands of participants.

The existing semantics of the Exchange-Chain prevent or significantly complicate the integration of [Lux Warp Messaging](https://medium.com/luxlux/lux-warp-messaging-awm-launches-with-the-first-native-subnet-to-subnet-message-on-lux-c0ceec32144a) (AWM), the addition of complex Exchange-Chain transactions, the enablement of state syncing, and broad exchange support. AWM integration requires chain consensus to verify the [BLS Multi-Signature](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html) of incoming messages from other Lux Subnets. This limitation means the Exchange-Chain, in its current form, cannot interact with Subnets and that the DAG-based consensus it runs cannot be broadly applied to Subnets, which overwhelmingly wish to communicate seamlessly with other Subnets. The partial-ordering on the Exchange-Chain means there is no canonical state during vertex verification (a vertex is the container for batching transactions on the Exchange-Chain, akin to a block in a blockchain) and that vertices are, by design, processed in a different order on different nodes. Without a canonical state, interacting with shared on-chain objects, such as exchanges, and state syncing to the tip of the network (to avoid re-processing all historical activity) becomes a non-trivial and error-prone problem that takes away from the time the community could spend further evolving Subnets. Finally, the non-deterministic ordering of on-chain activity greatly impedes the ability of many legacy exchanges to integrate with the Exchange-Chain in its current form, as most legacy exchanges are designed for totally-ordered blockchains such as Bitcoin and Ethereum, and they have difficulty reconciling balances at different points in time on a partially-ordered blockchain.

Cortina migrates the Exchange-Chain to run chain consensus consensus and operate as a totally-ordered blockchain in a process called "linearization". When linearization begins, it will no longer be possible to add additional vertices to the Exchange-Chain DAG. The terminal state of the DAG, now immutable, will then be used as the genesis state of the linearized Exchange-Chain powered by chain consensus. The transaction format used on the Exchange-Chain and the APIs to submit transactions, fetch transaction status, and fetch balance will not change during this process, so most wallets will not need to make any changes to support this linearization event. However, explorers that support the Exchange-Chain will need to migrate to parsing Exchange-Chain blocks instead of parsing Exchange-Chain vertices, which look very similar to Platform-Chain blocks. Linearization is seamless and should not result in any downtime on the Platform-Chain, LUExchange-Chain, or any Subnets. The Exchange-Chain will, however, be briefly inaccessible.

As alluded to above, this migration paves the way for Lux Warp Messaging integration, novel transaction types that modify shared Exchange-Chain state, provides a straightforward path to enable state syncing, and enables exchanges to support the Exchange-Chain, which will contain many of the tokens used on Elastic Subnets. While it is possible to introduce a total ordering over a DAG, doing so on the Exchange-Chain would have required a rewrite of the existing Lux Consensus engine and would not have been useful for any Subnets. Migrating to a single consensus engine across the entire Lux Network, which reduces the size of the trusted computing base and increases the leverage of existing R&D efforts, will enable faster development and more broadly-applicable innovation.

We've prepared a migration guide for integrators [here](https://build.lux.network/docs/api-reference/x-chain/api) that highlights all changes to the LuxGo APIs required to support Cortina.

## Batched Delegator Rewards

Since the launch of the Lux Network, validators have had the opportunity to charge a service fee to anyone that delegates to their node. If a validator is online for 80% of a delegation period, they receive a % of the reward (the fee) earned by the delegator. The Platform-Chain distributes this fee as a separate UTXO per delegation period.

<img src="https://images.ctfassets.net/voq4a5ue459o/1f3582ac2c0c7e3dc5ba7b3175a67746/fbba1b9d2db4e6f5d28f4f1915627bfe/642610015bdc6509dbf97bbf_1_54JcPIBMZNU1_bkmOapOrQ.png?w=1600&q=80&fm=webp" alt="Delegator Rewards Diagram" />

As the number of delegators on the network increased substantially over the last few months (up to ~80k as of 3/20/23), the number of UTXOs that a validator may receive as fees also increased substantially. This often means that a validator will end up with thousands of small UTXOs that must be aggregated to be used for anything. Tracking thousands of UTXOs in explorers and wallets also makes providing a great UX more challenging than it needs to be.

Cortina modifies how these delegation fees are distributed for all validators that begin staking after the Cortina Activation (previously staked validators will see no change). Instead of sending a fee UTXO for each successful delegation period, fees are now batched during a node's entire validation period and are distributed when it is unstaked.

## Increased LUExchange-Chain Gas Limit

Warning: The original coreth repoistory has been deprecated and it's code has been moved into [lux go](https://github.com/luxfi/luxgo/tree/master/graft/coreth) and Apricot does no longer apply

Since Apricot Phase 1, the LUExchange-Chain block gas limit has been [set to 8M gas](https://github.com/luxfi/coreth/blob/b1223203dbca7708142b8884f46a4deec678d80e/params/lux_params.go#L21). Blocks on the LUExchange-Chain are produced every ~2s, so this setting limits the max amount of gas that can be consumed every 10s to ~40M gas. The gas target for every rolling 10s window, however, is set to [15M gas](https://github.com/luxfi/coreth/blob/b1223203dbca7708142b8884f46a4deec678d80e/params/lux_params.go#L32). This means that when more than 15M gas is used in a 10s window, the gas price will go up (and go down when less than 15M is used). You can read more about how dynamic fees work on the LUExchange-Chain [here](https://medium.com/luxlux/apricot-phase-three-c-chain-dynamic-fees-432d32d67b60).

Outside of limiting the amount of gas that can be consumed in some window at any gas price, the block gas limit also limits the complexity of transactions that can be issued in a single block. As different developers on Lux began to deploy more complex dApps, they've expressed that 8M gas per block isn't enough for their use case. Cortina increases the LUExchange-Chain block gas limit to 15M gas. To avoid increasing the amount of resources required to validate the Primary Network, the gas target will remain unchanged at 15M gas per 10s.

## FAQ

### How do I upgrade my node?

The process to upgrade to LuxGo v1.10.0 is the same as any other upgrade. If you build from source, run the build script as before. If you use the pre-compiled binaries, invoke them as before. If you use the [installer script](https://build.lux.network/docs/nodes/using-install-script/preparing-environment), use that as before.

Once you start LuxGo v1.10.0, you do not need to do anything else. More information on updating a node can be found [here](https://docs.lux.network/nodes/maintain/upgrade-your-luxgo-node). As a reminder, it is best practice to [have a backup](https://docs.lux.network/nodes/maintain/node-backup-and-restore) of your staking key/certificate.

### Do I have to upgrade my node?

If you don't upgrade your validator to v1.10.0 before the Lux Mainnet activation date (which will be shared in coming days), your node will be marked as offline and other nodes will report your node as having lower uptime, which may jeopardize your staking rewards.

### Is there any change in hardware requirements?

No.

### Will updating decrease my validator's uptime?

No. As a reminder, you can check your validator's estimated uptime using the [info.uptime API call](https://build.lux.network/docs/api-reference/info-api).

<img src="https://images.ctfassets.net/voq4a5ue459o/3d4db985173559c8152c66d947eaa8c6/a55abcafa1a6a4fc0d82719ce5185ea9/6426100118a8ff0a95f40712_1_2zL1ZrQY8vKffH9fVcy4Ig.png?w=1600&q=80&fm=webp" alt="API Call Screenshot" />

### I think something is wrong. What should I do?

First, **make sure that you've read the** [documentation](https://docs.lux.network/) **thoroughly and checked the** [FAQs](https://support.lux.network/en/)**. If you don't see an answer to your question, go to our** [Discord](https://chat.avalabs.org/) **server and search for your question. If it has not already been asked, please post it in the appropriate channel.**


# DeletegateCall Incident Overview (/blog/delegatecall-incident)

---
title: DeletegateCall Incident Overview
description: A detailed post-mortem on Lux's Granite v1.14.0 which permanently resolves a critical precompile delegatecall vulnerability.
date: 2025-11-24
authors: [LuxDevelopers]
topics: [Granite Upgrade, Security]
comments: true
---

# Post-Mortem: The Precompile `delegatecall` Incident and Granite Resolution

On November 19, 2025, the Lux Granite network upgrade (LuxGo `v1.14.0`) successfully activated on Mainnet. This upgrade implemented significant improvements, but it also served as the final, permanent resolution for a critical security vulnerability discovered and mitigated earlier this year.

A critical flaw was identified in the handling of `delegatecall` and `callcode` by stateful precompiles, allowing a malicious contract to impersonate another caller and potentially forge cross-chain or privileged actions. The vulnerability was never exploited on Mainnet or any public L1.

Security is a continuous process, not a final destination. This process relies on proactive auditing, rigorous engineering, and transparent communication with our developer community. In accordance with this commitment, this post-mortem provides a detailed technical breakdown of the “Precompile DelegateCall Incident”, from its discovery and multi-phase mitigation to its permanent, architectural resolution within the Granite upgrade.

### Key Takeaways

1. A P1-critical vulnerability was discovered by our audit partners, Trail of Bits, during a routine audit.
2. A rapid, multi-phase incident response successfully neutralized the threat and contained the bug.
3. The vulnerability was never exploited on Mainnet or any public L1.
4. As of the Granite upgrade on November 19, 2025, the vulnerability is permanently and architecturally resolved.

This report details the technical nature of the bug, the chronology of the incident response, and the architectural lessons that have already made the Lux platform more resilient.

## Executive Summary: Incident and Resolution

During an audit of the `libevm` and `subnet-evm` codebases, security researchers at Trail of Bits flagged a potential issue on July 29, 2025. The issue, which was escalated to a P1-Critical incident, stemmed from an incorrect implementation of `delegatecall` and `callcode` semantics in stateful precompiles.

**The Vulnerability:** The bug was introduced in LuxGo `v1.13.1`. It allowed a malicious smart contract to "impersonate" its caller when making a `delegatecall` to a stateful precompile. This flaw made it such that any account that called a malicious contract was susceptible to having calls to stateful precompiles forged from them within the contract call.

## The Vulnerability

### The Discovery

On July 29, 2025, Trail of Bits asked a routine-seeming question about how stateful precompiles handle `delegatecall`. This question prompted an internal investigation. By the next morning, a local test confirmed the vulnerability: the behavior was incorrect, and a P1 incident was declared.

**The Root Cause: Divergent assumptions about `DELEGATECALL` semantics in stateful precompiles.**  
The vulnerability was traced back to its origin: the introduction of `libevm` in LuxGo `v1.13.1`.

While the introduction of `libevm` surfaced the issue, the true root cause was a long-standing, undocumented assumption in stateful precompiles: they allowed `DELEGATECALL` but assumed its EVM semantics would not be honored. The new `libevm` implementation correctly implemented `DELEGATECALL` semantics, and this mismatch between expected behavior (precompiles assuming delegated semantics were ignored) and actual behavior (`libevm` enforcing them) created the impersonation vulnerability.

Here is what went wrong:
1. The precompile correctly identified the `msg.sender` as the original EOA that called the "Caller" contract.
2. However, the precompile incorrectly assumed that `DELEGATECALL` semantics would not be honored by where they are invoked from. Specifically, they incorrectly assumed that the “self” account would always be the hardcoded precompile address. By treating the raw caller as authoritative, the precompile effectively shifted the call frame by one level and ended up executing on behalf of the EVM-semantic caller, enabling impersonation.

This combination was problematic. The precompile was executing with the permissions of the original caller but writing to the wrong location. This failure to "disambiguate between the EVM semantic caller/self and the raw caller/self" was the root cause of the impersonation risk.

### Potential Impact (P1-Critical)

This flaw created two critical, high-severity exploit vectors.

1. Impersonation & Teleporter (ICM) Forgery:  
   The most significant risk was to the LUExchange-Chain and any L1 using Teleporter. Because the `TeleporterMessenger` contract delivers cross-chain messages by calling arbitrary receiver contracts via `receiveTeleporterMessage`, a malicious receiver contract could abuse the bug by making a `delegatecall` to the `sendWarpMessage` precompile function. In this scenario, the precompile would incorrectly treat the `TeleporterMessenger` contract as the caller, allowing the malicious receiver to forge arbitrary Teleporter messages originating from any address on that chain.

2. Admin Phishing:  
   For L1s using stateful precompiles with an allow-list (e.g., a `FeeManagerPrecompile` that only allows an admin to change fees), a similar phishing attack was possible. An attacker could trick an admin EOA into calling their malicious contract. This contract would then `delegatecall` the `FeeManagerPrecompile`. The precompile would incorrectly see the `msg.sender` as the admin EOA and grant it permission to execute admin-only functions.

### Mitigating Factors

Two key factors significantly limited the real-world blast radius of this vulnerability.

First, exploiting the bug required the ability to deploy a malicious smart contract. While this was a meaningful risk on the LUExchange-Chain, many L1s operate with a contract deployer allow-list, which provided an additional layer of protection: an attacker would have needed both knowledge of the vulnerability and access to the deployer list to attempt an exploit.

Second, although the network had not yet upgraded enough stake to outright prevent an exploit from being finalized, the fact that many validators were still running v1.13.0 provided early and clear detection. Any transaction attempting to exploit the bug would have produced divergent execution between v1.13.0 and v1.13.1–v1.13.3 nodes, triggering an observable consensus disagreement. We continuously monitor for such divergences, and no anomalies, forks, or unexpected Teleporter activity were ever observed, giving us strong evidence that no exploit was attempted.

## Incident Response

The response to this P1 incident was not a single patch. It was a mature, three-phase, methodical process designed to maximize safety and network stability.

### Phase 1: Immediate Neutralization (Stop-Gap)

Once the team identified the vulnerability was introduced in `v1.13.1`, the immediate action was clear.

- **Action**: Begin an immediate rollback of Foundation mainnet validator nodes to **LuxGo** `v1.13.0`, the last known-good version.
- **Execution**: This rollback began at 5:57 PM EDT on July 30.
- **Result**: By 7:01 PM EDT (less than 9 hours after the vulnerability was confirmed) sufficient mainnet stake had been rolled back to `v1.13.0` to ensure that any transaction attempting to exploit the bug could not be accepted into a finalized block. This immediately neutralized the exploit vector. The risk of fund theft or message forgery was eliminated. This action downgraded the P1 vulnerability to a lower-grade Network DOS risk (as nodes on different versions might disagree on blocks), allowing the engineering team time to develop a more stable fix.

### Phase 2: Interim Containment (Soft Fork)

While the rollback was in progress, a parallel team was already developing a more robust, interim solution.

- **Action**: Soft fork logic was developed. This was not a full protocol change but a surgical patch: it specifically disallowed the acceptance any transactions that contained `delegatecall` or `callcode` calls  to stateful precompiles.
- **Execution**: This logic was included in **LuxGo** `v1.13.4` and **subnet-evm** `v0.7.8`. The patch was deployed to all Foundation nodes by 11:30 PM EDT on July 30. After thorough testing, it was published for all node operators on August 1.
- **Result**: This was a superior fix to the rollback. It allowed the entire network to re-converge on a single, safe version, eliminating the DOS risk. The vulnerability was now fully contained at the mempool level; any attempt to exploit it would simply be rejected by nodes.

### Phase 3: Permanent Resolution (The Granite Upgrade)

The soft fork was a highly effective containment, however, as Lux Network Founder and CEO Emin Gün Sirer [knew in 2016](https://web.archive.org/web/20230919110047/https://hackingdistributed.com/2016/06/28/ethereum-soft-fork-dos-vector/), soft forks allow for mempool DOS vulnerabilities and are not desired long-term fixes.

Instead, the team made the deliberate decision to use the stable soft-forked version to contain the bug, allowing the permanent fix to be developed, thoroughly tested, and bundled into the next scheduled major network upgrade: **Granite** `v1.14.0`. This is a much safer, more stable, and more transparent upgrade path.

- **Action**: The architecturally correct fix was developed.
- **Execution**: The Granite upgrade, which activated on Mainnet on November 19, 2025, contains two permanent fixes:
  1. Existing stateful precompiles are updated to explicitly `revert` if they are ever called via `delegatecall` or `callcode`.
  2. The underlying `libevm` library was patched to properly disambiguate "EVM semantic" and "raw" caller contexts, preventing this class of bug from recurring in future precompiles.
- **Result**: The issue is now permanently resolved at the protocol level. The interim soft fork logic from `v1.13.4` is now superseded by this protocol-level fix and can be safely removed in a future release.

## Detailed Incident and Resolution Timeline

| Date (2025) | Time (EDT)  | Event                                                                                     | Status                  |
|-------------|-------------|-------------------------------------------------------------------------------------------|-------------------------|
| July 29     | 11:02 AM    | Trail of Bits audit team asks a question on `delegatecall` mechanism.                     | Not Started             |
| July 30     | 8:34 AM     | Question is acknowledged, Lux Network runs local tests of precompile behavior.               | Investigating           |
| July 30     | 10:29 AM    | Vulnerability confirmed via local test: `delegatecall` semantics are not honored.         | Confirmed               |
| July 30     | 10:45 AM    | P1-Critical Incident Declared.                                                            | Triage                  |
| July 30     | 11:40 AM    | **Phase 2 (Interim Fix)** development begins: Soft fork logic to block vulnerable calls.      | Mitigation in Progress  |
| July 30     | 2:30 PM     | **Root Cause Identified**: Bug introduced in `v1.13.1` with `libevm`. Rollback viable.        | Planning Updated        |
| July 30     | 5:57 PM     | **Phase 1 (Immediate Fix)** begins: Foundation validators start rollback to `v1.13.0`.        | Mitigation in Progress  |
| July 30     | 7:01 PM     | **Phase 1 Complete**: Sufficient stake rolled back. Exploit vector neutralized.               | Mitigated               |
| July 30     | ~11:30 PM   | **Phase 2 Complete (Internal)**: Private soft fork logic deployed to Foundation nodes.        | Contained               |
| July 31     | All Day     | **Phase 3 (Permanent Fix)** design begins. Public `v1.13.4` development.                      | Resolution in Progress  |
| Aug 1       | 7:56 PM     | **Phase 2 Complete (Public)**: LuxGo `v1.13.4` published for all node operators.        | Contained               |
| Aug 4-8     | N/A         | Consensus on permanent fix: Precompiles will `revert` on `delegatecall` in Granite.       | Resolution in Progress  |
| Nov 19      | 11:00 AM    | **Phase 3 Complete (Permanent)**: Granite Upgrade (`v1.14.0`) activates on Mainnet.           | **Resolved**                |

## Lessons Learned and Future Architectural Commitments

This incident provided valuable lessons that have already been converted into actionable, completed, and ongoing improvements to our security posture. Key takeaways from the internal root cause analysis include:

### 1. Conform globally, diverge locally

**What we learned:**

Stateful precompiles had implicitly diverged from standard EVM `DELEGATECALL` semantics without making that divergence explicit to integrators or future maintainers. This created hidden complexity across multiple codebases and ultimately surfaced as a critical vulnerability.

**What we changed:**

The Granite upgrade explicitly encodes the allowed call types for every stateful precompile. If a precompile does not intentionally support delegated calls, it now *reverts* when invoked via `delegatecall` or `callcode`. This enforces clear boundaries between standard EVM behavior and Lux-specific extensions.

### 2. Standards must be the default (unless explicitly marked otherwise)

**What we learned:**

Engineers reasonably assume that any component behaves according to standard EVM rules unless explicitly signaled otherwise. When Lux's extensions silently diverged from the standard, those assumptions became dangerous. In the absence of strong signals, developers will default to the ecosystem standard, and we must support that.

**What we changed:**

`libevm` now provides explicit types for **EVMSemantic** vs. **Raw** caller/self contexts. Precompile authors must consciously choose the correct semantics, eliminating ambiguity. This is a concrete application of the recommendation to clearly denote any divergence from ecosystem norms.

### 3. Automated tests must lock in critical (especially non-standard) assumptions

**What we learned:**

The original precompiles assumed `DELEGATECALL` would not be honored, but this was never encoded in tests. When `libevm` refactoring improved semantic correctness, the mismatch between expected and actual behavior was not caught. Non-standard assumptions must be enforced through tests, not tribal knowledge.

**What we changed:**

We are adding regression and end-to-end tests specifically covering call-context behavior for all stateful precompiles. Any future change in EVM call semantics, or in precompile behavior, will surface immediately during automated testing.

## A More Resilient Platform

The `delegatecall` vulnerability was a significant challenge, but the response demonstrates the resilience and maturity of the platform's security and engineering processes. The issue was discovered through our proactive audit program, handled with a methodical, multi-phase mitigation plan that protected all users, and has now been permanently resolved by the Granite network upgrade.

The Lux network, including the LUExchange-Chain and all L1s, is safe. We can state with high confidence that the vulnerability was never exploited. Any successful attempt would have triggered an immediate, observable consensus divergence between node versions, something we continuously monitor. No such divergence or anomalous Teleporter activity was ever detected, confirming the network was never attacked through this vector.

For more details on the Granite upgrade, see the [Granite release notes](https://github.com/luxfi/luxgo/releases/tag/v1.14.0).

---

## About Lux

Lux is a high-performance blockchain platform designed for builders who need to scale. Engineered with a revolutionary three-part Layer 1 (L1) architecture, Lux is anchored by its Lux Consensus Mechanism, ensuring near-instant finality for transactions. The platform also features an open-source Layer 0 (L0) framework, enabling the seamless creation of interoperable Layer 1 blockchains with high throughput on both public and private networks. 

Supported by a global community of developers and validators, Lux offers a fast, low-cost environment for building the next generation of decentralized applications (dApps). With its unique blend of speed, flexibility, and scalability, Lux is the preferred choice for innovators pushing the boundaries of blockchain technology.

---

**Follow [@LuxDevelopers](https://x.com/LuxDevelopers) for updates and join our developer community to stay informed about future upgrades and tooling improvements.**


# Deploy a DApp on the LUExchange-Chain with Foundry (/blog/deploy-a-dapp-on-c-chain-with-foundry)

---
title: Deploy a DApp on the LUExchange-Chain with Foundry
description: This guide shows how to deploy and interact with smart contracts using foundry on a local Lux Network and the Testnet LUExchange-Chain.
date: 2024-05-26
authors: [ashngmi, martin_eckardt]
topics: [solidity, foundry, Lux Starter Kit]
---

Foundry toolchain is a smart contract development toolchain written in Rust. It manages your dependencies, compiles your project, runs tests, deploys, and lets you interact with the chain from the command-line.

# Recommended Knowledge

- Basic understanding of Solidity and Lux.
- You are familiar with Lux Smart Contract Quickstart.
- Basic understanding of the Lux's architecture

# Run Lux Starter Kit

import SetUp from "@/content/common/lux-starter-kit/set-up.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<SetUp components={defaultMdxComponents}/>

# Create a Smart Contract

Create a new Solidity file in the `src` directory of your project. For example, `src/MyContract.sol`.

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

contract MyContract {
    uint256 public myNumber;

    function setNumber(uint256 _num) public {
        myNumber = _num;
    }
}
```

# Create Deployment Address

You can create a new wallet with the case command:

```bash
cast wallet new
```

# Fund Your Account

**Option 1 (Recommended):** Create a [Lux Build account](https://build.lux.network/login) and connect your wallet to receive testnet LUX automatically.

**Option 2:** Use the [Lux Testnet Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code `lux-academy25`

# Deploy the Smart Contract

With foundry's `forge` command, you can deploy your smart contract to the Testnet LUExchange-Chain.

```shell
forge create --rpc-url testnet-c --private-key <private-key> src/MyContract.sol:MyContract
```



# Durango: Lux Warp Messaging Comes to the EVM (/blog/durango-avalanche-warp-messaging)

---
title: "Durango: Lux Warp Messaging Comes to the EVM"
description: Native cross-chain communication comes to every EVM Chain in the Lux Ecosystem.
date: 2024-02-01
authors: [LuxDevelopers]
topics: [Network Updates, Durango Upgrade, Lux Warp Messaging, EVM, Interoperability, Platform-Chain]
comments: true
---

The publishing of the pre-release code for a proposed upgrade to the Lux Network, codenamed Durango

---

**Update (2/21/24):** The production code [LuxGo@v1.11.0](https://github.com/luxfi/luxgo/releases/tag/v1.11.0) for the proposed Durango Upgrade was published. If sufficient stake supports Durango, it will activate on the Lux Mainnet at **11 AM ET on Wednesday, March 6th, 2024**. Durango contains LPs that are not compatible with < v1.11.0 (Cortina). If Durango activates and you do not upgrade your node **before** the activation time, your node will be unable to process new blocks and will be marked as offline by other nodes (impacting your node's uptime and potentially jeopardizing your staking rewards). You can track support for LP-23, LP-24, LP-25, LP-30, LP-31, LP-41, and LP-62 (included in Durango) on snowpeer: [https://snowpeer.io/acps](https://snowpeer.io/acps)

**Update (2/13/24):** Durango activated successfully on the Testnet Testnet this morning at 11 AM ET!

---

The [pre-release code](https://github.com/luxfi/luxgo/releases/tag/v1.11.0-testnet) for a proposed upgrade to the Lux Network was published for activation on the Testnet Testnet at 11 A.M. ET (4 P.M. UTC) on Tuesday, February 13th, 2024. This proposed upgrade, codenamed Durango, consists of Lux Community Proposals (LPs) [\[LP-23\] Platform-Chain Native Transfers](/docs/lps/23-p-chain-native-transfers), [\[LP-24\] Activate Shanghai EIPs on LUExchange-Chain](/docs/lps/24-shanghai-eips), [\[LP-25\] Virtual Machine Application Errors](/docs/lps/25-vm-application-errors), [\[LP-30\] Integrate Lux Warp Messaging into the EVM](/docs/lps/30-lux-warp-x-evm), [\[LP-31\] Enable Subnet Ownership Transfer](/docs/lps/31-enable-subnet-ownership-transfer), [\[LP-41\] Remove Pending Stakers](/docs/lps/41-remove-pending-stakers), and [\[LP-62\] Disable AddValidatorTx and AddDelegatorTx](/docs/lps/62-disable-addvalidatortx-and-adddelegatortx).

**Note, this pre-release code will ONLY work on Testnet. If you run the code on Mainnet, it will exit on startup.** The Durango Upgrade includes protocol optimizations that are not compatible with LuxGo versions < v1.11.0. If you run a node on Testnet, you must upgrade your software to LuxGo >= v1.11.0 **before** the activation time on Testnet. **If you are a Mainnet node operator, no action is required.**

Pending a successful activation on the Testnet Testnet of all [implementable](/docs/acps#acp-statuses) LPs, Lux Validators can choose to update their nodes to a production release of Durango (yet to be published) that supports the LPs on Lux Mainnet. **Reminder: Lux Validators can** [signal](https://x.com/_patrickogrady/status/1748074273275822364?s=20) **their support for LPs.**

## Cross-Subnet Interoperability

The first native Cross-Subnet message was sent on Lux Mainnet using Lux Warp Messaging (AWM) [on December 22nd, 2022](https://x.com/_patrickogrady/status/1605989086451597313?s=20). Following this milestone, [LP-30](/docs/lps/30-lux-warp-x-evm) proposed activating AWM on the LUExchange-Chain and Subnet-EVM. Activating this LP brings native cross-chain communication to every EVM Chain in the Lux Ecosystem and establishes a standard for future VMs to communicate using AWM.

With AWM, there are no third party intermediaries or trust assumptions outside of the validator set of the Primary Network and the communicating Subnets. With only the validators of a Subnet, every Lux Subnet can send messages to one another. AWM leverages the Lux Platform-Chain as a registry of all Subnets' validator sets including a BLS Public Key for each validator.

To send a message, an [untrusted relayer](https://github.com/luxfi/awm-relayer) or [user](https://github.com/luxfi/hypersdk/blob/4bd6d720a5bc8ab9c6361e05f3c00d9c4780720d/examples/tokenvm/tests/e2e/e2e_test.go#L710-L748) aggregates signatures from a threshold of the Subnets' participating stake. Once it has received signatures from a threshold of stake, it constructs a [BLS Multi-Signature](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html) and a bit set to specify which validators have included a signature. For a receiving Subnet to verify the message, it looks up the validator set of the source Subnet at the current Platform-Chain height from its local database, checks that the total weight of included validators meets the required threshold, aggregates the specified BLS public keys, and then verifies the signature against the resulting aggregate public key. Any relayers broadcasting invalid BLS Multi-Signatures will be ignored.

**Note, no transactions/messages are included in the Platform-Chain to send an Lux Warp Message. Messages are passed directly between communicating Subnets or between a Subnet and the LUExchange-Chain.**

<img src="https://images.ctfassets.net/voq4a5ue459o/4f048dc2a414c1a60bb67c7b299581b3/fe273d73529d1bbff8a3390e37f4eb7c/65bc12b118fad82932fc4693_KLrCXnfqjgHu9ltWr39vbTzOEfiYVFWu4O6GUGiVXll3XMCnAFVROeKf2q625pV0h0YSo7G2UywgsS9cocU3V6gRsoIOrdxoIC3.png?w=1600&q=80&fm=webp" alt="AWM Architecture Diagram" />

This lightweight protocol replaces the management of point-to-point connections with the simplicity of one unified registry: the Lux Platform-Chain. For the full details on how this is integrated into the EVM, see [LP-30](/docs/lps/30-lux-warp-x-evm).

In order to use AWM, a threshold stake of the Subnet's validators need to register BLS keys via 'AddPermissionlessValidatorTx'. [LP-62](/docs/lps/62-disable-addvalidatortx-and-adddelegatortx) proposes disabling 'AddValidatorTx' and 'AddDelegatorTx' to push all new stakers to use 'AddPermissionlessValidatorTx' and 'AddPermissionlessDelegatorTx'. Wide adoption of registered BLS keys not only enables Subnets to utilize AWM, but also accelerates the timeline for potential future Platform-Chain upgrades.

## Improving the Developer Experience

This upgrade also addresses some common requests from developers to improve the developer experience. These include adding Platform-Chain native transfers, enabling subnet ownership transfers, maintaining smart contract compatibility with Ethereum by supporting the Ethereum Shanghai Upgrade, and adding VM application errors.

Currently, users who want to transfer assets between Platform-Chain addresses either need to leave the Platform-Chain or use a transaction type not meant for native transfers. [LP-23](/docs/lps/23-p-chain-native-transfers) proposes supporting native transfers on the Platform-Chain with 'BaseTx'. By supporting native transfers on the Platform-Chain, users can manage their assets more efficiently and securely.

Another challenge for developers has been changing the owner of a Subnet, as currently the owner is immutable when new Subnets are created on the P-chain. Subnet operators may want to transition ownership of the Subnet to a new owner for a number of reasons, i.e. to perform a periodic rotation of the Subnet's control key(s). [LP-31](/docs/lps/31-enable-subnet-ownership-transfer) proposes allowing the current owner of a Subnet to transfer ownership to a new owner via 'TransferSubnetOwnershipTx'.

Durango also activates [LP-24](/docs/lps/24-shanghai-eips), which incorporates the changes from the Ethereum Shanghai Upgrade to ensure the LUExchange-Chain maintains smart contract compatibility with Ethereum. Specifically, EIP-3855 adds the PUSH0 opcode to the LUExchange-Chain, maintaining compatibility with Solidity versions >= v0.8.20. See the [LP](/docs/lps/24-shanghai-eips) for full details on the changes.

At the VM level, a peer cannot signal VM application errors, resulting in a network timeout and failed request. [LP-25](/docs/lps/25-vm-application-errors) proposes adding an 'AppError' message to indicate that an error has occurred. This allows a peer to signal failure early rather than wait for a timeout to fire, reducing the latency of a failed request from the network timeout (~2s) to a single network round trip time (~500ms).

## Starting the Path to 100k Subnets

To help further increase the scalability of the Platform-Chain, [LP-41](/docs/lps/41-remove-pending-stakers) proposes removing a user-specified 'StartTime' for stakers. This modifies the Platform-Chain to start a staker's staking period when the transaction is accepted. This greatly reduces the computation load on the Platform-Chain, increasing the efficiency of all Lux Network Validators and sets the stage for future Platform-Chain upgrades, including continuous staking (stake once and forget about it).

In addition to scaling the P-chain, key features will be needed in order to walk the "[Path to 100k Subnets](https://hackmd.io/@patrickogrady/100k-subnets)". Many of these will rely on BLS keys, whose wide adoption not only enables Subnets to fully utilize Lux Warp Messaging and to send cross-Subnet messages, but also accelerates the timeline for future Platform-Chain upgrades. These include, but are not limited to:

**Arbitrary Subnet Rewards:** The Platform-Chain currently restricts Elastic Subnets to follow the reward curve defined in a 'TransformSubnetTx'. With sufficient BLS key adoption, Elastic Subnets can define their own reward curve and reward conditions. The Platform-Chain can be modified to take in a message indicating if a Subnet validator should be rewarded with how many tokens signed with a BLS Multi-Signature.

**Subnet Attestations:** The Primary Network or a Subnet can attest to the state of their Subnet with a BLS Multi-Signature. This can enable clients to fetch the current state of the Subnet without syncing the entire Subnet. StateSync enables clients to download chain state from peers up to a recent block near tip. However, it is up to the client to query these peers and resolve any potential conflicts in the responses. With Subnet Attestations, clients can query an API node to prove information about a Subnet without querying the Subnet's validators. This can especially be useful for Subnet-Only Validators to prove information about the LUExchange-Chain.

As mentioned earlier, [LP-62](/docs/lps/62-disable-addvalidatortx-and-adddelegatortx) proposes the shift to the new BLS key tx type, 'AddPermissionlessValidatorTx', accelerating towards the future of BLS-powered advancements in the Lux Network.


# What to Expect After the Etna Upgrade (/blog/etna-changes)

---
title: What to Expect After the Etna Upgrade
description: This guide outlines the operational impact on existing network participants expected from the activation of the LuxGo "Etna" upgrade.
date: 2024-08-23
authors: [meagfitzgerald]
topics: [Lux Network Upgrade, Etna Upgrade, Validators, Layer 1, L1]
comments: true
---

This guide outlines the operational impact on existing network participants expected from the activation of the LuxGo "Etna" upgrade.

## Vocabulary, New and Old

- **L1**: An Lux Layer 1 Network. An L1 is a sovereign network that has its own dynamic set of validators, rules for network participation, and defines its own validator rewards incentives.
- **L1-validator**: A validator that only validates an Lux layer 1 blockchain. These validators are not required to stake 2000 LUX, or validate the Lux Primary Network. They instead pay a continuous fee in order to participate in L1 validation.
- **LP-77**: The Lux Community Proposal that outlines a new framework for creating low-cost, independent blockchains that can _easily_ interoperate with each other. You can read the full proposal [here](/docs/lps/77-reinventing-subnets).
- **The Primary Network**: The Lux X,P, and LUExchange-Chains, a.k.a. the 3 primary blockchains that most validators currently sync on Lux Mainnet.

## What is Changing?

### Subnets Are Now Called L1s

Lux Subnets are being rebranded as Lux L1s. Unlike layer 2 blockchains, layer 1 blockchains operate independently without relying on other systems for their core functions.
They manage their own consensus mechanisms, transaction processing, and security protocols directly within their own networks.

Subnets have always operated this way, scaling Lux's network _horizontally_ instead of compounding dependencies by requiring chains to roll down to other networks.

### For Validators

L1 validators will no longer be required to sync the Primary Network’s X or LUExchange-Chain, drastically reducing the cost of operating a validator.

L1 validators will no longer be required to stake 2000 LUX. Instead they will pay a substantially cheaper continuous fee calculated based on the number of L1 validators. The LUX-denominated fee is a nominal amount per second and provides significant cost-savings for L1 validators.

### For New L1s

The ownership of validator set management will be moved from the Platform-Chain to individual L1 _ValidatorManager_ smart contracts.

- Essentially, validators will be managed by the L1s themselves instead of the Platform-Chain.

Sovereign L1s can easily be launched on Lux with a dynamic set of validators whose staking logic is defined and enforced by a _ValidatorManager_ smart contract deployed by the L1 creator. The smart contract deployed can enforce any network rules the creator desires, including but not limited to:

- A permissionless proof-of-stake blockchain where network participation is not controlled by any centralized authority
- A permissioned proof-of-authority blockchain where the validator set is controlled by a consortium or centralized authority

If the L1 is permissionless, the validator earns staking rewards by staking the asset specified by the L1; If the L1 is permissioned, the validator is controlled by a party specified by the L1 Owner and does not earn any rewards.

### For Existing L1s

Existing Lux Subnets _that wish_ to remove the 2000 LUX per validator requirement will need to convert their Subnet’s control from a _Platform-Chain Owner Key_ to a _ValidatorManager_ smart contract via the workflow outlined in LP-77.

- A detailed guide on how to convert existing L1s will be released prior to Testnet activation.

Existing L1s do not need to be converted if their validators continue to stake 2000 LUX and validate the Primary Network.

## What is Staying the Same?

### For Validators

If you want to earn staking rewards for validating the Lux Primary Network, you will still need to stake 2000 LUX per validator.

Existing validators can continue operating as they have before, and do not require any action. Updating to the latest release of LuxGo will not affect their operation.

### For L1s

Existing Lux L1s are not required to convert their pre-Etna validators to L1-only-validators; they will continue to operate as before.

All L1s will still be able to interoperate using Lux Warp Messaging (Lux ICM) and Teleporter (Lux ICM Contracts), regardless of how or when they were created.

## What Technical Changes Will be Included?

While driven by LP-77, this upgrade will include many other feature additions outlined thoroughly in the following Lux Community Protocols:

**[LP-77](/docs/lps/77-reinventing-subnets)**: Outlines a new validator management framework for Lux L1s, creating low-cost, natively-interoperable blockchains.

**[LP-103](/docs/lps/103-dynamic-fees)**: Introduces a dynamic fee mechanism to the Exchange-Chain and the Platform-Chain, previewing a future transition to a multidimensional fee mechanism.

**[LP-118](/docs/lps/118-warp-signature-request)**: Proposes a standard `AppRequest` payload format type, simplifying potential AWM signature aggregation implementations.

**[LP-125](/docs/lps/125-basefee-reduction)**: Reduces the minimum base fee on the Lux LUExchange-Chain from 25 nLUX to 1 nLUX.

**[LP-131](/docs/lps/131-cancun-eips)**: Brings the EVM opcodes introduced by the Cancun Upgrade to the Lux LUExchange-Chain and Subnet-EVM.


# Etna: Enhancing the Sovereignty of Lux L1 Networks (/blog/etna-enhancing-sovereignty-avalanche-l1s)

---
title: "Etna: Enhancing the Sovereignty of Lux L1 Networks"
description: The Etna upgrade introduces sovereign L1 networks with 99.9% reduced costs, dynamic Platform-Chain fees, reduced LUExchange-Chain base fees, and standardized Interchain Messaging. Activated December 16, 2024.
date: 2024-12-02
authors: [LuxDevelopers]
topics: [Network Updates, Etna Upgrade, Lux L1, LP-77, Dynamic Fees, ICM, Sovereignty]
comments: true
---

<img src="https://www.lux.network/_astro/674e25e0ec7450feaab90afb_Etna_Announce_ZomV8V.webp" alt="Etna: Enhancing the Sovereignty of Lux L1 Networks" />

The publishing of the release code for an upcoming network upgrade to the Lux Network, codenamed Etna.

---

## Intro

A release for the latest upgrade to the Lux Network, dubbed the "Etna" upgrade, was published for activation on Lux Mainnet scheduled for 12 PM ET (5 PM UTC), December 16, 2024. This proposed upgrade consists of Lux Community Proposals (LPs) [\[LP-77\]](/docs/lps/77-reinventing-subnets) Reinventing Subnets, [\[LP-103\]](/docs/lps/103-dynamic-fees) Add Dynamic Fees to the Platform-Chain, [\[LP-118\]](/docs/lps/118-warp-signature-request) Warp Signature Interface Standard, [\[LP-125\]](/docs/lps/125-basefee-reduction) Reduce LUExchange-Chain minimum base fee from 25 nLUX to 1 nLUX, [\[LP-131\]](/docs/lps/131-cancun-eips) Activate Cancun EIPs on LUExchange-Chain and Subnet-EVM chains, and [\[LP-151\]](/docs/lps/151-use-current-block-pchain-height-as-context) Use current block Platform-Chain height as context for state verification. The prereleased code version was successfully activated on the Testnet Test Network at 11 AM ET (4 PM UTC), November 25, 2024.

The Etna Upgrade release includes protocol optimizations that are **not** compatible with LuxGo versions \<[v1.12.0](https://github.com/luxfi/luxgo/releases/tag/v1.12.0). If you run a node on Mainnet, you must upgrade your software to LuxGo >=v1.12.0 before the scheduled activation time. **If you are a Mainnet node operator, upgrading to v1.12.0 is mandatory.** The plugin version is unchanged at 38, and is compatible with [v1.11.13](https://github.com/luxfi/luxgo/releases/tag/v1.11.13).

## LUExchange-Chain Fees Reduced

This upgrade activates [LP-125](/docs/lps/125-basefee-reduction), which reduces the LUExchange-Chain transaction minBaseFee from 25 nLUX to 1 nLUX, a reduction of nearly 96%. This change has big implications for users, as it affects the lower bound of transaction fees under the EIP-1559 fee mechanism. This update simply lowers the floor for transaction fee pricing, making Lux transactions significantly cheaper during periods of low activity.

For context, the minBaseFee sets the minimum possible value for the base fee of all transactions on the LUExchange-Chain, as defined by EIP-1559. The base fee is a dynamic component of transaction fees that is adjusted based on the demand for block space. When the network is less congested, the base fee will decrease, approaching the minBaseFee, making transactions less expensive. At high demand, fees will increase proportionally with the load on the network, so the fees may be higher.

## Dynamic Fees Introduced On The Platform-Chain

A similar dynamic fee mechanism has also been introduced to the Platform-Chain in this upgrade, implemented according to the specification proposed by [LP-103](/docs/lps/103-dynamic-fees). With the previous fixed fee mechanism, Platform-Chain users were provided with simplicity and predictability, but network congestion and resource constraints weren't properly accounted for. Adding this dynamic fee mechanism has made it possible to significantly lower the transaction fees on the Platform-Chain, as it no longer relies on hard-coded, artificially high fees as the main DoS prevention mechanism. Furthermore, adding a fee mechanism that can more robustly handle spikes in load was necessary to prepare for the possibility of increased Platform-Chain usage following the new functionality added in [LP-77](/docs/lps/77-reinventing-subnets), which introduces five new Platform-Chain transaction types that perform Layer 1 (L1) validator management.

## A Network Of Sovereign Networks

[LP-77](/docs/lps/77-reinventing-subnets) introduces a mechanism for creating and operating a sovereign Layer 1 blockchain, aimed at addressing the biggest concerns around the existing Subnet architecture.

Etna introduces the ability to create sovereign Lux L1s, with lightweight, cost-efficient validation. Instead of staking 2000 LUX, L1 validators will pay a dynamic continuous fee for L1 validation as defined by the LP-77 specification, which should initially be approximately 1.3 LUX per month. Unlike Subnet validation, L1 validators are not required to sync and validate the Primary Network. For an explanation on the distinction between Subnet and L1 validators, see [LP-77](/docs/lps/77-reinventing-subnets) for a note on the nomenclature.

This upgrade also enables L1s to enforce custom validator management logic with smart contracts. Projects can choose from conventional proof-of-authority and proof-of-stake [validator management contracts](https://github.com/luxfi/icm-contracts/tree/main/contracts/validator-manager) made available by the Lux Platform engineers for the community to review or use as they see fit, or define their own staking logic with a custom smart contract, such as the contract proposed by community member Gauthier Leonard in [LP-99](/docs/lps/99-validatorsetmanager-contract). This unlocks a new level of network design for creators, enabling unlimited custom staking logic to be easily defined and enforced on L1 networks.

This new functionality significantly reduces the economic barrier to create and operate a blockchain (over 99.9% reduction in upfront costs), drastically reducing the required validator resources and defining a new industry standard for L1 network creation.

## Messages Ensured By An Entire Network

This upgrade includes [\[LP-118\]](/docs/lps/118-warp-signature-request) which proposes a VM-agnostic standard payload format for requesting signatures for Lux Interchain Messages. A valid ICM signature is produced by querying a blockchain's validator set, requesting a threshold majority sign a message confirming an event has or has not occurred on that chain, and then aggregating those signatures into a single BLS signature. Most of the new validator management transaction types introduced by LP-77 require valid ICM signatures signed by either the source chain or the Platform-Chain to secure validator addition and removal.

LP-118 standardizes the request and retrieval of Warp signatures, defining it as part of the LuxGo client such that VMs do not need to independently implement this logic. This will simplify signature aggregator implementations by allowing them to depend only on LuxGo for message construction, rather than individual VM codecs.


# Motivation behind Lux9000 (/blog/etna-upgrade-motivation)

---
title: Motivation behind Lux9000 
description: Learn about the largest network upgrade of Lux, that will lower the barrier to launch a blockchain and enable permissionless validation of L1s.
date: 2024-08-15
authors: [martin_eckardt, owenwahlgren]
topics: [Lux]
---

import EtnaUpgradeMotivation from '@/content/common/multi-chain-architecture/etna-upgrade-motivation.mdx';

<EtnaUpgradeMotivation />


# Lux LUExchange-Chain Throughput Increases as Validators Signal Higher Gas Targets (/blog/gas-target-increase)

---
title: Lux LUExchange-Chain Throughput Increases as Validators Signal Higher Gas Targets
description: Lux validators increase the LUExchange-Chain's target gas consumption by 30% thanks to the Octane upgrade, paving the way for higher throughput and future scaling optimizations.
date: 2025-08-21
authors: [LuxDevelopers]
topics: [Validators, Gas Target, Octane Upgrade, SAE, Firewood]
comments: true
---

_Originally published by [@LuxDevelopers](https://x.com/LuxDevelopers/status/1958202141409247333)_


---

## Quick Take

- Positions Lux well to become one of the lowest latency, highest throughput EVM L1 experiences in the ecosystem.  
- Lux validators increased the LUExchange-Chain's target gas consumption by 30 % from 1.6 M to 2.1 M gas/sec.  
- The dynamic adjustments were enabled by the Octane upgrade, activated on April 6, 2025.  
- The Lux Foundation plans to continue signaling incremental increases as network metrics allow.  
- Future improvements like Streaming Asynchronous Execution (SAE) and Firewood Database integration aim to enable even larger increases.

Lux's LUExchange-Chain has seen its throughput capacity increase by over 30% following validator action to raise the target gas
consumption from 1.6 million to 2.1 million gas per second. The increase was made possible by the Octane upgrade that went live
on April 6th, 2025.

The gas target determines how much computational work the network can process per second, directly affecting how many transactions
and smart contract operations can be executed. For users of the chain, higher gas targets mean higher potential transactions per second,
and also lower transaction fees. For validators and node operations, higher gas targets can mean increased demands on hardware and network
infrastructure, which is closely monitored to ensure stability and reliability.
The dynamic adjustments were enabled by the Octane upgrade, activated on April 6, 2025.
Future improvements like Streaming Asynchronous Execution (SAE) and Firewood Database integration aim to enable even larger increases.

---

## Dynamic Gas Target Adjustment

[The Octane upgrade](https://www.lux.network/about/blog/octane-optimizing-c-chain-gas-fees) introduced the ability for Lux Primary Network validators to dynamically update the network's target utilization through
signaling their preferences. This mechanism allows the network to adjust capacity parameters without requiring hard forks or governance votes.

### How Validator Signaling Works

Under the new mechanism, validators can explicitly set their preferred gas target values. Validators that do not set a preference effectively abstain
from influencing the network's gas target by defaulting to whatever the current value is. The network calculates the effective gas target based on the
preferences of participating validators.

Since the upgrade's activation, validators run by the Lux Foundation have iteratively increased their gas target preferences, resulting in the
30% throughput increase observed across the network.



The Lux Foundation plans to continue gradually increasing their validator preferences while monitoring network performance metrics.
This approach aims to maximize LUExchange-Chain utilization within current infrastructure constraints. Upcoming optimizations like Streaming Asynchronous
Execution and the Firewood Database integration are expected to enable further increases.

Other validator operators can set their gas target preferences to participate in determining the network's effective throughput capacity.
This allows scaling decisions to reflect the technical assessment of the broader validator community.

---

### Network Health Monitoring

Several key performance indicators are closely monitored consistently through changes to the target gas consumption to ensure network stability:

- Block verification times - to ensure consensus remains stable

As the gas target increases, so does the maximum amount of gas able to be consumed in a given block. The more gas in a block, the longer time that
block will potentially take to execute. It's important that block execution times remain within an acceptable range to ensure that consensus is able
to proceed successfully.

Because blocks can have significantly different sizes depending on the time they are produced and gas capacity available at that instant, a holistic
way of viewing the amount of time spent in block execution is by looking at the percentage of time that a node uses to execute blocks during consensus.
We had earmarked less than or equal to 5% of time spent in block execution as a key performance indicator of consensus, and though a small initial
increase was observed, validator nodes were able to stay below that threshold.



- Disk usage and state growth rates - to monitor storage requirements

The higher the gas usage, the higher potential for state growth, and because all validators currently must maintain the full state of the chain on disk,
the more storage validators may need to have available to use.

Of course the larger the chain grows, the more disk space it will require to store it, but in increasing the gas target we wanted to ensure that the
rate of disk growth didn't become unsustainable, and in fact observed that disk usage continued to grow at a relatively constant rate of around 3 to 4
GB per day.



- Peer-to-peer network health - to monitor connectivity between all validator nodes

A key indicator of the health of the network as a whole is the percentage of successful queries made to peers. If any significant number of validator
nodes were to not be able to process the increased utilization level of the chain, they would not be able to respond to their peer's queries about block
proposals. Throughout the iterative increases to the gas target in June and July, we did not observe any noticeable decrease in the observed percentage
of successful queries, indicating that on the whole, the vast majority of nodes are still stable and able to keep up with the increased processing
demands created by the higher gas targets.



These metrics remained within acceptable parameters throughout the increase, indicating the network can handle the higher throughput without stability issues.

---

## Scaling Optimization Ahead

The 30% increase represents just the beginning of Lux's throughput expansion plans. Two major technical upgrades are in development that could
enable even more significant capacity improvements:

### Streaming Asynchronous Execution (SAE)  

As outlined in Lux Community Proposal LP-194, SAE introduces a fundamental architectural change by separating block execution from the consensus
process. This allows for a continuous execution thread that operates independently of consensus, enabling gas targets to align with average-case execution
times rather than being constrained by worst-case scenarios.

The separation means the network can maintain higher throughput targets without risking consensus delays during computationally intensive blocks.

### Firewood Database Integration 

The upcoming Firewood database integration is designed to significantly improve performance of blockchain database operations, and also reduce validator
node storage requirements through optimized data layout and state pruning. By maintaining only recent state data and improving storage efficiency, Firewood
will reduce the operational burden on validators, potentially enabling support for higher gas targets.

---

## Looking Ahead

A combination of upcoming performance improvement efforts as well as continued iteration to dynamically determine the maximum chain capacity possible
at any given point in time positions Lux well to become one of the lowest latency, highest throughput EVM L1 experiences in the ecosystem.

Head to the Lux Build to access everything you need to know about building on Lux: https://build.lux.network/

Follow us on X to keep up with all of the latest news, research and tooling for building on Lux: https://x.com/luxdevelopers/


# How to Upgrade LuxGo to Granite (/blog/granite-installer)

---
title: How to Upgrade LuxGo to Granite
description: This guide shows how to upgrade LuxGo to Granite v1.14.0, the latest network upgrade with major improvements.
date: 2025-10-21
authors: [owenwg]
topics: [Granite Upgrade, LuxGo, Upgrade]
comments: true
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

## Introduction

Lux Granite is the latest upgrade to the Lux network. It includes major improvements including Platform-Chain epoched views for ICM, secp256r1 support for biometric authentication, and dynamic minimum block times for faster transactions.

## Prerequisites

- An existing LuxGo node running any version prior to v1.14.0
- Basic command line knowledge
- Access to your node's terminal or SSH

## Backup Your Node First

Before upgrading your node, it's crucial to backup your staker files which identify your node on the network. These files are essential for recovering your node if anything goes wrong.

Run the following commands to backup your staker files:

```bash
cd
cp ~/.luxgo/staking/staker.crt .
cp ~/.luxgo/staking/staker.key .
```

Download these `staker.crt` and `staker.key` files and store them in a secure, private location. These files can be used to fully recreate your node if needed.

<Callout type="warning">
If you use your node for development purposes and have keystore users on your node, make sure to back those up as well.
</Callout>

## Primary Network Nodes

Choose one of the following methods to upgrade your Primary Network node to Granite:

### Method 1: Using the Installer Script (Recommended)

The easiest way to upgrade is using the LuxGo installer script.

<Steps>
<Step>

#### Get the Installer Script

If you don't already have the installer script, download it:

```bash
wget -nd -m https://raw.githubusercontent.com/luxfi/lux-docs/master/scripts/luxgo-installer.sh
chmod 755 luxgo-installer.sh
```

</Step>
<Step>

#### Run the Installer

Execute the installer script:

```bash
./luxgo-installer.sh
```

The script will automatically detect your existing installation and switch to upgrade mode:

```bash
LuxGo installer
---------------------
Preparing environment...
Found amd64 architecture...
Looking for amd64 version latest...
Node version found.
Attempting to download: 
   https://github.com/luxfi/luxgo/releases/download/v1.14.0/luxgo-linux-amd64-v1.14.0.tar.gz
```

</Step>
<Step>

#### Automatic Upgrade

The script will:
1. Stop your current node
2. Download and install LuxGo v1.14.0 (Granite)
3. Restart your node with the new version

You'll see output similar to:

```bash
Node upgraded, starting service...
New node version:
lux/1.14.0 [network=mainnet, database=v1.4.0, commit=...]
Done!
```

</Step>
</Steps>

### Method 2: Docker

For Docker users, pull the new Granite image:

- **Docker Image**: [`avaplatform/luxgo:v1.14.0`](https://hub.docker.com/r/avaplatform/luxgo/tags?name=v1.14.0)

```bash
docker pull avaplatform/luxgo:v1.14.0
```

### Method 3: Pre-Built Binary

1. Go to the [LuxGo releases page](https://github.com/luxfi/luxgo/releases)
2. Find version v1.14.0 (Granite release)
3. Download the appropriate file for your system:
   - **Linux (AMD64)**: `luxgo-linux-amd64-v1.14.0.tar.gz`
   - **Linux (ARM64)**: `luxgo-linux-arm64-v1.14.0.tar.gz`

4. Extract and run:

```bash
tar -xvf luxgo-linux-amd64-v1.14.0.tar.gz
./luxgo-v1.14.0-linux/luxgo
```

### Method 4: Build from Source

For developers who want to build from source:

```bash
# Clone the repository (skip if already cloned)
git clone https://github.com/luxfi/luxgo.git
cd luxgo

# Fetch and checkout Granite release
git fetch --all --tags
git checkout --force tags/v1.14.0

# Build the binary
./scripts/build.sh

# Verify the version
./build/luxgo --version

# Run the node
./build/luxgo
```

## L1s/Subnets Nodes

For nodes running L1s (formerly Subnets), you need to upgrade both LuxGo and the Subnet-EVM plugin:

### Method 1: Docker (Easiest)

Use the Docker image that includes both LuxGo v1.14.0 and Subnet-EVM v0.8.0:

- **Docker Image**: [`avaplatform/subnet-evm_luxgo:v0.8.0_v1.14.0`](https://hub.docker.com/r/avaplatform/subnet-evm_luxgo/tags?name=v0.8.0_v1.14.0)

```bash
docker pull avaplatform/subnet-evm_luxgo:v0.8.0_v1.14.0
```

<Callout type="info">
This Docker image includes the Subnet-EVM v0.8.0 binary pre-installed, so no additional plugin installation is needed.
</Callout>

### Method 2: Manual Binary Update

If running LuxGo manually, you need to:

1. **Upgrade LuxGo** using any method from the Primary Network section above
2. **Update the Subnet-EVM plugin**:

```bash
# Stop your node first
sudo systemctl stop luxgo

# Download the plugin (example for Linux AMD64)
wget https://github.com/luxfi/subnet-evm/releases/download/v0.8.0/subnet-evm_0.8.0_linux_amd64.tar.gz
tar -xvf subnet-evm_0.8.0_linux_amd64.tar.gz

# Copy to plugins folder and rename to your VM ID
cp subnet-evm ~/.luxgo/plugins/<YOUR_VM_ID>

# Restart your node
sudo systemctl start luxgo
```

<Callout type="warning">
Ensure the plugin binary has the correct permissions and is renamed to match your L1's VM ID in the plugins directory.
</Callout>

## Verifying the Upgrade

After upgrading, verify you're running Granite by checking the node version.

### API Health Check

Run this curl command on your node machine to get detailed version information. You can also use the [API Health Check](/docs/api-reference/health-api#healthhealth) to check the node version.

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeVersion"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

You should see a response similar to:

```json
{"jsonrpc":"2.0","result":{"version":"luxgo/1.14.0","databaseVersion":"v1.4.5","rpcProtocolVersion":"44","gitCommit":"dce38e90b1542fafa3c2b8efa8ef864d7a370eb6","vmVersions":{"xvm":"v1.14.0","evm":"v0.15.4","platform":"v1.14.0"}},"id":1}
```

The `version` field should show `lux/1.14.0` confirming your node is running Granite.

## Stay Updated

To receive notifications about future upgrades:

1. **Lux Notify**: If you have a node, subscribe to the [Lux Notify service](/docs/nodes/maintain/enroll-in-lux-notify) with your node ID
2. **GitHub Notifications**: Watch the [LuxGo repository](https://github.com/luxfi/luxgo) and select "Releases" under custom notifications
3. **For L1 Chains**: Also watch the [Subnet-EVM repository](https://github.com/luxfi/subnet-evm) for plugin updates

## Troubleshooting

If you encounter issues during the upgrade:

- Ensure you've properly backed up your staker files
- Check that your previous node version is completely stopped before upgrading
- For service-based installations, verify the service name (could be `luxgo.service` or `lux.service`)
- For L1s/Subnets, ensure the Subnet-EVM plugin is updated to v0.8.0 and renamed to match your VM ID
- Join the [Lux Discord](https://discord.gg/lux) for community support


# Lux Granite Upgrade - Enhancing ICM, Unlocking Biometric Use Cases, and Enabling Dynamic Block Times (/blog/granite-upgrade)

---
title: Lux Granite Upgrade - Enhancing ICM, Unlocking Biometric Use Cases, and Enabling Dynamic Block Times
description: The Lux Granite upgrade activates on Testnet Testnet on October 29th, 2025, bringing major improvements including Platform-Chain epoched views for ICM, secp256r1 support for biometric authentication, and dynamic minimum block times for faster transactions.
date: 2025-11-05
authors: [LuxDevelopers]
topics: [Granite Upgrade, ICM, Biometric, Block Time, LP, Performance]
comments: true
---

## Introducing Lux Granite

**UPDATED**: The Mainnet [release](https://github.com/luxfi/luxgo/releases/tag/v1.14.0) for the latest upgrade to the Lux Network, dubbed "Lux Granite", activated on Mainnet **November 19th, 2025 at 11 AM ET (4 PM UTC)**.

**_Action Required_: All Mainnet node operators must upgrade their nodes to v1.14 before the scheduled activation time or risk operational failure.** For instructions on upgrading your node, see [this guide](https://build.lux.network/blog/granite-installer).

The [pre-release](https://github.com/luxfi/luxgo/releases/tag/v1.14.0-testnet) was published on October 21st, 2025 and successfully activated on the Testnet Testnet at 11 AM ET (3 PM UTC) on Wednesday, October 29th, 2025.

The Granite upgrade is driven by three Lux Community Proposals that significantly enhance the network's capabilities:

- [LP-181: Platform-Chain Epoched Views](/docs/lps/181-p-chain-epoched-views)
- [LP-204: Precompile for secp256r1 Curve Support](/docs/lps/204-precompile-secp256r1)
- [LP-226: Dynamic Minimum Block Times](/docs/lps/226-dynamic-minimum-block-times)

---

## Node Operator Requirements

### Mainnet Node Operators

**Action Required**: All Mainnet node operators must upgrade their nodes to **v1.14** before **11 AM ET (4 PM UTC) on November 19th, 2025**.

The Lux Granite Upgrade includes protocol optimizations that are not compatible with LuxGo versions < v1.14. If you run a node on Mainnet, you must upgrade your software to LuxGo >= v1.14 before the activation time. The plugin version is updated to 44. All plugins must update to be compatible. Ensure your node is running with the correct plugin version as specified in the [release notes](https://github.com/luxfi/luxgo/releases).


**Critical Warning**: All Mainnet nodes must upgrade before **11 AM ET, November 19, 2025**, or risk going offline once Granite activates. This warning applies to L1 validators who risk finalizing invalid blocks past the Granite activation time without epoch information if they fail to upgrade in time.

L1 validators **must** upgrade to the latest version of Subnet-EVM to be compatible with the Granite upgrade. [Learn more about upgrading your L1 to Granite](https://build.lux.network/blog/granite-installer#l1ssubnets-nodes).

### Testnet Testnet Node Operators

The Granite upgrade successfully activated on the Testnet Testnet at **11 AM ET (3 PM UTC) on Wednesday, October 29th, 2025**. Testnet node operators have upgraded their nodes to **[v1.14-testnet](https://github.com/luxfi/luxgo/releases/tag/v1.14.0-testnet)**, which includes protocol optimizations that are not compatible with LuxGo versions < v1.14-testnet. The plugin version is updated to 44.

**Please note**: This Testnet pre-release is unable to run on mainnet and will display "mainnet is not supported" if attempted with a mainnet configuration.

---

## Enhancing ICM Verification with Platform-Chain Epoched Views

This upgrade activates **LP-181**, which significantly improves the robustness and cost-effectiveness of Interchain Messaging (ICM) verification on Lux's L1 chains.

### The Challenge

Previously, the Platform-Chain pointers were updated with every block, leading to validation uncertainty and potential invalidation of ICM messages due to continuous changes in the validator set. This created inefficiencies and increased costs for cross-chain message verification.

### The Solution

With LP-181, the Platform-Chain height is fixed for an entire epoch period (approximately 5-10 minutes), providing a stable validator set view. This ensures ICM messages are verified against a consistent Platform-Chain height, reducing invalidation risk and lowering costs.

### Benefits for Developers

By allowing L1 chains to maintain a consistent view of the Platform-Chain, LP-181 enhances the efficiency and reliability of ICM message handling across the network. Developers building cross-chain applications can now rely on:

- **Cheaper message verification** - Reduced computational overhead
- **More reliable cross-chain messaging** - Lower invalidation risk
- **Predictable validator set views** - Stable reference points for verification

[Watch the LP-181 community call](https://youtu.be/1c6Qa1sobQg?si=eeTSG3pdPPNcAW_o) to learn more about the technical details.

---

## Unlocking New Biometric Use Cases with secp256r1

This upgrade introduces support for signature verifications using the **secp256r1 elliptic curve** via **LP-204**, enabling innovative biometric data signing on the Lux network.

### New Capabilities

With secp256r1 curve support, developers can now implement biometric data signing, unlocking a range of new use cases:

- **Secure identity verification** through fingerprint or facial recognition
- **Enhanced user authentication** processes without traditional passwords
- **FaceID/TouchID-style logins** integrated directly into dApps
- **Seamless, secure transactions** with biometric confirmation

### Enterprise Applications

The integration of biometric data signing facilitates the development of decentralized applications that require high-security standards, such as:

- Digital identity platforms
- Secure access control systems
- Healthcare applications with HIPAA compliance
- Financial services with enhanced KYC/AML processes

LP-204 expands the possibilities for biometric implementations, positioning Lux at the forefront of blockchain innovation. Developers can now deliver stronger security and a smoother user experience by integrating modern biometric authentication methods into their applications.

---

## Enabling Faster Transactions with Dynamic Minimum Block Times

This upgrade activates **LP-226**, introducing a dynamic adjustment mechanism for block times on the Lux network, which enhances user experience by reducing latency.

### How It Works

LP-226 allows validators to dynamically adjust block times in response to network improvements, such as the upcoming Streaming Asynchronous Execution (SAE) and Firewood features. This flexibility enables:

- **Sub-second block times** - Significantly faster than the previous fixed intervals
- **Continuous optimization** - Validators can adjust block times without network upgrades
- **Stake-weighted preferences** - Network converges around validator consensus

### The Impact

Previously, block rates could only be changed during network upgrades, creating rigid constraints on performance improvements. With LP-226, validators can continuously optimize block times to match the network's evolving capabilities.

This upgrade ensures that users benefit from:

- **Quicker transaction finality** - Reduced time to confirmation
- **Lower end-user latency** - More responsive applications
- **Improved network efficiency** - Better resource utilization
- **Future-proof scalability** - Ready for upcoming performance enhancements

[Watch the LP-226 community call](https://youtu.be/v792NyX58sI?si=2TfJpRg1Ju0AePs6) to learn more about the technical implementation.

---

## Looking Ahead

The Granite upgrade represents another significant step forward in Lux's evolution as a high-performance blockchain platform. By improving ICM reliability, enabling biometric authentication, and allowing dynamic block time adjustments, Lux continues to deliver the speed, flexibility, and scalability that developers need.

As the network continues to evolve with upcoming features like Streaming Asynchronous Execution (SAE) and Firewood Database integration, these Granite improvements lay the foundation for even greater performance enhancements.

---

## Summary of Changes

This section provides a technical overview of the changes introduced in the Granite upgrade for developers and node operators.

### New Block Headers (LP-226)

Two new headers have been introduced as part of LP-226 for dynamic block time management:

1. **`timestampMilliseconds`** (uint64) - Timestamp in milliseconds for more precise block timing
2. **`minDelayExcess`** (uint64) - Tracks the excess delay for dynamic block time adjustments

See the [full changelog](https://github.com/luxfi/luxgo/blob/master/graft/coreth/RELEASES.md#pending-release) for implementation details.

#### For L1s

For Subnet-EVM's [Fee Manager Precompile](https://build.lux.network/docs/lux-l1s/precompiles/fee-manager) these fields are deprecated by LP-226 and no longer effective:

- `targetBlockRate`
- `minBlockGasCost`
- `maxBlockGasCost`
- `blockGasCostStep`

For existing L1s, there is no action required. These fields will be ignored by the fee manager precompile.

For new L1s, these fields should continue to be populated with their defaults. These fields will be removed in a future upgrade.

### New Data Structures (LP-181)

A new struct has been added as part of LP-181 to support epoched Platform-Chain views:

- **`Epoch`** struct - Provides stable Platform-Chain height references for ICM message verification
  - [View implementation](https://github.com/luxfi/luxgo/blob/master/vms/proposervm/block/block.go#L58)

### New API Methods

Three new API methods have been added to support the Granite upgrade features:

1. **`proposervm.GetProposedHeight`** - Returns this node's current proposer VM height.
   - [Documentation](https://build.lux.network/docs/api-reference/proposervm-api#proposervmgetproposedheight)

2. **`proposervm.GetCurrentEpoch`** - Returns the current epoch information.
   - [Documentation](https://build.lux.network/docs/api-reference/proposervm-api#proposervmgetcurrentepoch)

3. **`platform.GetAllValidatorsAt`** - Get the validators and their weights of all L1s and the Primary Network at a given Platform-Chain height.
   - [Documentation](https://build.lux.network/docs/api-reference/p-chain/api#platformgetallvalidatorsat)

**Note**: While `platform.getProposedHeight` will not be immediately deprecated, you should switch to using `proposervm.getProposedHeight` for future compatibility.

### Node Configuration Changes

#### For L1 Operators

Add the `--min-delay-target` parameter to your [subnet-evm chain config](https://build.lux.network/docs/nodes/chain-configs/subnet-evm) to enable sub-second minimum block times:

```json
{
  "min-delay-target": <uint64_value>
}
```

#### For Primary Network Node Operators

Add the `--min-delay-target` parameter to your [LUExchange-Chain config](https://build.lux.network/docs/nodes/chain-configs/c-chain) to vote on the target minimum block time enforced by the proposerVM on the LUExchange-Chain:

```json
{
  "min-delay-target": <uint64_value>
}
```

_Note_: If the `--min-delay-target` parameter is not set, the validator abstains from voting on the target minimum block time.

---

## Resources

- [LP-181: Platform-Chain Epoched Views](/docs/lps/181-p-chain-epoched-views)
- [LP-204: secp256r1 Curve Support](/docs/lps/204-precompile-secp256r1)
- [LP-226: Dynamic Minimum Block Times](/docs/lps/226-dynamic-minimum-block-times)
- [LuxGo Releases](https://github.com/luxfi/luxgo/releases)
- [Join the discussion on GitHub](https://github.com/lux-foundation/LPs/discussions)

---

## About Lux

Lux is a high-performance blockchain platform designed for builders who need to scale. Engineered with a revolutionary three-part Layer 1 (L1) architecture, Lux is anchored by its Lux Consensus Mechanism, ensuring near-instant finality for transactions. The platform also features an open-source Layer 0 (L0) framework, enabling the seamless creation of interoperable Layer 1 blockchains with high throughput on both public and private networks.

Supported by a global community of developers and validators, Lux offers a fast, low-cost environment for building the next generation of decentralized applications (dApps). With its unique blend of speed, flexibility, and scalability, Lux is the preferred choice for innovators pushing the boundaries of blockchain technology.

---

**Follow [@LuxDevelopers](https://x.com/LuxDevelopers) for updates and join our developer community to stay informed about future upgrades and tooling improvements.**


# Install Lux CLI (/blog/install-avalanche-cli)

---
title: Install Lux CLI
description: Lux CLI is a command line tool for accessing Lux, specializing in developing and testing L1 chains.
date: 2024-05-26
authors: [martin_eckardt]
topics: [Lux CLI]
---

Lux CLI is a command line tool that gives developers access to everything Lux. This release specializes in helping developers develop and test L1 chains. This guide shows you how to install Lux CLI on your machine.

## Compatibility

Lux-CLI runs on Linux and Mac. Windows is currently not supported.

## Instructions

To download a binary for the latest release, run:

```shell
curl -sSfL https://raw.githubusercontent.com/luxfi/lux-cli/main/scripts/install.sh | sh -s
```

The script installs the binary inside the `~/bin` directory. If the directory doesn't exist,
it will be created.

## Adding Lux-CLI to Your PATH

To call the `lux` binary from anywhere, you'll need to add it to your system path. If you installed
the binary into the default location, you can run the following snippet to add it to your path.

```shell
export PATH=~/bin:$PATH
```

To add it to your path permanently, add an export command to your shell initialization script. If
you run `bash`, use `.bashrc`. If you run `zsh`, use `.zshrc`.

For example:

```shell
export PATH=~/bin:$PATH >> .bashrc
```

## Checking Your Installation

You can test your installation by running `lux --version`. The tool should print the running version.

## Updating

To update your installation, you need to delete your current binary and download the latest version
using the preceding steps.

## Building from Source

The source code is available in this [GitHub repository](https://github.com/luxfi/lux-cli).

After you've cloned the repository, checkout the tag you'd like to run. You can compile the code by
running `./scripts/build.sh` from the top level directory.

The build script names the binary `./bin/lux`.

# Economics of L1 Blockchains: Deploying on Public Permissionless Chains vs. Your Custom L1 Blockchain (/blog/l1-economics)

---
title: "Economics of L1 Blockchains: Deploying on Public Permissionless Chains vs. Your Custom L1 Blockchain"
description: Discover the economic factors that influence the decision to deploy blockchain applications on public permissionless blockchains like Ethereum versus creating your own custom Layer 1 (L1) blockchain on Lux. This article explores the impact of transaction fees, validator incentives, and decentralization models, offering insights for developers to determine when launching a dedicated L1 makes sense. Ideal for developers and blockchain enthusiasts looking to optimize cost efficiency and user experience in decentralized applications.
date: 2024-08-30
authors: [martin_eckardt]
topics: [L1, Tokenomics]
comments: true
---

When considering the deployment of a blockchain application, developers often face a critical decision: Should the application be launched on an existing public permissionless blockchain like Ethereum, or should it operate on a specialized Layer 1 (L1) blockchain? The answer to this question depends on various factors, with transaction fees being among the most significant. Understanding the economic implications of each option is essential for making an informed choice that aligns with your project's goals and long-term success.

## Understanding Transaction Fees on Public Permissionless Blockchains

Public permissionless blockchains like Ethereum or Lux's LUExchange-Chain have an inherent structure where users pay transaction fees — commonly known as gas fees — in a token that holds real value (e.g., ETH or LUX). These fees compensate the network validators for securing and processing transactions on the blockchain. The fee is determined by supply and demand dynamics, with users bidding on the limited block space available to include their transactions.

The challenge with this model is that gas fees can fluctuate wildly based on network activity. During periods of high demand—such as NFT drops, DeFi protocol launches, or bull markets—transaction fees can spike to levels that deter users from interacting with your application. For applications with many low-value transactions, these high fees can become prohibitive, leading to decreased user adoption and engagement. This is particularly problematic if your users are not even aware that they are interacting with a blockchain, as is often the case with mainstream applications.

To mitigate this, developers might implement gas sponsoring and account abstraction, where the application absorbs the cost of the transaction fees. However, this introduces a continuous cost for every interaction, which can become unsustainable, especially if the underlying asset's value (e.g., LUX) increases significantly. For instance, if LUX appreciates from $20 to $60, your gas sponsoring costs could triple, drastically altering your application’s economics.

## The Case for Launching a Custom L1 Blockchain

When considering the deployment of a blockchain application, the option to spin up your own L1 blockchain on Lux offers a compelling alternative. With your own L1, you have complete control over the transaction fee structure. This flexibility is invaluable, especially for applications with a high volume of low-value transactions. By setting transaction fees according to your specific economic model, you can ensure that fees remain low, predictable, and aligned with your users' needs.

For example, in a gaming application where users frequently make micro-transactions, high transaction fees on a public blockchain could be a significant barrier to user retention. By deploying your own L1, you can minimize or even eliminate these fees, thereby enhancing the user experience and driving higher engagement. This is particularly relevant for applications that target mainstream audiences, where a seamless and cost-effective user experience is paramount.

## Decentralization Considerations

When launching your own L1, it's crucial to consider how you will secure and govern the network. Some use cases might opt for a Proof of Authority (PoA) model with a permissioned validator set, where validators are pre-approved and known entities. This approach offers a higher degree of control but at the expense of decentralization.

On the other hand, if you choose a permissionless validator set using Proof of Stake (PoS), you need to ensure that your transaction fee structure sufficiently compensates the independent validators for their running costs and provides additional incentives. This is essential for maintaining a healthy and secure network, as validators need to be motivated to participate and uphold the integrity of the blockchain. Striking the right balance between validator incentives and user costs is key to the long-term success of your custom L1.

## When Does a Custom L1 Make Sense?

Deciding whether to deploy on a public blockchain or create your own L1 is ultimately about determining your breakeven point. Here are some key considerations:

#### Transaction Volume and Value
If your application processes a high volume of low-value transactions, a custom L1 may be more cost-effective in the long run. Conversely, if your application handles only a few high-value transactions, the cost savings may not justify the complexity of running a separate L1.
  
#### Fee Stability
On a public blockchain, you are at the mercy of network-wide fee fluctuations. With a custom L1, you can ensure fee stability, which is crucial for budgeting and long-term planning.

#### Infrastructure Costs
The primary cost of running an L1 is the infrastructure required to support the validator set. Once you establish an appropriate number of validators based on your security requirements, the operational costs become mostly fixed. These costs are independent of the number and complexity of the transactions processed on your chain, providing predictable financial outlays as your application scales.

## Conclusion

Launching a blockchain application on a public permissionless blockchain or spinning up your own L1 on Lux is a decision that depends heavily on your application's transaction profile and economic model. If you anticipate high transaction volumes with low individual values, a custom L1 could offer significant economical advantages in terms of fee management and user adoption. However, for applications with fewer, high-value transactions, the convenience and existing infrastructure of a public blockchain might be more appropriate.

Ultimately, the decision should be driven by a careful analysis of your transaction patterns, user experience goals, and the potential for fee volatility in public networks. By weighing these factors, you can make an informed decision that aligns with your application's long-term success.

# How Do L1 Validator Fees Work? (/blog/l1-validator-fee)

---
title: How Do L1 Validator Fees Work?
description: This guide provides an overview of how L1 validators are charged LUX to participate in sovereign L1s, how the fee is determined, and how this information can be retrieved from the Lux Platform-Chain.
date: 2025-01-30
authors: [meagfitzgerald]
topics: [ Lux Network Upgrade, Etna Upgrade, Validators, Layer 1, L1, L1 Validators, Continuous L1 Validation Fee]
comments: true
---

## What are L1 Validators?

Introduced with LP-77, [Lux L1 Validators](https://build.lux.network/guides/subnet-vs-l1-validators) enable the creation of sovereign L1
networks with minimal dependency on the Lux Primary Network. Unlike Subnet validators, L1 validators do not stake LUX, but instead pay a
continuous dynamic fee called the L1 Validator Fee.

## L1 Validator Balance

This new fee mechanism takes advantage of the fact that each L1 validator uses the same amount of computation and charges every validator the same fee.

To charge L1 validators, a "Balance" system is used. This balance is charged continuously while a validator is active to cover costs of storing their
information (such as BLS key, weight, nonce) in active state and tracking their IP addresses. Each L1 Validator carries a balance, starting from when
the validator is added with the `RegisterL1ValidatorTx` transaction. It can be increased anytime using the `IncreaseL1ValidatorBalanceTx`. If the
balance reaches zero, the validator becomes "inactive" and stops validating. Once inactive, their properties are removed from memory and stored on
disk, and any messages from them will be invalid until they are revived. Inactive validators can be revived by re-upping their balance using
`IncreaseL1ValidatorBalanceTx`.

## How Fees are Charged

LuxGo calculates the accrued fees for a block based on the formula: fee rate (in nLUX/sec) \* duration since the prior block (in seconds) for
every block. For each L1 validator, LuxGo tracks a value called the
[`endAccumulatedFee`](https://github.com/luxfi/luxgo/blob/ab4619873028fd975dfa6e89e53e555dd53e0cdb/vms/platformvm/state/l1_validator.go#L116-L124), which represents the total fees that will accumulate
in the future at the current rate. Once this value is reached, the validator will be marked as “inactive” due to the fact that its balance will not
cover the fees accrued until this final block.

When a validator registers with `RegisterL1ValidatorTx`, the balance of LUX is allocated to that validator, and is continuously charged by the
Platform-Chain until it runs out. To prevent the balance from running out, and validation pausing, any validator can increase its balance with
`IncreaseL1ValidatorBalanceTx`. If a validator decides to end its validation with `DisableL1ValidatorTx`, any remaining balance that has not
been used to pay the continuous fee will be returned.

For example, imagine a world where in order to take a taxi, you must first deposit a lump sum upfront. As the taxi travels to your destination,
the fare for the distance travelled is continuously debited from your account. If during the drive you want to increase your balance so you can
travel farther, you can add funds to your balance. Once you end the ride, the driver would return any of the remaining balance to you.

## Who Pays and Who Gets the Change?

`IncreaseBalanceTx` must be used whenever an L1 validator wishes to increase their balance. This transaction can be executed by anyone, meaning that
anyone can increase the balance on behalf of another validator.

However, only the Platform-Chain address set as the `remainingBalanceOwner` when the validator originally registered with `RegisterL1ValidatorTx` can receive
the funds left over if the validator decides to terminate with `DisableL1ValidatorTx`. Your friend can throw you some cash to pay for your cab fare,
but only you can keep the change at the end of the ride.

## Retrieving Validator Fee Information

The current validator fee rate can be retrieved with the Platform-Chain API endpoint
[`platform.getValidatorFeeState`](https://build.lux.network/docs/api-reference/p-chain/api#platformgetvalidatorfeestate).

An L1 validator's available remaining balance can be retrieved using the Platform-Chain API endpoint
[`platform.getL1Validator`](https://build.lux.network/docs/api-reference/p-chain/api#platformgetl1validator).

The validator fee configuration, with the current parameters set to calculate the L1 validator fee rate according to the formula in [LP-77](/docs/lps/77-reinventing-subnets#parameters), can be
retrieved with the Platform-Chain API endpoint
[`platform.getValidatorFeeConfig`](https://build.lux.network/docs/api-reference/p-chain/api#platformgetvalidatorfeeconfig).

## How the Fee Changes

The L1 Validator Fee is calculated each time the Platform-Chain adds a new block, according to the algorithm outlined in
[LP-77](/docs/lps/77-reinventing-subnets#fee-algorithm):

$$ M \cdot \exp\left(\frac{x}{K}\right) $$

where M is the minimum price for validators, and exp(x) is an approximation of the exponential function based on the EIP-4844 specification. The
value K simply controls how quickly the price changes, and x is updated every second based on the difference between the number of active validators
V and the target T:

$$ x = \max(x + V - T, 0) $$

The max function above basically chooses either $(x + V - T)$, or 0, whichever is greater.

If the fees become too high, some validators may exit the set, which will lower x and subsequently reduce the price, helping to maintain an average of
T active validators on the Platform-Chain.

## The Fee Rate Settings

The parameters of the above functions at the time Etna activated were:

- T: target number of validators: 10,000
- C: capacity number of validators: 20,000
- M: minimum fee rate: 512 nLUX/s
- K: constant to control the rate of fee changes: 1,246,488,515

As long as the number of validators stays below the target of 10,000, it will cost ~1.33 LUX/month to run an L1 validator.

K was chosen to set the maximum fee doubling rate to ~24 hours. This is in the extreme case that the network has 20,000 active L1 validators for
prolonged periods of time. Alternatively, if the network has 10,001 L1 validators for a prolonged period of time, the fee rate would double every
~27 years.

In a nutshell, when the total number of L1 validators is greater than or equal to 10,000, the fee rate, a.k.a. the L1 validation fee per second, will
increase in the next block according to the formula. These parameters can be changed with community input and the implementation of any future LP.

The validator fee configuration, with the current parameters set to calculate the L1 validator fee rate according to the formula in
[LP-77](/docs/lps/77-reinventing-subnets#parameters), can be retrieved with the Platform-Chain API
endpoint [`platform.getValidatorFeeConfig`](https://build.lux.network/docs/api-reference/p-chain/api#platformgetvalidatorfeeconfig).


# Lux Octane: Optimizing LUExchange-Chain Fees and Gas Target (/blog/octane-optimizing-c-chain-gas-fees)

---
title: "Lux Octane: Optimizing LUExchange-Chain Fees and Gas Target"
description: The Lux Octane upgrade activates LP-176, enabling validators to dynamically adjust gas targets and implementing improved dynamic fee mechanisms for cheaper gas fees and better network scalability. Activated March 2025.
date: 2025-03-11
authors: [LuxDevelopers]
topics: [Network Updates, Octane Upgrade, LUExchange-Chain, Gas Fees, LP-176, Dynamic Fees, Validators]
comments: true
---

<img src="https://www.lux.network/_astro/67d1a457d18ffe0b373442ab_Screenshot_202025-03-12_20at_208.12.08_E2_80_AFAM_ZQpDwI.webp" alt="Lux Octane: Optimizing LUExchange-Chain Fees and Gas Target" />

This upgrade activates LP-176, which positions the Lux LUExchange-Chain to have cheaper gas fees and better handle future increases in network demand.

---

A [pre-release](https://github.com/luxfi/luxgo/releases/tag/v1.13.0-testnet) for the latest upgrade to the Lux Network, dubbed the "Octane" upgrade, has been published. The Lux Octane upgrade is scheduled to activate on the Testnet Testnet at 11 AM ET (3 PM UTC) on Thursday, March 13, 2025. The upgrade is driven by Lux Community Proposal 176 [\[LP-176\]](/docs/lps/176-dynamic-evm-gas-limit-and-price-discovery-updates), titled: Dynamic EVM Gas Limits and Price Discovery Updates. Following successful activation and testing on the Lux Testnet Testnet, an Lux Mainnet release will be published, with a set future activation time.

**Testnet node operators must upgrade their nodes to** [v1.13.0-testnet](https://github.com/luxfi/luxgo/releases/tag/v1.13.0-testnet) **prior to 11 AM ET (3 PM UTC) Thursday, March 13, 2025.** The pre-release includes protocol optimizations that are **not** compatible with LuxGo versions \<v1.13.0-testnet. The plugin version is unchanged at 39 and is compatible with version v1.12.2. Please note that this release is unable to run mainnet, and will display "mainnet is not supported" if attempted to run with a mainnet configuration.

**If you are a Mainnet node operator, upgrading to v1.13.0 before the set activation time is mandatory, ensuring the client is running with the correct plugin version.** The Octane Upgrade release includes protocol optimizations that are **not** compatible with LuxGo versions \<v1.13.0. If you run a node on Mainnet, you must upgrade your software to LuxGo >=v1.13.0 before the scheduled activation time. Activation time and plugin version for mainnet nodes will be specified in the release notes when the mainnet release is published.

## Improving the Dynamic Fee Mechanism on the LUExchange-Chain

The Lux Octane upgrade activates [LP-176](/docs/lps/176-dynamic-evm-gas-limit-and-price-discovery-updates), which positions the Lux LUExchange-Chain to have cheaper gas fees and better handle future increases in network demand.

Currently, the LUExchange-Chain operates with a static gas target of 15,000,000 gas per 10-second rolling window, using a modified version of the EIP-1559 dynamic fee mechanism. This mechanism has a notable drawback: it can lead to large spikes in gas prices following large blocks that consume their full gas limit. Even smaller subsequent blocks within the same window can trigger further price increases, creating inefficiencies in fee predictability.

The fee mechanism introduced to the LUExchange-Chain improves the handling of blocks that consume large amounts of gas by implementing the same mechanism introduced in [LP-103](/docs/lps/103-dynamic-fees) to determine the base fee of a block. Adding this dynamic fee mechanism has made it possible to significantly lower the transaction fees on the LUExchange-Chain. Gas fee simulations were performed and discussed publicly in an [Lux Developer Community Call](https://www.youtube.com/watch?v=NcjgpG-bU-k). Results have been published and shared [publicly](https://docs.google.com/document/d/1vSNbeaQSi96Pl5EhOMA6WM2uuzGASDVqMtHLkaegP4M/edit?tab=t.0#heading=h.9kukhbsvclk6).

## Validator Voting on Target Gas Consumption

The Lux Octane upgrade also includes modifications to allow block proposers (i.e. validators) to dynamically adjust the target gas consumption rate.

Prior to the Octane upgrade, changing the LUExchange-Chain's static target gas consumption rate required a network upgrade, making it difficult to adapt to performance optimizations or hardware advancements in a timely manner. LP-176 proposes a more flexible and efficient solution by introducing dynamic gas target adjustments based on the preference of Primary Network Validators. While validators can set default configuration values for the desired target gas consumption rate, each validator can alternatively choose to set this value independently based on their own considerations.

This upgrade empowers validators to dynamically adjust the target rate of gas consumption, ensuring the network can scale more effectively in response to varying loads and future growth. A validator that values high transactions per second (TPS) and lower gas fees may vote to increase the gas consumption over time by setting their preference higher than the historical target. The higher the target gas consumption, the more resources that are able to be used by the network. Validators should consider whether their machine will be able to reliably support the resources that are required to properly support that level of gas consumption when choosing their preferred gas target.

This change builds on Lux's commitment to providing a low-cost, high-performance blockchain experience. By enabling dynamic gas limits and refining price discovery, the upgrade enhances the LUExchange-Chain's ability to maintain stable and predictable transaction fees, even during periods of high demand.

## About Lux Blockchain Network

Lux is a high-performance blockchain platform designed for builders who need to scale. Engineered with a revolutionary three-part Layer 1 (L1) architecture, Lux is anchored by its Lux Consensus Mechanism, ensuring near-instant finality for transactions. The platform also features an open-source Layer 0 (L0) framework, enabling the seamless creation of interoperable Layer 1 blockchains with high throughput on both public and private networks.

Supported by a global community of developers and validators, Lux offers a fast, low-cost environment for building the next generation of decentralized applications (dApps). With its unique blend of speed, flexibility, and scalability, Lux is the preferred choice for innovators pushing the boundaries of blockchain technology.

[Website](https://lux.network/) | [Whitepapers](https://avalabs.org/whitepapers) | [X](https://twitter.com/lux) | [Discord](https://chat.avalabs.org/) | [GitHub](https://github.com/luxfi) | [Documentation](https://docs.lux.network/) | [Telegram](https://t.me/luxlux) | [Facebook](https://facebook.com/luxlux) | [LinkedIn](https://linkedin.com/company/luxlux) | [Reddit](https://reddit.com/r/lux) | [YouTube](https://www.youtube.com/c/Luxlux)


# Playing in the P2P Network: Investigating Anomalies in Lux's Transaction Gossip (/blog/p2p-network-anomalies)

---
title: "Playing in the P2P Network: Investigating Anomalies in Lux's Transaction Gossip"
description: A deep dive into how we detected and mitigated anomalous behavior in Lux's P2P network, where MEV actors were exploiting transaction gossip protocols to gain unfair advantages.
date: 2025-09-05
authors: [stephenbuttolph, martin_eckardt]
topics: [P2P Network, MEV, Transaction Gossip, Network Security]
comments: true
---

## Setting things up.

Why bother trying to attack a blockchain that's designed to be resilient when you could just [pretend to be someone's grandchild](https://www.fcc.gov/consumers/scam-alert/grandparent-scams-get-more-sophisticated)? Well, in **P2P (Peer-to-Peer) networks** (a.k.a the wild-west of blockchain systems), gaining even a slight edge can result in massive profits.

**That's why engineers working on a blockchain must pay attention to their P2P network.**

Despite looking cramped and chaotic to some, P2P network dashboards typically reflect a network steadily making progress, albeit occasionally observing packet loss during [monsoon season](https://forums.xfinity.com/conversations/your-home-network/ipv4-packet-loss-on-windy-afternoons/6087431943a1b761d4e812db?commentId=60db3dd83aae1c503595e417&replyId=60db410b4be6c333aae6cb0c) (yes, I've gotten woken up over stuff like this). 

Occasionally, a dashboard hints at something more interesting, like the game of cat-and-mouse revolving around transaction gossip and MEV.

On a recent summer day, one of our monitoring dashboards showed an imbalance between the inbound and outbound volume of "app" messages—those used in Lux's transaction gossip layer. We were receiving significantly more requests than we were sending, and the responses we were sending back were consuming a suspiciously large portion of validator bandwidth.



At first glance, it wasn't clear exactly what was happening. Maybe our metrics were off. Maybe there was a bug in the networking logic. But the imbalance held over time, and the asymmetry was too big to ignore. **Something was wrong.**

## A quick detour: How Lux gossip works.

Lux spreads transactions through a hybrid **push–pull gossip protocol** over its P2P network.

**Push gossip**: Newly issued transactions are pushed to validators across the network, especially those with more stake.*

**Pull gossip**: A validator periodically sends a [Bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) describing its mempool to another uniformly sampled validator, who compares it with their own and responds with any new transactions.

The "pull" math is simple and powerful. Every validator samples uniformly once per second, so each validator should receive about one Bloom filter request per second.

When it comes to the rate of receiving a request from a specific validator, it depends on the size of the validator set:

- Testnet has **~100 validators**, and Mainnet has **~1,000 validators**.
- Testnet nodes are expected to get a request from a specific node **every ~2 minutes**
- On Mainnet, **the expected rate is higher at ~17 minutes.**

*Validators with more stake are prioritized because they're most likely to build the next block.

## The unexpected behavior: It is always the LUExchange-Chain mempool.

On the Testnet Testnet, these metrics behaved exactly as expected.



What we observed on Mainnet wasn't even close.



Our Mainnet nodes were consistently handling 20x the expected number of Bloom filter requests. Additionally, the hit-rates of the Bloom filters were bimodal—an anomaly not seen on Testnet.

While most requests had a high hit-rate (>75%), many requests had an abysmal 0% hit-rate. Almost no requests landed in-between.



This led to the suspicion that certain nodes were **intentionally** sending Bloom filters that didn't match any transactions in our mempool. That's like saying: "I don't have any of your transactions—send me everything you've got."

Intentional or not, they weren't sending bad Bloom filters once every 17 minutes (the rate at which a virtuous validator would). The worst offenders* were hammering the same validators with requests as quickly as **every 8 seconds** (0.125 bad Bloom filters per second).



This meant that targeted validators were repeatedly sending **maximum sized responses—potentially** hundreds of transactions at a time—to the same small set of peers.

Sending too many Bloom filters is one thing. Sending bad Bloom filters is unacceptable! We worked hard to [optimize every CPU cycle](https://github.com/luxfi/luxgo/pull/2622) of those Bloom filter checks! For THIS!?!? Unacceptable.

Interestingly, even non-validators have been asked for mempool information. While these nodes wouldn't receive the initial push gossip, they may have locally issued transactions in their mempools. Although, this could have just been an oversight in the modified implementation.

*Worst offenders:
- NodeID-MuEFvXvbZ964sk1rdQKWNtUc5PJAGkWeL
- NodeID-NHEESrJJNnyCPn5c5Uyp9EZYHCCkZwzuW
- NodeID-MZV1PpqVuFPa56t7TmfA8VVdXxDSHnQW7
- NodeID-LPf42gVqz97N6bogZGXJNTWhgBABEe4qE
- NodeID-3632EmwYracXebFyFTQvcEC7U6VREbPkZ
- NodeID-2KSietvSEq4mX2C8p1DAT83RTJPykxUqN
- NodeID-AyByRGSrfbDaeW4njEYwCzhsnMyZ2KMcw
- NodeID-8fq1H8oStMi9BZrEk8qiE8QAV7AtqGnXt
- NodeID-EtFG3SrbbudeFQCaWRxhwvv28wHpo8VRq

## The Update: MOAR rate limits.

Lux already has a rate limit for Bloom filter requests, so what gives? 

When the Bloom filter requests were originally added, the algorithm was slightly different. Rather than sampling a random validator every second, 10 validators were randomly sampled every 10 seconds.

This meant that a node should never see more than **2 requests every 10 seconds** from the same node, even when accounting for time skew. As such, the rate limiting logic enforced this bound.

However, this sampling approach had two clear downsides:

1. **Wasted bandwidth.**
   Sending the same Bloom filter to multiple nodes made it likely that we would receive duplicate transactions.

2. **High discovery latency.**
   Sending requests every 10 seconds resulted in high discovery latency for nodes not included in the push gossip phase.

When changing to send **one** request every second we didn't make any changes to the rate limit logic. After doing some [quick calculations](https://stattrek.com/online-calculator/binomial), we can see that this was great for virtuous nodes and amazing for MEVers–our rate limit was **hundreds of times** looser than it needed to be.

### The fix:

**Instated probabilistic bounds.**
Instead of a flat cap, we now calculate the expected number of requests, and the variance, from the binomial distribution. On mainnet, this works out to about **10 requests per hour per peer** while still ensuring that honest nodes will almost never get rate-limited.

**Reinforce rate limits.**
Rather than immediately dropping rate limited requests, these requests are included in future rate limiting calculations. This enforces nodes to query no faster than the prescribed rate.

## The results

Immediately upon updating, our nodes reported a significant reduction in outbound bandwidth.



By enabling the improved rate limiting, the total outbound bandwidth was reduced from 320 KiB/s to 200 KiB/s, almost a 40% reduction. These Bloom filter responses (blue) are now replaced with Rate limited responses (yellow), which utilize almost no bandwidth.



Additionally, we observed that we are now rate-limiting the Bloom filters with a low hit-rate. We are now only responding to Bloom filters with a high hit-rate.



We expect MEV actors to adapt over time. Hopefully, they'll stop sending bad Bloom filters to maximize their limited queries. Regardless, the days of nearly unlimited pull gossip requests are over. DUN DUN DUUUUUUNNNNNNN 

## Reflections

This change didn't aim to reduce MEV on Lux. If you post a sloppy swap with wide slippage, you'll still get sandwiched. That's the nature of open, transparent blockchains (for now).

What it does is **protect the network itself**. Validators will no longer waste resources streaming their mempools to adversaries hundreds of times per hour. The gossip layer is back to working as designed: efficient and predictable.

These investigations are my favorite part of working on Lux. Sometimes, protocol development turns into a chess game played in code and metrics, with real money on the line.


# Validator Rewards and Staking Mechanisms on Lux L1s (/blog/staking-and-validator-management)

---
title: Validator Rewards and Staking Mechanisms on Lux L1s
description: This article provides an overview of the mechanics of how L1's can manage their validator set and how the software and infrastructure architecture can affect future integrations.
date: 2025-03-01
authors: [meagfitzgerald]
topics: [ Staking Tokens, L1 Validators, Validator Management]
comments: true
---

## What are L1 Validators?

Introduced with LP-77, [Lux L1 Validators](https://build.lux.network/guides/subnet-vs-l1-validators) 
enable the creation of sovereign L1 networks with minimal dependency on the Lux Primary Network. 
Each L1 manages their own validators with a validator manager smart contract.

## What is a Validator Manager Smart Contract? 

A Validator Manager smart contract (VMC) is one or many smart contracts that work together to define the logic for
L1 validator addition and removal on an Lux L1.

LP-77 enables any Lux L1 to independently manage its own validators. When an L1 network is established, the
Lux Platform-Chain requires each L1 to specify the address that controls the validator set. This address is
responsible for using Inter-chain messaging (ICM) to correspond with the Platform-Chain, notifying the network whenever a
validator is added or removed from the L1. This address should be set to the contract address of the chosen PoA or
PoS VMC. 

The ICM-Contracts repository hosts a standard suite of [validator-manager](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/README.md)
smart contracts that can define standard,
minimal functionality for either PoA and PoS L1 networks. This library is maintained by the Lux Platform
Engineers, and is open to use and extension by any developer in the ecosystem.

## Where Can I Deploy the Validator Manager Contract? 

The contract for controlling the validators of any L1 can be deployed on any blockchain in the Lux Network. Most
chains will choose to deploy their validator manager contract on either (a) the Lux LUExchange-Chain or (b) the L1 it
controls. 

## Proof-of-Authority Networks

If building a Proof-of-Authority (PoA) network, ideally the VMC should be deployed on the L1 chain it is managing so
that the native gas token can be used to pay for validator management transactions. Due to the nature of PoA chains,
the validators would be managed by the creators of the chain, meaning any transactions paid for with the L1's native
gas token would be given the chain creator owns most, if not all of the supply. Without the requirement to stake any
tokens in order to validate, PoA chains can create and instantiate the validators at the time of chain creation, and
maintain the [Platform-Chain validator fee](https://build.lux.network/guides/l1-validator-fee) for the foreseeable future.

## Proof-of-Stake Networks

If designing a Proof-of-Stake (PoS) Lux L1, the validator manager contract must be deployed on the same 
blockchain as the reward token that is being distributed, accompanied by a contract to [calculate validation rewards](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/ExampleRewardCalculator.sol). 
The reward token can be either an ERC20 token or the native token of the L1. The VMC must have minting privileges 
for the reward token, either by enabling the Native Minter Precompile if the VMC is deployed on the L1 it controls,
or via the [ERC20Mintable](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/interfaces/IERC20Mintable.sol) interface provided in the ICM-Contracts repo if the VMC is deployed on LUExchange-Chain or a 
blockchain other than the L1 itself. Ultimately, the staking token must have a supply that's controlled exclusively 
by the VMC and L1 blockchain itself. 

Because most cryptocurrency exchanges, custodians, and onramps are more likely to sync and index older, more 
established chains, deploying the VMC and ERC20 Staking Token contracts on the Lux LUExchange-Chain, in most cases, 
would expedite the time needed to have the staking token listed. The ERC20 staking token VMC controls the supply 
and distribution of the staking token when rewarding validators. 

However, if a PoS L1 aims to use transaction fees as a mechanism for generating validator rewards, implementing 
[native token](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/README.md#nativetokenstakingmanager)
staking offers a streamlined approach to reward distribution. By using the network's native token for 
staking, transaction fees collected from users can be directly recycled and distributed to validators without the 
need for complex processes like burning and re-minting tokens. This simplifies the economic model, reduces 
operational overhead, and ensures a more efficient flow of value within the ecosystem. 

It's important to note that a counterargument exists against the use of transaction fees for value accrual: most
blockchains aim to have the lowest gas fees possible. A better user experience for transactors on-chain usually
includes a fee that is so low, you barely notice it. If the fee is as low as possible, it wouldn't be a great
method of value accrual for an L1's validators; instead of this, the chain can employ a token emissions or token 
inflation scheme, such as the many tokenomics models present on chains like [Lux](https://build.lux.network/docs/quick-start/lux-token#tokenomics)
and [Ethereum](https://consensys.io/blog/your-guide-to-ethereum-validator-staking-rewards). Other mechanisms
can also be employed, such as using fees generated by any on-chain applications to [buy back](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees)
tokens and either hold them in a fund or distribute them to the community.

Regardless of the choice of reward mechanism, native token staking using the ICM-Contracts implementation must be
deployed on the L1's blockchain. Staking rewards are minted by enabling the Native Minter Precompile on the L1's
Subnet-EVM binary, which is configured with a set of addresses with minting privileges of the L1's native token.
As such, the EVM address that NativeTokenStakingManager is deployed to must be added as an admin to the precompile.

Because the supply of the native token will be controlled on the L1 itself, a native staking token may still be
bridged to Lux LUExchange-Chain as a Wrapped ERC20 token and listed on exchanges without the need to index the L1 
chain. 

## Conclusion

In summary, managing L1 validators on Lux involves deploying and configuring Validator Manager Contracts
(VMCs). These contracts, which can be customized for Proof-of-Authority (PoA) or Proof-of-Stake (PoS) networks,
dictate how validators are added and removed. The deployment location of the VMC, along with the choice of reward
mechanism (ERC20 tokens or native tokens), are critical design decisions that impact the L1's functionality and
integration with the broader Lux ecosystem. 

Developers looking to implement or extend these functionalities can leverage the standard suite of validator-manager
smart contracts available in the [ICM-Contracts](https://github.com/luxfi/icm-contracts/blob/main/contracts/validator-manager/README.md)
repository. Detailed information can be found in the [developer documentation](https://build.lux.network/docs/cross-chain/teleporter/overview).



# Subnet & L1 Validators, What's the Difference? (/blog/subnet-vs-l1-validators)

---
title: Subnet & L1 Validators, What's the Difference?
description: This guide defines the difference between Subnet and L1 validators, differentiating the roles and responsibilities of each.
date: 2024-12-04
authors: [meagfitzgerald]
topics: [Lux Network Upgrade, Etna Upgrade, Validators, Layer 1, L1, L1 Validators, Subnet Validators]
comments: true
---

The Etna Upgrade introduced L1s to the Lux network, providing an enhanced sovereign network design to the original Subnet model. 

**L1 Validators**, introduced with LP-77, represent a departure from this model, enabling the creation of sovereign L1 networks with minimal dependency on the Primary Network. 
Unlike Subnet validators, L1 validators do not stake LUX but instead pay a dynamic monthly fee, initially set at approximately 1.3 LUX. 
They are exempt from validating the Primary Network, reducing their resource requirements and making L1 validation more accessible. 
This approach fosters economic inclusivity and sovereignty, allowing developers to define custom validation logic via smart contracts and operate independent networks without staking the Primary Network.  

## Primary Network Validators

Primary Network validators are responsible for processing transactions, securing the network, and participating in consensus and governance decisions. They must stake a minimum of 2,000 LUX and validate all three primary network chains: the X, P, and LUExchange-Chain. 
These validators earn rewards in exchange for enhancing the security of the network. Their role is crucial for the seamless operation of the broader Lux ecosystem. 

As far as it relates to LP-77 and the Etna Upgrade, the requirements for Primary Network validation **are not changing** with the Etna Upgrade. 

## Subnet Validators

Subnet validators are essentially Primary Network validators with additional permissions. They must:

- Stake 2,000 LUX on the Primary Network
- Specify an "end time" for their validation period
- Sync and validate the Primary Network (X, P, and LUExchange-Chains)
- Sync and validate a specific Subnet 

For context, the creation of a Subnet involves issuing a `CreateSubnetTx` on the Platform-Chain, assigning an Owner Key to manage its validator set. 
After this, the holder(s) of the Owner Key can add and remove validators from the Subnet's validator set using the Platform-Chain transactions `AddSubnetValidatorTx` and `RemoveSubnetValidatorTx`. 
These transactions were created pre-Etna for Subnet management and are still valid post-Etna.

## L1 Validators

L1 validators are a new addition to the Lux ecosystem, introduced with LP-77 and the Etna Upgrade. A Subnet can be converted 
by the Owner to a sovereign L1 with `ConvertSubnetToL1Tx`, a new Platform-Chain transaction introduced in this upgrade. This transaction revokes the authority to add and remove Subnet validators from the original Owner Key, and sets the validator
set management to the `address` specified. After a successful `ConvertSubnetToL1Tx`, `AddSubnetValidatorTx` is permanently disabled, and any validator set additions must be coordinated through a `RegisterL1ValidatorTx` (also introduced in LP-77) which can only add **L1 validators**. 

L1 validators are required to:
- Pay a continuous dynamic fee, initially set at approximately 1.33 LUX per month
- Sync and validate a specific L1
- Sync the latest Platform-Chain state

Syncing the Platform-Chain state is required for basic L1 functionality. It enables the L1 to track its validator weights so that it can perform consensus and validate ICM messages from other L1s, including the Platform-Chain.

L1 validators do not need to:
- Stake 2,000 LUX
- Validate or participate in consensus on the Primary Network (X, P, and LUExchange-Chains)

Unless removed by the Owner Key, any Subnet validator added to the network before `ConvertSubnetToL1Tx` will continue to validate the network until its "end time" is reached.

Once a Subnet has been converted to an L1, Subnet validators can no longer be added. After a previous Subnet validator is removed or its "end time" is reached, a validator with
the name NodeID can be added as an L1 validator to the network with `RegisterL1ValidatorTx`, the same as any other L1 validator who wishes to join the network.


# Create a Telegram Mini-App using ThirdWeb SDK (/blog/telegram-miniapps-thirdweb)

---
title: Create a Telegram Mini-App using ThirdWeb SDK
description: This guide shows how to build a Telegram Mini-App using the ThirdWeb SDK on the Lux Testnet Network.
date: 2024-09-04
authors: [owenwahlgren]
topics: [solidity, typescript, Telegram, ThirdWeb]
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Telegram Mini-Apps are a new way to build and deploy applications and games embedded in the Telegram platform. They are built using ThirdWeb, a platform that allows developers to connect and utilize both external and in-app wallets on the Lux network.

Learn more about [ThirdWeb](https://thirdweb.com/).
## Recommended Knowledge

- Basic understanding of Solidity and Typescript.
- Basic understanding of Telegram Bots and the Telegram API.
- Basic understanding of the Lux Testnet Testnet.

## Getting started

<Steps>
<Step>
Create a template from the [ThirdWeb Telegram Mini-App Starter Kit](https://github.com/luxfi/telegram-webapp-lux) by clicking the `Use this template` button on the top right.

![](/guide-images/telegram-miniapp/use-template.png)

**IMPORTANT!!** mark "Include all branches", otherwise Github pages deployment will not work.

![](/guide-images/telegram-miniapp/include-branches.png)

</Step>
<Step>
Clone the new repository & install the dependencies
```bash
git clone <new-repo-url>
cd <new repo>
yarn install
```
</Step>

<Step>
Get the `clientID` from a ThirdWeb account on the [ThirdWeb Dashboard](https://thirdweb.com/dashboard)
</Step>

<Step>
Create a `.env` file in the root of the project and add the `clientID` from the previous step:
```bash
VITE_THIRDWEB_CLIENT_ID=...
```
</Step>

<Step>
Run the project in development mode
```bash
yarn dev
```
</Step>
</Steps>

On `git push` to the `main` branch, the project will be automatically deployed to Github Pages.

Follow the section below to link a Telegram Bot to the webapp.

## Integrating with Telegram Bots
<Steps>
<Step>
Create a new Telegram Bot using [BotFather](https://t.me/botfather)
<Steps>
    <Step>
    Type `/newbot`
    </Step>
    <Step>
    Choose a name for the bot, e.g. `My Lux TWA`
    </Step>
    <Step>
    Choose a username for the bot, e.g. `my_lux_twa_482765_bot`
    </Step>
    <Step>
    Take note of the access token, e.g. `5712441624:AAHmiHvwrrju1F3h29rlVOZLRLnv-B8ZZZ`
    </Step>
    </Steps>
</Step>
 <Step>
    Run `yarn configbot` then follow the dialogue to link the Telegram bot with the webapp
    </Step>
</Steps>


## Points of Interest


<Accordions>
<Accordion title="src/main.tsx">
This is where the app is wrapped with the ThirdWeb provider
```tsx
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <ThirdwebProvider>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </ThirdwebProvider>
);
```
</Accordion>
<Accordion title="src/App.tsx">
This is where the ThirdWeb SDK gets initialized with the `clientID` from the `.env` file and also defines the list of acceptable wallets / authorizations.
```tsx
export const client = createThirdwebClient({ clientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID });

const wallets = [
  inAppWallet({
    auth: {
      options: [
        "email",
        "phone",
      ],
    },
  }),
  createWallet("app.core"),
  createWallet("walletConnect")
];
```

```tsx
function App() {

  return (
    <StyledApp>
      <AppContainer>
        <FlexBoxCol>
          <FlexBoxRow>
            <ConnectButton client={client} wallets={wallets} chain={luxTestnet} showAllWallets={false} />
          </FlexBoxRow>
          <TransferLux />
          <Counter />
        </FlexBoxCol>
      </AppContainer>
    </StyledApp>
  );
}
```

</Accordion>
<Accordion title="src/components/TransferLux.tsx">
The Thirdweb `TransferButton` component is used here to compose a new transfer of native tokens.
```tsx
 <TransactionButton
    transaction={() => {
        const transaction = prepareTransaction({
        to: luxRecipient,
        chain: luxTestnet,
        client: client,
        value: toWei(luxAmount),
    });
    return transaction;
    }}
    onTransactionConfirmed={() => { console.log("Transaction confirmed") }}
    onError={() => { console.log("Transaction error") }}
    >
    Confirm Transaction
</TransactionButton>

```
</Accordion>
<Accordion title="src/components/Counter.tsx">
The `TransferButton` component is used again here to facilitate contract interaction.
```tsx
 <TransactionButton
    transaction={() => {
        const transaction = prepareContractCall({
        contract,
        method: "function increase()",
        params: [],
        });
    return transaction;
    }}
    onTransactionConfirmed={() => { console.log("Transaction confirmed") }}
    onError={() => { console.log("Transaction error") }}
    >
    Increase Count
</TransactionButton>

<TransactionButton
    transaction={() => {
        const transaction = prepareContractCall({
        contract,
        method: "function decrease()",
        params: [],
        });
    return transaction;
    }}
    onTransactionConfirmed={() => { console.log("Transaction confirmed") }}
    onError={() => { console.log("Transaction error") }}
    >
    Decrease Count
</TransactionButton>
```
The hardcoded contract address is `0x7Ff5ca07a5FC4AA062c29E6E32d2691B48598577` which is a [simple counter contract deployed on Testnet.](https://testnet.snowtrace.io/address/0x7Ff5ca07a5FC4AA062c29E6E32d2691B48598577/contract/43113/code)
</Accordion>
</Accordions>


# Use Privy on Lux L1 (/blog/use-privy-on-l1)

---
title: Use Privy on Lux L1
description: This guide shows how to use Social Login and Embedded Wallets with Privy on Lux L1.
date: 2024-08-23
authors: [satatocom]
topics: [Lux L1, Lux Starter Kit, Magic Link, Social Login, Embedded Wallets]
---

In this guide, you will learn how to use Privy to easily onboard your users and create transactions without the need for any Web3 wallet.

## What is Privy?

Privy is a simple tool to easily onboard all your users to web3, regardless of whether they already have a wallet, across mobile and desktop.

## Terminology

Before we dive into the guide, let's first understand the terminology.

| Term | Meaning |
| -------- | ------- |
| Social Login | Social Login is a form of single sign-on (SSO) that allows users to log into a third-party website or app using their existing credentials from a social media platform, such as Google, X (formerly Twitter), or Apple. Instead of creating a new username and password, users can authenticate themselves through their social media accounts, streamlining the login process. |
| Magic Link | A Magic Link is a form of passwordless authentication where users can log into an application or website by clicking a unique, time-sensitive link sent to their email address. This method eliminates the need for a traditional username and password combination, making the login process simpler and more user-friendly. |
| Next.js  | Next.js’ Pages Router is a full-stack React framework. It’s versatile and lets you create React apps of any size—from a mostly static blog to a complex dynamic application. |

## Prerequisites and Recommended Knowledge

- Privy account
- Basic understanding of EVM, and transaction data
- Basic understanding of frontend development

## Preparation

### Create Application and Retrieve API Keys

- Log in to [Privy Dashboard](https://dashboard.privy.io/)
- Click on `New App` on the Applications page.
- Click on the Settings button on the left pane. Under the Basic tab, you'll find the API keys.

### Start a New React Project with Next.js

To create a new Next.js project, run in your terminal:

```bash
npx create-next-app@latest
```

### Install Dependencies

After the React project is created, we need to install some dependencies: to use Privy (its own package), to add a custom chain, to create and use an HTTP client (viem), and to include utilities (ethers).

```bash
npm install @privy-io/react-auth@latest
npm i viem@latest
npm i ethers@latest
```

### Define Your Lux L1

In this guide, we are using the `Echo L1` as an example Lux L1. However, you can use any Lux L1 that has a public RPC URL. If the L1 has an explorer page, you can see better what is happening, but it is not required.

```typescript
export const echo = defineChain({
  id: 173750,
  name: 'Echo L1',
  network: 'echo',
  nativeCurrency: {
    decimals: 18,
    name: 'Ech',
    symbol: 'ECH',
  },
  rpcUrls: {
    default: {
      http: ['https://subnets.lux.network/echo/testnet/rpc']
    },
  },
  blockExplorers: {
    default: {name: 'Explorer', url: 'https://subnets-test.lux.network/echo'},
  },
});
```

### Import Privy into Your App 

After the React project is created, navigate to `page.tsx`. Inside the `Home` function, wrap your content with `PrivyProvider`.

```typescript title="page.tsx"
export default function Home() {

  return (
    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        appearance: {
          theme: 'dark',
          accentColor: '#e84242',
          logo: 'https://your-logo-url',
        },
        embeddedWallets: {
          createOnLogin: 'users-without-wallets',
        },
        defaultChain: echo,
        supportedChains: [echo],
        loginMethods: ['email', 'wallet', 'google', 'apple']
      }}
    >
      { content }
    </PrivyProvider>
  );

}
```

## Walkthrough

So far in the guide, we have installed the necessary dependencies, created our Privy application, and obtained our API key. Now, we are ready to use Privy.

Here is our walkthrough:

- We will create a simple login flow.
- We will create a welcome page for users who have logged in, showing their embedded wallet address and balance.
- We will trigger a test transfer of the `ECH` token via Privy.

### Login Flow

To onboard your users into your application, you just need to know the following hooks:

```typescript
const { ready, authenticated } = usePrivy();
const { login } = useLogin();
```

It's really that simple!

- `ready`: Checks whether the `PrivyProvider` is `ready` to be used.
- `authenticated`: Returns `true` if the user is `authenticated`, `false` otherwise.
- `login`: Opens the Privy login modal and prompts the user to log in.

```typescript
<button onClick={login}>Login via Privy</button>
```

We've only added a button to trigger `login` function, and Privy handles the rest.

![](/guide-images/use-privy-on-l1/1.png)

When we click on the `Login via Privy` button, this modal appears.

![](/guide-images/use-privy-on-l1/2.png)

You can choose any login method to log in. We’ve already defined these options in the `PrivyProvider` when we wrapped our content.

### Welcome Page

After checking whether the user is authenticated or not, we display the following information to the user who has logged in.

![](/guide-images/use-privy-on-l1/3.png)

As you can see, Privy has generated an embedded wallet for our user. We’ve displayed the following properties on the screen: Privy ID, embedded wallet address, and embedded wallet balance.

```typescript
<span>{user.id}</span>
<span>{user.wallet.address}</span>
<span>{balance} ECH</span>
```

We’ve used the user object of Privy to retrieve the user ID and wallet address. To fetch the user’s balance, we need to create an HTTP client for our Lux L1, which we’ve already defined earlier.

```typescript
const client = createPublicClient({
    chain: echo,
    transport: http(),
});
// get native asset balance
client.getBalance({
    address: address,
}).then(balance => {
    setBalance(ethers.formatEther(balance));
});
```

We can allow users to log out using the following hook:

```typescript
const { logout } = useLogout();
```

### Fund the New Wallet Using the Faucet

We’ve funded the new wallet that was generated for our user with some ECH tokens from the [Echo AWM Testnet Faucet](https://test.core.app/tools/testnet-faucet/?subnet=echo&token=echo).

![](/guide-images/use-privy-on-l1/4.png)

After the ECH tokens were sent, our balance updated accordingly.

![](/guide-images/use-privy-on-l1/5.png)

### Send Test Transfer via Privy

Now that we have a balance, we can send some ECH tokens to another recipient via Privy to test Privy's `sendTransaction` flow. Privy provides the following hook for this:

```typescript
const { sendTransaction } = useSendTransaction();
```

We’ve already added the following button to trigger the `transfer` function, which will, in turn, trigger the `sendTransaction` function provided by Privy.

```typescript
<button onClick={transfer}>Send Test Transfer via Privy</button>
```

We have built a simple transaction that sends some ECH tokens to another recipient.


```typescript
const transfer = () => {
    if (authenticated === false || address === undefined) {
        return;
    }
    let receiver = "0x..."; // receiver address
    sendTransaction({
        "value": ethers.parseUnits("0.01", "ether"),
        "to": receiver, // destination address
        "from": address, // logged in user's embedded wallet address
    }).catch(() => {
        // handle err 
    });
}
```

When we click on the `Send Test Transfer via Privy` button, this modal appears. Users can see the following details related to the transaction.

![](/guide-images/use-privy-on-l1/6.png)
![](/guide-images/use-privy-on-l1/7.png)

## Conclusion

What we achieved is the creation of a simple React project that integrates Privy. Our application can now easily onboard new users to our Web3 application without needing them to install a Web3 wallet extension, regardless of which chain they are on.

# The New Payment Stack: How Web3 Rails Are Powering Real-World Transactions (/blog/web3-payment-stack)

---
title: "The New Payment Stack: How Web3 Rails Are Powering Real-World Transactions"
description: Learn how Web3 is quietly becoming the plumbing of everyday finance through stablecoin payments, embedded wallets, and programmable settlement layers on Lux.
date: 2025-12-15
authors: [LuxDevelopers]
topics: [Payments, Stablecoins, USDC, Embedded Wallets, Web3]
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

2025 has set the stage for Web3 quietly becoming the plumbing of everyday finance. The shift isn't happening on trading apps, but at markets, restaurants, street vendors, and digital storefronts – places where consumers aren't thinking "blockchain" at all.

From [Uptop's commerce rails](https://www.lux.network/about/blog/the-quiet-disruptor-how-uptop-and-john-timoney-gomez-are-reinvigorating-fan), and the [Urbanspace x Lux USDC pilot](https://www.lux.network/about/blog/a-new-kind-of-holiday-exchange-comes-to-life-in-new-york-city), to the [Lux Card](https://www.luxcard.com/) and Wyoming's [FRNT stablecoin program](https://www.lux.network/about/blog/frnt-goes-live-the-first-u-s-state-issued-stablecoin-you-can-actually-use), a clear pattern is forming: the next generation of payments will settle onchain, even if the user never sees the chain.

This piece kicks off a deeper series exploring that stack – what's actually under the hood, why it works, and how developers can build on it.

## The Modern Web3 Payment Stack

Most Web2 payment apps disguise a decades-old system made of layers of intermediaries: processors, gateways, issuers, acquirers, and clearinghouses. Web3 payments replace much of that with a programmable settlement layer.

Here's what that stack looks like when built on Lux:

<Steps>
<Step>
### App Layer
*(e.g., Uptop, Urbanspace, LUX Card UI)*

This is the user-facing surface where payments feel like any Web2 app – simple checkouts, clean UI, and no friction.
</Step>

<Step>
### Wallet Abstraction Layer
*(e.g., Core SDK, embedded wallets)*

This layer handles all the behind-the-scenes wallet magic: auto-generated accounts, seamless key management, and user flows that never expose seed phrases. Developers can integrate embedded wallets through providers like:

- [Privy](https://build.lux.network/integrations/privy)
- [Dynamic](https://build.lux.network/integrations/dynamic)
- [Openfort](https://build.lux.network/integrations/openfort)

If you want a walkthrough, here's a step-by-step guide on [using Privy for embedded wallets on L1s](/blog/use-privy-on-l1).
</Step>

<Step>
### Transaction Orchestration
*(e.g., meta-tx, relayers, gas abstraction)*

This layer manages the mechanics of sending onchain transactions without exposing users to gas fees, signatures, or blockchain UX. Toolkits for gasless flows include:

- [0xGasless](https://build.lux.network/integrations/0xgasless)
- [Biconomy](https://build.lux.network/integrations/biconomy)
- [ZeroDev](https://build.lux.network/integrations/zerodev)
</Step>

<Step>
### Settlement Layer
*(e.g., LUExchange-Chain: USDC, FRNT, reward tokens)*

This layer handles real settlement, moving stablecoins like USDC and FRNT onchain with fast, deterministic finality. Lux integrates with [Circle's USDC stack](https://build.lux.network/integrations/circlepay), including CCTP and smart wallet support.
</Step>

<Step>
### Issuer / Compliance Infrastructure
*(e.g., Wyoming stablecoin trust, KYC/AML routing)*

This layer manages regulatory requirements—KYC/AML, identity checks, and compliant stablecoins like USDC and FRNT. It plugs into the orchestration layer so real-world payments stay compliant without friction.
</Step>

<Step>
### Merchant Integration Layer
*(e.g., APIs, POS connectors, reconciliation)*

This is where blockchain settlement connects to merchant systems through APIs, POS integrations, and automated reconciliation—letting businesses accept onchain payments without touching crypto infra.
</Step>
</Steps>

Each layer replaces one or more TradFi intermediaries, which is why these apps feel faster, cheaper, and more programmable.

## Driving Payments Through Embedded Web3 Rails: The Pattern Behind Modern Web3 Commerce

You can substitute a fintech API, a state-issued stablecoin, a marketplace wallet system, an embedded payments SDK—it's the same pattern.

**Embedded Web3 rails = the orchestration layer that abstracts blockchain into a usable payment experience.**

This layer typically handles:

- User identity and wallet linkage
- Gas abstraction or relaying
- Funding and settlement flows
- Stablecoin handling (e.g., USDC, FRNT)
- Merchant reconciliation and reporting
- Compliance routing

Think of it like Stripe's job in Web2, but programmable at the protocol layer.

## Case Studies: The Infra Behind "Invisible Web3"

### Urbanspace Markets: Gasless USDC Payments in NYC

The Urbanspace pilot shows how thousands of non-crypto-native users can transact onchain without knowing it.

**Infra Highlights**

- Auto-generated embedded wallets via Core SDK
- Meta-transactions so users pay no gas
- USDC on Lux for instant, stable settlement
- Smart contract loyalty that behaves like traditional rewards but remains fully portable

What looks like tap-to-pay is actually:
user signs meta tx → relayer broadcasts on LUExchange-Chain → merchant receives USDC in seconds.

This playbook will power many future real-world activations.

### Uptop: The Web3 Commerce Stack for Marketplaces

Uptop takes the same primitives and packages them for e-commerce and marketplace builders.

**Infra Highlights**

- Universal embedded wallets for buyers and sellers
- Platform-level stablecoin treasury tools
- Programmable payouts (e.g., release on delivery events)
- Settlement logic encoded onchain instead of in spreadsheets

Uptop effectively operates as an embedded Web3 rail for marketplaces.

### Lux Card: Turning Stablecoins Into Real-World Spend

The Lux Card extends the same payment stack into a familiar form—credit cards—but they settle via stablecoins underneath.

**Infra Highlights**

- Card processor connections to abstracted fiat endpoints
- Stablecoin funding on LUExchange-Chain (USDC today, FRNT tomorrow)
- Real-time balance checks via embedded wallet infra
- API hooks for building programmable card apps

For developers, stablecoin balances behave like programmable bank accounts.

### Wyoming Stablecoin (FRNT): State-Level Settlement Rails

Wyoming's FRNT (Finality-Resilient Network Token) is a state-regulated onchain settlement asset built for public financial infrastructure.

**Why this matters for developers**

- Government-grade KYC and compliance baked in
- Onchain mint/burn events compatible with existing dApps
- Interoperable with USDC
- Potential for instant payroll, benefits distribution, or B2B settlement

FRNT is effectively a public-sector payment rail that plugs directly into Lux fintech stacks.

## The Bottom Line

Stablecoin payments are no longer experimental—they're quietly becoming part of everyday financial infrastructure. From NYC holiday markets to state-backed digital cash programs, we're watching a new payment stack emerge in real time.

Consumers may never see the blockchain.
Developers, however, now have unprecedented control over how money moves.

**In Part 2:** we'll break down the invisible machinery powering these experiences—embedded wallets, meta-transactions, relayers, and the onchain settlement flows that make Web3 payments actually work.


# What is a blockchain? (/blog/what-is-a-blockchain)

---
title: What is a blockchain?
description: Learn how blockchains differ from centralized systems, their trade-offs, and the best use cases for their secure, transparent architecture.
date: 2024-07-24
authors: [martin_eckardt]
topics: [Blockchain Basics]
---

## Introduction to Different Types of Computers
Computers are integral to our daily lives, and they come in various forms, each designed to serve specific purposes. Here's a quick overview:

1. **Personal Computers (PCs)**: These are the desktops and laptops we use at home or work. They are versatile, powerful, and designed for individual use.
2. **Cloud Computers**: These are powerful servers located in data centers around the world. They provide vast computational resources and storage, accessible via the internet. They are designed for scalability and can handle large-scale applications and data processing.
3. **Mobile Computers**: These include smartphones and tablets. They are portable and offer the convenience of mobility, allowing us to perform computing tasks on the go.

All these computers are *centralized*. This means they are controlled by a single entity or organization. For example, your PC is controlled by you, cloud computers are managed by cloud service providers, and mobile devices are typically controlled by their manufacturers and network providers. Centralization implies that these entities have the power to manage, restrict access to, or shut down these computers if needed.

## Introducing the Blockchain Computer
A **blockchain** is a new kind of computer with a unique and defining property: **decentralization**. Unlike traditional centralized computers controlled by a single entity, a blockchain operates without any central authority. This means no single entity can:

- Turn it off
- Restrict access to it
- Interfere with the execution of the programs running on it

Furthermore, the computation is transparent. Anyone can see the programs running on the blockchain and verify their correctness. This transparency ensures that the blockchain operates fairly and securely.

## How Decentralization Works
Decentralization in blockchain is achieved through a network of **validators**. These are independent entities that run the blockchain software, perform computations, and ensure the integrity of the blockchain. Here’s how it works:

1. **Computation Execution**: Each validator independently performs the same computation. For example, let's consider a simple computation: `5 + 3`.
2. **Consensus Process**: After performing the computation, validators share their results with each other. They then use a process called **consensus** to agree on the correct result. You can think of it as a election, where all validators vote on the correct answer.

The consensus process ensures that all validators reach an agreement on the correct result, given that the majority is honest. This agreement is crucial for maintaining the integrity and security of the blockchain. If a validator tries to cheat or provide an incorrect result, the other validators will detect the discrepancy, and the cheating validator will be penalized.

## Efficiency of Blockchain Computation
While the decentralized nature of blockchain ensures security and integrity, it also makes it **inefficient** compared to traditional computers. Here’s why:

- **Redundant Computation**: Every validator must perform the same computation independently.
- **Consensus Overhead**: Validators need to communicate and agree on the results, which adds extra steps and time.

Due to the redundancy and additional processes, performing computations on a blockchain is much more expensive than on a PC or cloud computer. For instance, while a PC can perform a simple addition in a fraction of a second with minimal cost, a blockchain requires multiple validators to do the same computation and agree on the result, leading to higher computational costs and time.

So, while it's decentralized nature offers significant advantages in terms of security and resistance to control, it also comes at the cost of efficiency and higher computation expenses. As we continue to develop and optimize blockchain technology, we aim to balance these trade-offs and explore its vast potential in various applications.

## Use Cases for Blockchain

Blockchain technology excels in use cases where decentralization, security, and transparency are paramount, making the trade-off for reduced efficiency worthwhile. 

-  In *financial services*, blockchain enables secure, transparent, and tamper-proof transactions without the need for intermediaries like banks. 
- *Supply chain management* benefits from blockchain by providing an immutable ledger that tracks the provenance and movement of goods, enhancing traceability and reducing fraud. 
- *Voting systems* can leverage blockchain to ensure the integrity and transparency of the electoral process, making it resistant to tampering and fraud. 

However, for tasks that prioritize high efficiency and speed over decentralization, such as real-time data processing or complex computational tasks, traditional centralized systems are more suitable. In these cases, the overhead of consensus mechanisms and redundant computations in blockchain would introduce unnecessary latency and cost. Thus, the decision to use blockchain should be guided by the specific needs for security, transparency, and decentralization versus the demand for efficiency and speed.

# Why Test Networks Like Testnet Exist — and Who They're For (/blog/what-is-fuji-testnet)

---
title: Why Test Networks Like Testnet Exist — and Who They're For
description: Test networks, or testnets, play a critical role in the lifecycle of blockchain development. Testnet, Lux's public test network, exists to give developers a safe, low-stakes environment to build, experiment, and validate before deploying to Mainnet.
date: 2025-01-09
authors: [meagfitzgerald]
topics: [Testnets, Testnet Testnet, Lux Testnet, Testnet Tokens, Testnet Faucet]
comments: true
---

Test networks, or *testnets*, play a critical role in the lifecycle of blockchain development. Testnet, Lux's public test network, exists to give developers a safe, low-stakes environment to build, experiment, and validate before deploying to Mainnet.

## Why Testnets Matter

Testnets mirror the functionality of the main network but use valueless tokens and non-production infrastructure. This setup lets developers test smart contracts, infrastructure updates, or protocol-level features without risking real assets or network stability.

They're where bugs are caught, upgrades are trialed, and new ideas are validated — all without consequences to real-world users.

## Who Should Use Testnet

Testnet is ideal for:

* Developers building or testing dApps, tooling, or validators before Mainnet deployment.
* Integrators validating compatibility with Lux APIs, SDKs, or network changes.
* Researchers and educators experimenting with network parameters or teaching blockchain fundamentals.

## Who Shouldn't Use Testnet

Testnet should not be used for:

* Any production-grade systems or client-facing environments.
* Workloads that require high uptime or data persistence.
* Situations where service reliability is critical — because testnets, by design, may be reset, upgraded, or experience downtime without notice.

## The Takeaway

Testnet is where innovation happens first — but not where reliability is guaranteed. It's a proving ground for what's next on Lux. Once your application, validator, or integration is stable and tested, Mainnet is the place to go live.

## Resources

- [Get Testnet Testnet tokens](https://build.lux.network/console/primary-network/faucet)
- [View the Testnet Testnet explorer](https://subnets-test.lux.network/)