> For the complete documentation index, see [llms.txt](https://parad0xlabs.gitbook.io/parad0xlabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parad0xlabs.gitbook.io/parad0xlabs-docs/web0-how-it-all-connects/build-on-null.md).

# Build on .null (Open SDK)

`.null` is a **permissionless protocol**, not a product you have to ask us to use. The programs live on Solana mainnet; anyone can talk to them directly. The open `@parad0x_labs/null-sdk` (MIT) is the thin, typed layer that builds the exact instruction bytes for you — registering names and running **open-ascending (English) auctions** — so you can ship your own resolver, marketplace, or agent without reverse-engineering account layouts.

> **The thesis in one line:** build whatever client you want — the protocol fee is enforced *on-chain*, not by our front-end. Decentralized for users, sustainable for the protocol.

***

## Install

The SDK ships from the `web0` monorepo at `packages/null-sdk` (npm release name `@parad0x_labs/null-sdk`, v0.1.0, MIT). Three small dependencies, no framework:

```bash
npm i @solana/web3.js @noble/hashes poseidon-lite
# then add @parad0x_labs/null-sdk (from the monorepo until it's on the registry)
```

What's in the box:

| Module      | Gives you                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `constants` | program IDs, mints, seeds, currency + instruction tags                                                                |
| `pda`       | `domainPda`, `auctionPda`, `vaultPda`, `commitPda`, `ataFor`, `nameHash`                                              |
| `poseidon`  | Poseidon hashing helpers (Dark Passport commitments)                                                                  |
| `registrar` | `registerIx`, `resolveIx`, `transferIx`, `updateContentIx`, `updateEndpointIx`, `updatePassportIx`                    |
| `auction`   | `ixCreateEnglishAuction`, `ixPlaceBidEnglish`, `ixSettleEnglish`, `ixCancelEnglish`, `englishPda`, `auctionConfigPda` |

Every function returns a plain `TransactionInstruction` (or a `PublicKey`). You keep full control of signing, fee-payer, priority fees, and RPC. The SDK never holds a key.

***

## Resolve a name (read-only, no SDK auth)

The PDA is derived from the **name alone**, so anyone can resolve any name with one RPC read:

```ts
import { Connection } from "@solana/web3.js";
import { domainPda } from "@parad0x_labs/null-sdk";

const conn = new Connection("https://api.mainnet-beta.solana.com");
const pda  = domainPda("alice");                 // alice.null -> PDA (no owner needed)
const acc  = await conn.getAccountInfo(pda);
// decode the 314-byte NullDomain account: owner @65, arweave_txid @97, x402_endpoint @129…
// (full layout in the .null Domain Spec)
```

***

## Register a name

```ts
import { Transaction } from "@solana/web3.js";
import { registerIx, CURRENCY_SOL } from "@parad0x_labs/null-sdk";

const ix = registerIx({
  payer: wallet.publicKey,
  name: "alice",
  currency: CURRENCY_SOL,        // or CURRENCY_NULL to pay the fee in NULL (Token-2022)
  // treasury: TREASURY,         // include only when the configured SOL fee > 0
});

await sendAndConfirm(new Transaction().add(ix), [wallet]);
```

During the pilot the configured fee is **0**, so registration costs only Solana rent. The fee is flippable on-chain by the authority (`SetConfig`) — your code doesn't change when it goes live; you just include the treasury account.

***

## Run an English auction

`.null` resale runs as an **open-ascending (English) auction** — the SDK builds the instruction bytes; the `null-auction` program enforces the rules on-chain. Bids are public and rise in the open; the privacy in Web0 lives in the payment/identity layer (Dark NULL), not in the bidding.

```ts
import {
  ixCreateEnglishAuction, ixPlaceBidEnglish, ixSettleEnglish, ixCancelEnglish,
  auctionConfigPda,
} from "@parad0x_labs/null-sdk";

// 1) Seller lists the name with a start price and a clock. The name is escrowed in
//    the auction PDA, so one name can only have one active sale at a time.
const create = ixCreateEnglishAuction({
  seller: seller.publicKey,
  name: "alice",
  startPriceLamports: 100_000_000n,   // 0.1 SOL opening
  durationSecs: 86_400,               // 24h
  config: auctionConfigPda(),         // on-chain fee config (capped ≤5%)
});

// 2) Anyone bids higher. Each bid must clear the high by the min step (the larger of
//    +5% or +0.05 SOL); the previous high bidder is refunded on-chain in the same
//    instruction. A bid in the anti-snipe window extends the clock.
const bid = ixPlaceBidEnglish({
  bidder: bidder.publicKey,
  name: "alice",
  amountLamports: 150_000_000n,       // 0.15 SOL
});

// 3) Settle (permissionless): name transfers to the high bidder; the seller gets the
//    proceeds minus the protocol fee, the treasury gets the fee, and the auction PDA
//    rent is reclaimed to the seller. No bids → the name returns to the seller.
const settle = ixSettleEnglish({
  caller: anyone.publicKey, name: "alice",
  seller: seller.publicKey, config: auctionConfigPda(),
});

// (Seller can ixCancelEnglish any time before the first bid lands.)
```

Every outbid is refunded the instant it's beaten — losers never come back to claim. The protocol fee is read from the on-chain `AuctionConfig`: capped at 5% in the program, lowerable freely, and any raise is timelocked 48h.

***

## You don't need us — and the house still gets paid

The SDK builds instructions for the on-chain programs **directly**. There is no Parad0x API, no gateway, no key to request. Anyone can fork this SDK, run their own client, or ship a competing marketplace UI — and the protocol fee is still collected, because it's enforced **inside the program**, not by a front-end:

* `Register` charges the configured fee (or the transaction fails).
* `SettleEnglish` pays the treasury its fee — read from the on-chain `AuctionConfig`, capped at 5% (or it doesn't settle).

That's the ENS / Uniswap pattern: the rail is permissionless, the fee is in the contract. The protocol stays funded no matter whose app the user is in.

***

## Caveats

* The programs are **Public Beta** — non-custodial, capped, and **not yet audited**. The SDK is the interface; it inherits that posture. We don't claim "audited."
* **Auctions settle in SOL.** The protocol fee is read from the on-chain `AuctionConfig` (capped at 5%, lowerable freely, any raise timelocked 48h) — your client doesn't change when the fee moves.
* The **Dark NULL** privacy circuits (shielded pool, KVAC, the Passport threshold proofs) use verifying keys that are **single-party** until the trusted-setup ceremony finalizes. The English auction itself uses no ZK — it's plain on-chain SOL escrow.

Build on it. Open an issue or a PR on the `web0` repo if you hit a rough edge — that's what the open SDK is for.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://parad0xlabs.gitbook.io/parad0xlabs-docs/web0-how-it-all-connects/build-on-null.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.