# Gluon

Gluon is an order‑book Layer‑2 blockchain built with [Rollkit](https://rollkit.dev/) and secured by Sunrise, a next-generation L1 combining data availability and liquidity.\
The base layer for Interliquid Networks.\
The rollup implements Sunrise's Proof‑of‑Liquidity (PoL) and leverages IBC for seamless asset movement.

***

## Key Features

| Category                   | Description                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Order‑book DEX**         | Deterministic matching logic, price‑time priority, and on‑chain settlement.                            |
| **Web2‑style onboarding**  | OAuth registration abstracts private‑key management; user keys never leave the client device.          |
| **Off‑chain matching**     | High‑throughput matching engine batches trades before finalising them on chain.                        |
| **Double‑signature model** | All funding transactions require both user and operator signatures, preventing unilateral withdrawals. |
| **IBC deposits/withdraws** | Native IBC channels connect Gluon to external Cosmos‑SDK chains for trust‑minimised transfers.         |

***

## Developer Overview

* **Source code:** <https://github.com/sunriselayer/gluon>
* **Sunrise Rollkit adapter:** <https://github.com/sunriselayer/sunrise-rollkit>
* **Modules used:** `x/order`, `x/perp`, `x/customauth` (see protobuf definitions).

***

## Authentication & Key Management

Gluon introduces a *CustomAuth* flow that pairs a web‑generated ECDSA key with an on‑chain account:

1. **OAuth sign‑up** → server deterministically derives user address.
2. **Device pairing** → browser generates an AES key and an ECDSA key; the latter is AES‑encrypted and stored server‑side.
3. **Verification key** is submitted on chain (pairing transaction).

### Sign‑up Flow

The sign-up process is intentionally simple and user-friendly:

* Users can sign up using familiar OAuth providers (Google, GitHub, etc.)
* The application automatically derives a Sunrise address for the user
* No manual wallet setup or seed phrase management required

{% @mermaid/diagram content="sequenceDiagram
autonumber
User  ->>  App     : OAuth sign‑up
App   -->  App     : Derive Sunrise address" %}

This streamlined process ensures users can start trading quickly without blockchain complexity.

### Device‑Pairing Flow

The device pairing process implements several security measures:

* Generates unique encryption keys for each device
* Keeps sensitive ECDSA keys encrypted and secure
* Establishes a verification mechanism for future transactions

{% @mermaid/diagram content="sequenceDiagram
autonumber
User     ->> Browser : Initiate pairing
Browser  --> Browser : Generate AES key
Browser  --> Browser : Generate ECDSA key
Browser  --> Browser : Encrypt ECDSA with AES
Browser  ->> App     : Upload encrypted key + verification key
App      ->> Gluon   : Tx: register verification key" %}

This multi-step process ensures secure key management while maintaining user control.

### Order Creation (off‑chain)

The off-chain order creation process enables high-performance trading:

* Orders are signed locally using the user's encrypted key
* Signatures are verified before being accepted
* Orders remain off-chain until batched for matching

{% @mermaid/diagram content="sequenceDiagram
autonumber
User     ->> Browser : Place order
Browser  --> Browser : Decrypt ECDSA key
Browser  --> Browser : Sign order payload
Browser  ->> App     : Order + signature" %}

This approach allows for sub-second order placement while maintaining security.

### Order Cancellation (on‑chain)

The cancellation process ensures order integrity:

* Cancellations are recorded on-chain for transparency
* Prevents replay attacks of old signatures
* Provides immutable proof of cancellation

{% @mermaid/diagram content="sequenceDiagram
autonumber
User ->> App   : Cancel order
App  ->> Gluon : Tx: register order + cancel" %}

This on-chain record is crucial for maintaining order book integrity.

### Withdrawal (IBC)

The withdrawal process implements multiple security layers:

* Requires dual signatures from both user and operator
* Implements a 24-hour security delay for new key pairs
* Uses IBC for trust-minimized cross-chain transfers

{% @mermaid/diagram content="sequenceDiagram
autonumber
User     ->> Browser : Withdraw request
Browser  --> Browser : Decrypt ECDSA key & sign tx
Browser  ->> App     : Signed withdrawal
App      --> App     : Operator signs tx
App      ->> Gluon   : Tx with dual signatures
Gluon    --> Gluon   : Verify signatures & 24 h key‑pairing delay
Gluon    ->> ChainX  : IBC transfer" %}

This multi-layered approach ensures secure and reliable asset transfers across chains.

> No external wallets (e.g., MetaMask) are required; keys remain client‑side and are revocable on‑chain.

## Trading Lifecycle

### Order Creation (off‑chain)

Orders reside off‑chain until batched in the first matching transaction, enabling sub‑second UX.

{% @mermaid/diagram content="sequenceDiagram
autonumber
User     ->> Browser : Place order
Browser  --> Browser : Decrypt ECDSA key
Browser  --> Browser : Sign order payload
Browser  ->> App     : Order + signature" %}

### Order Cancellation (on‑chain)

An on‑chain record prevents operators from replaying stale user signatures.

{% @mermaid/diagram content="sequenceDiagram
autonumber
User ->> App   : Cancel order
App  ->> Gluon : Tx: register order + cancel" %}

### Withdrawal (IBC)

A 24‑hour latency between key‑pairing and fund movements mitigates operator‑key compromise.

{% @mermaid/diagram content="sequenceDiagram
autonumber
User     ->> Browser : Withdraw request
Browser  --> Browser : Decrypt ECDSA key & sign tx
Browser  ->> App     : Signed withdrawal
App      --> App     : Operator signs tx
App      ->> Gluon   : Tx with dual signatures
Gluon    --> Gluon   : Verify signatures & 24 h key‑pairing delay
Gluon    ->> ChainX  : IBC transfer" %}

## Order Module (protobuf)

The order subsystem is defined in `gluon/order/*`. Core types:

The `BaseOrder` message defines the fundamental structure for all orders in the system:

* Each order is associated with a specific user address and trading pair
* Orders can be either limit orders (with a specified price) or market orders
* The expiry timestamp prevents replay attacks and ensures order freshness
* Amount and price are stored as strings to handle arbitrary precision

```go
message BaseOrder {
  string         address      = 1;  // bech32 user address
  string         denom_base   = 2;  // e.g., "uatom"
  string         denom_quote  = 3;  // e.g., "uusdc"
  OrderDirection direction    = 4;  // BUY / SELL
  string         amount       = 5;  // base amount
  string         limit_price  = 6;  // optional
  google.protobuf.Timestamp expiry = 7;  // anti‑replay
}

enum OrderDirection {
  ORDER_DIRECTION_UNSPECIFIED = 0;
  ORDER_DIRECTION_BUY         = 1;
  ORDER_DIRECTION_SELL        = 2;
}
```

The `OrderDirection` enum provides a type-safe way to specify order sides:

* Uses standard protobuf enum conventions with an UNSPECIFIED default
* Clearly distinguishes between buy and sell orders
* Helps prevent order-side related bugs through compile-time checking


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sunriselayer.io/learn/gluon.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.