Overview

LITHIK documentation

LITHIK is a metaprotocol on Solana for programmable non-fungible assets. Every action is a Deposit: a normal Solana transaction carrying a JSON memo and a small fee to the protocol treasury. Indexers replay deposits under public rules to compute state. There is no custom program, so anything that can sign a Solana transaction can use LITHIK.

Quickstart

1. Install Phantom, Solflare or Backpack.
2. Get free devnet SOL at faucet.solana.com.
3. Open the app, keep the network on devnet, connect your wallet.
4. Go to My Cores and use Drill a Core. Approve the transaction.
5. Open your new core and use Add a layer to change an attribute. Its art redraws and its history grows.

Set your wallet to the same network as the app (in Phantom: Settings → Developer Settings → Testnet Mode → Solana Devnet), so the transaction preview it shows you is accurate. The app sends the transaction through its own RPC; only the signature comes from your wallet.

Using the app

Explore lists every core on the selected network. My Cores shows what you hold, with Drill a Core and Anchor an NFT. Basins lets you open a basin and manage its surveyors. Governance holds proposals and votes. Activity is the raw deposit feed, including rejected deposits and the reason each was rejected.

Click any core to see its attributes, owner, basins, attestations and full history. Each history entry links to its transaction on the Solana explorer. Use the RPC button to plug in a private RPC endpoint if the public one is slow.

Envelope

A valid deposit transaction contains:

1. SystemProgram.transfer from the signer to the treasury, for at least the fee of the op.
2. An SPL Memo instruction (MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr) whose UTF-8 data is lithik: followed by a JSON object with "v":1 and an "op" field.

The memo is at most 560 bytes. The signer of the transaction (its fee payer) is the actor. The transaction signature is the id of anything it creates.

Operations

Drill a Core · mint

n name (1–48), i image URL (https://, ipfs:// or ar://, optional), d description (≤200, optional), a attributes (≤16 keys; values are strings ≤64, numbers or booleans).

lithik:{"v":1,"op":"mint","n":"First Light","a":{"level":1,"element":"ember"}}

Add a layer · set

id core id, with any of n, i, d, a. Attributes merge, and null deletes a key.

lithik:{"v":1,"op":"set","id":"<asset id>","a":{"level":2,"element":null}}

Settle in a Basin · link

lithik:{"v":1,"op":"link","id":"<asset id>","m":"arena-items"}

Transfer · give

lithik:{"v":1,"op":"give","id":"<asset id>","to":"<wallet address>"}

Anchor an NFT · bind

Attach state to an existing NFT mint. If the mint is already bound, this transfers control to the signer and keeps the history.

lithik:{"v":1,"op":"bind","mint":"<nft mint address>","n":"My bound piece"}

Open a Basin · mod

m slug ([a-z0-9][a-z0-9-]{1,23}), n name, d description.

lithik:{"v":1,"op":"mod","m":"arena-items","n":"Arena Items","d":"Weapons and armour for Arena seasons"}

Surveyors · val

lithik:{"v":1,"op":"val","m":"arena-items","add":"<wallet address>"}

Survey · att

lithik:{"v":1,"op":"att","id":"<asset id>","m":"arena-items","ok":true,"note":"balanced stats"}

Propose · prop and Vote · vote

end is a unix timestamp from 1 hour to 31 days after the proposal’s block time. A vote c is y, n or a.

lithik:{"v":1,"op":"prop","t":"Lower the mint fee","d":"Halve the fee for 90 days to grow usage","end":1800000000}

lithik:{"v":1,"op":"vote","pid":"<proposal id>","c":"y"}

Validity rules

• Failed transactions are ignored. Indexers use confirmed commitment.
• Unparseable memos, unknown ops, wrong versions and schema violations are rejected.
• Fee below the op’s fee: rejected.
• set, link, give: the signer must be the current owner. Bound cores cannot be given; they follow the NFT.
• link: the basin must exist and the core must not already be linked to it.
• mod: the slug must be unused. val: the signer must own the basin. The owner cannot be removed.
• att: the signer must be a surveyor of the basin and the core must be linked to it. A newer attestation from the same surveyor replaces the older one.
• vote: only inside the window. The latest vote per wallet counts.

Fees & treasury

You also pay Solana’s normal network fee (about 0.000005 SOL).

Fee schedule

Fees live in feeSchedule in assets/config.js. Each entry has a from unix time, and every deposit is checked against the entry that was active at its block time. A governance decision to change fees therefore adds a new entry with a future from; it never rewrites history.

feeSchedule: [
  { from: 0, lamports: 1000000, fees: { set: 500000, vote: 0 } },
  // after the $LITK launch: pay in the token instead of SOL
  { from: 1767225600, lamports: 0, token: { mint: '<$LITK mint>', decimals: 6, symbol: '$LITK', amount: 10000000, fees: { vote: 0 } } }
]

When an entry has a token, the transaction also creates the treasury’s token account if needed and makes a TransferChecked of the token fee from the signer. The 0-lamport SOL transfer stays in the transaction, because that is how indexers find it.

JavaScript SDK

The whole protocol is one file, assets/protocol.js. It runs in the browser with @solana/web3.js and in Node.

<script src="https://cdn.jsdelivr.net/npm/@solana/web3.js@1.98.4/lib/index.iife.min.js"></script>
<script src="https://lithik.xyz/assets/config.js"></script>
<script src="https://lithik.xyz/assets/protocol.js"></script>
<script>
  const P = createProtocol(solanaWeb3, CONFIG, { cluster: 'devnet' });
  // write: any wallet with signTransaction (Phantom, Solflare, Backpack…)
  await window.phantom.solana.connect();
  const id = await P.sendWithWallet(window.phantom.solana, { op: 'mint', n: 'Hello', a: { level: 1 } });
  // read: replay the ledger
  const state = await P.index();
  console.log(state.assets[id]);
</script>

// Node
const web3 = require('@solana/web3.js');
const createProtocol = require('./assets/protocol.js');
const CONFIG = require('./assets/config.js');
const P = createProtocol(web3, CONFIG, { cluster: 'devnet' });
const sig = await P.sendWithKeypair(keypair, { op: 'set', id, a: { level: 2 } });

CLI

git clone <repository-url> lithik && cd lithik
npm install
node cli/cli.cjs keygen --out ~/.config/solana/id.json
node cli/cli.cjs airdrop 1
node cli/cli.cjs mint --name "First Light" --attr level=1 --attr element=ember
node cli/cli.cjs set <id> --attr level=2 --attr element=
node cli/cli.cjs module arena-items --name "Arena Items"
node cli/cli.cjs link <id> arena-items
node cli/cli.cjs index

Run node cli/cli.cjs help for every command. Add --cluster mainnet-beta or --rpc <url> to change network.

Run an indexer

Snapshots. So that visitors don’t have to read the whole history on their first visit, the site can serve data/records-devnet.json and data/records-mainnet-beta.json. Generate them with node cli/cli.cjs snapshot --cluster devnet. The included GitHub Actions workflow refreshes them every 15 minutes. A snapshot only speeds up loading: the app keeps reading newer deposits from Solana, and RPC → Rebuild from chain ignores the snapshot and recomputes everything locally.

Indexing is just getSignaturesForAddress(treasury) → getParsedTransaction → replay(). The SDK caches what it has seen and only fetches new signatures on the next run. To serve state to others, run index() on a schedule and publish the result as JSON. Because the rules are deterministic, anyone can check your output against their own.

Basins

1. Pick a slug and open a basin in the app or with cli module.
2. Publish your standard: which attributes a core needs and what quality bar it has to meet.
3. Add surveyors with val. They survey linked cores.
4. Applications filter to attested cores to show only what meets the standard.

Governance

Governance starts in a signal phase (one wallet, one vote). When the $LITK mint address is set as tokenMint in assets/config.js, tallies switch to token-weighted automatically. See the Paper for the full process.

FAQ

Is LITHIK its own blockchain?

No. It is a set of rules for reading ordinary Solana transactions. Solana does consensus and settlement.

Do I need to run a validator?

No. LITHIK surveyors are a social role inside basins. They are unrelated to Solana validators and need no hardware.

Can my core be deleted or changed by someone else?

No. Only the owner’s deposits are valid for it. Anything else is recorded as rejected and has no effect.

Will my cores appear in Phantom’s NFT tab?

Native cores live in the LITHIK state, not the SPL token program, so they appear in LITHIK-aware apps. Use Anchor an NFT to add LITHIK state to an NFT that wallets already display.

What does it cost?

See Fees. On devnet it is free test SOL.