# Documentation

- [Welcome](/docs): Developer documentation for the Nolus Protocol.

- **How it works**
- Protocol: The Nolus protocol - concepts and architecture.
  - [Overview](/docs/protocol/overview): What Nolus is and the moving parts that make it work.
  - [Architecture](/docs/protocol/architecture): How the chain, contracts, and external services connect.
  - Borrowing: How the protocol opens, services, repays, and closes a margin position.
    - [Borrowing](/docs/protocol/borrowing): How the protocol opens, services, repays, and closes a margin position.
    - [Opening a position](/docs/protocol/borrowing/opening): From collateral deposit to active position.
    - [Querying a position](/docs/protocol/borrowing/querying): Observable states and the full set of returned fields.
    - [Quoting a position](/docs/protocol/borrowing/quoting): Preview what a margin position would look like under current LPP utilization.
    - [Repaying and closing](/docs/protocol/borrowing/repaying-closing): Manual repayment, market close (full), and partial close flows.
  - Lending: How lenders supply liquidity to the LPP and earn yield.
    - [Lending](/docs/protocol/lending): How lenders supply liquidity to the LPP and earn yield.
    - [Deposit and withdraw](/docs/protocol/lending/deposit-withdraw): Mint nLPN by depositing LPN; burn nLPN to withdraw principal + accrued interest.
    - [NLS rewards](/docs/protocol/lending/rewards): How the Treasury distributes uNLS incentives to LPPs and how lenders claim them.
  - [Oracle](/docs/protocol/oracle): How prices reach the chain: on-chain oracle contract and off-chain feeder.
  - [Liquidations & risk](/docs/protocol/risk): How Nolus handles drawdowns: partial liquidation, warning thresholds, the reserve backstop.
  - [Security](/docs/protocol/security): The protocol's security model: audits, contract isolation, governance constraints.
- IBC
  - [Overview](/docs/ibc/overview): Inter-Blockchain Communication on Nolus.
  - [Solray](/docs/ibc/solray): The Nolus IBC program on Solana - production addresses and what each on-chain account does.

- **Operate**
- Network: Operating the Nolus chain.
  - [Chain overview](/docs/network/chain-overview): Building, configuring, and running the Nolus chain.
  - Run a full node: Build nolusd, initialize, sync, and operate a full node on Pirin (mainnet).
    - [Run a full node](/docs/network/run-a-node): Build nolusd, initialize, sync, and operate a full node on Pirin (mainnet).
    - [Build nolusd](/docs/network/run-a-node/build): Clone nolus-core, check out a release, compile, and verify the install.
    - [Configure](/docs/network/run-a-node/configure): Initialize the node, fetch genesis and persistent peers, edit gas and pruning settings.
    - [Cosmovisor](/docs/network/run-a-node/cosmovisor): Automate chain-upgrade binary swaps with a systemd-managed Cosmovisor service.
    - [Run the node](/docs/network/run-a-node/run): Start nolusd (with or without Cosmovisor), check sync status, tail logs.
    - [Bootstrap from a snapshot](/docs/network/run-a-node/snapshot): Skip syncing from genesis - recover state from a Nolus-provided snapshot.
  - [Validators](/docs/network/validators): Create, restore, and unjail a Nolus validator.
  - IBC relayer: Run a Hermes IBC relayer that connects Nolus to Osmosis.
    - [IBC relayer](/docs/network/relayer): Run a Hermes IBC relayer that connects Nolus to Osmosis.
    - [Hermes setup](/docs/network/relayer/hermes): Install Rust, build Hermes, configure for Pirin and Osmosis, validate, and run.
    - [IBC transfer channels](/docs/network/relayer/channels): Live IBC channels between Nolus and its counterparty chains.
  - [RPC, LCD, and gRPC endpoints](/docs/network/rpc-endpoints): Public network endpoints for reading chain state and submitting transactions.

- **Build**
- TypeScript SDK: nolus.js - the official TypeScript SDK for the Nolus Protocol.
  - [Getting started](/docs/sdk/getting-started): Use nolus.js to read protocol state and submit transactions.
  - [Examples](/docs/sdk/examples): Common nolus.js workflows: quote, open, query, manage, repay, close, and lend.
- ETL data API: Live indexed protocol data served from the Nolus ETL.
  - [Overview](/docs/etl/overview): What data the Nolus ETL exposes and how to query it.
- Agentic workflows: Drive Nolus from AI agents via three complementary surfaces.
  - [Overview](/docs/agentic-workflows): Three complementary surfaces for driving Nolus from AI agents.
  - [MCP server](/docs/agentic-workflows/mcp-server): Tool surface, network config, and client setup for the Nolus MCP server.
  - [In-page WebMCP](/docs/agentic-workflows/webmcp): Browser-resident agent surface on app.nolus.io - wallet-scoped reads, connect, navigate.

- **Reference**
- [Glossary](/docs/glossary): Vocabulary used across the protocol and these docs.
- [Public APIs](/docs/public-apis): Off-chain APIs around the Nolus protocol.