LODE / SDK

SDK

Getting started

Install

PackageWhatPeer dependency
@lodefoundation/sdkThe client and the chain-neutral types, every chain—
@lodefoundation/sdk-solanaThe Solana adapter (installs @lodefoundation/carpenter-sdk)@solana/kit ^8.3.0
@lodefoundation/sdk-evmThe EVM adapterviem ^2.56.3
Release
0.1.1
Rust
Git dependencies at the release tag. Not on crates.io.
Quoter wasm
Shipped in @lodefoundation/sdk-solana. An install needs no Rust toolchain.
Licence
Apache-2.0
# both chains
npm install @lodefoundation/sdk @lodefoundation/sdk-solana @lodefoundation/sdk-evm   @solana/kit viem

# Solana only:  npm install @lodefoundation/sdk @lodefoundation/sdk-solana @solana/kit
# EVM only:     npm install @lodefoundation/sdk @lodefoundation/sdk-evm viem

FloorClient

FloorClient takes one adapter per chain family and sends each call to the adapter for the launch’s chain.

Solana
createSolanaAdapter: clusters, quoter, launchTable, traderLink (optional, a referral link).
EVM
createEvmAdapter: chains, rpcUrls.
Amounts
Bigints in base units.
Addresses
Kept verbatim. A Solana address is case-sensitive.

TypeScript

import { FloorClient } from '@lodefoundation/sdk';
import { createSolanaAdapter } from '@lodefoundation/sdk-solana';
import { initQuote } from '@lodefoundation/sdk-solana/quote/wasm';
import { createEvmAdapter } from '@lodefoundation/sdk-evm';
import { createSolanaRpc } from '@solana/kit';

const rpc = createSolanaRpc(process.env.SOLANA_RPC_URL);
// floor_quote_bg.wasm, shipped in the package, served as a file
const quoter = await initQuote(wasmBytes);

const solana = createSolanaAdapter({
  clusters: { mainnet: { rpc } },
  quoter,
  launchTable: async (ref) => lookupTableOf(ref), // a sale's lookup table
});
const evm = createEvmAdapter({
  chains: [8453],
  rpcUrls: { 8453: process.env.BASE_RPC_URL },
});

// one client: each call goes to the adapter for the launch's chain
const floor = new FloorClient([solana, evm]);

Chains

ChainReferenceAdapter
Solana mainnet-betasolanaRef('mainnet')@lodefoundation/sdk-solana
SepoliasolanaRef('devnet')@lodefoundation/sdk-solana
EthereumevmRef(1)@lodefoundation/sdk-evm
BaseevmRef(8453)@lodefoundation/sdk-evm
BSCevmRef(56)@lodefoundation/sdk-evm
Robinhood ChainevmRef(4663)@lodefoundation/sdk-evm
ArcevmRef(5042)@lodefoundation/sdk-evm
SepoliaevmRef(11155111)@lodefoundation/sdk-evm

The EVM chains share one set of LODE addresses; Sepolia is the test set. Rows that carry only Uniswap v4’s contracts are refused by name.

Trading

List launches

listLaunches(chain, { limit }) answers one registry page, newest first, and a cursor for the next.

Unfiltered
Anyone can create a launch with any name and symbol. Identify a launch by its address.
Solana pages
Paged by registry index; a page can hold fewer than limit while cursor is not null.
Phase
pending, bonding, graduated

TypeScript

import { solanaRef } from '@lodefoundation/sdk';

// one registry page, newest first
const { launches, cursor } = await floor.listLaunches(
  solanaRef('mainnet'), { limit: 20 },
);

// listings are unfiltered: match a launch by its address
const launch = launches.find((l) => l.ref.token === MINT);
if (!launch) throw new Error('not on this page: follow the cursor');

Quote

quote(ref, side, amountIn) answers the output and the trader’s whole take, or throws.

FieldWhat
amountInbigint
amountOutbigint
feesEvery part of the take
feesExactboolean
refundOptional
graduatesA buy that sells the sale out graduates the launch inside it
maxExtraNativeThe most native currency such a buy can take on top of amountIn
Take on EVM
LP fee, floor skim, creator fee, holder fee, LODE Platform fee.
Take on Ethereum
LP fee, floor skim, creator fee, holder fee, LODE Platform fee, Carpenter Platform fee.
Sell-back
Before graduation a sell-back pays the launch’s fixed sale price, less the LODE Platform fee, the same for any seller.
// lamports in, base units out
const q = await floor.quote(launch.ref, 'buy', 1_000_000_000n);

q.amountOut;   // bigint
q.fees;        // the trader's whole take
q.graduates;   // a buy that sells the sale out
q.maxExtraNative;

Build a trade

buildTrade(params) never signs. It answers an UnsignedTx: everything one action needs, in order, for one wallet prompt.

FamilyShape
evm{ family, chainId, calls }
solana{ family, cluster, transactions }

TypeScript

const tx = await floor.buildTrade({
  launch: launch.ref,
  side: 'buy',
  amountIn: 1_000_000_000n,
  minAmountOut: (q.amountOut * 99n) / 100n,
  trader,
});

tx.family; // 'evm' | 'solana'

Send on EVM

WalletPrompts
An atomic EIP-5792 batch on the chainOne: the approvals and the trade land together or not at all
No EIP-5792, or no atomic batch on the chainOne per call, in order; a reverted call stops the rest
Approvals
Granted on chain, inside the same batch. No action asks for a Permit2 signature.
Amount
exact for a bonding buy, unlimited for a pool swap (approvalAmount).
Waits
batchTimeoutMs 60 s, receiptTimeoutMs 180 s, wait: false returns at the batch id.

TypeScript

import { sendEvmCalls } from '@lodefoundation/sdk-evm';

// { family: 'evm', chainId, calls }: the missing approvals, then the trade
const sent = await sendEvmCalls(walletClient, tx, {
  onSubmitted: (id) => saveBatchId(id), // an EIP-5792 batch id
  onSent: (hash) => saveHash(hash),     // each transaction, one per call
});
// { path: 'eip5792', id, hashes } or { path: 'transactions', hashes }

Send on Ethereum

ActionTransactionsPrompts
Swap on a graduated pool11
Sell-back during the sale11
Sale buy1, or 2 while the launch is not prepared1
First trade with a referral link+1, the link first1
Signing
Every transaction of one action is signed together, then sent in order; the first failure stops the run.
Blockhash
Shared, valid for about 60–90 s. opts.replan rebuilds what has not landed.
Sale trades
Compiled through the launch’s own lookup table, which launchTable supplies.

TypeScript

import { sendSolanaTransactions } from '@lodefoundation/sdk-solana';

// { family: 'solana', cluster, transactions }: every transaction, in order
if (tx.family === 'solana') {
  await sendSolanaTransactions(wallet, tx, rpc);
}

Rust

Crates

CrateWhat
floor-typesAccount layouts, seeds, constants, discriminators and program ids, over carpenter-types
floor-mathThe skim ramp, fee booking, the bid band, the floor solve, the staircase, the sale, holder rewards, referrals
floor-quoteFloorHookQuoter (the HookQuoter for floor_hook), quote_swap for LODE pools, the sale buy and sell-back
floor-sale-ammA jupiter-amm-interface Amm for LODE bonding sales (its own workspace, jupiter/)

No crate depends on a Solana crate but floor-sale-amm. The Carpenter crates are pinned to the same release; both repositories must point at the same tag.

Rust

# Cargo.toml
[dependencies]
floor-quote = { git = "https://github.com/gudtekdonkey/floor-sdk", tag = "0.1.1" }
floor-types = { git = "https://github.com/gudtekdonkey/floor-sdk", tag = "0.1.1" }

Jupiter adapter

CaseSupported
Buys (wSOL in), exact-inYes
A buy that sells the sale outNo: SaleWouldGraduate
Sell-backs (wSOL out), exact-inYes, where the program carries sell_back_wsol
Sales quoted in another tokenNo: TokenQuoteNotRouted
Exact-outNo: ExactOutNotSupported

Graduated pools are Carpenter pools: carpenter-amm, on the Carpenter SDK page.

Rust

# floor-sdk/jupiter: its own Cargo workspace
cd jupiter && cargo test

# label "LODE": buys (wSOL in) and sell-backs (wSOL out), exact-in
# get_swap_and_account_metas returns Swap::Placeholder until Jupiter's
# interface carries a LODE sale variant

Reference

Types

TypeWhat
ChainRefA chain: solanaRef(cluster) or evmRef(chainId)
LaunchRefA launch: its chain and its token address
LaunchName, symbol, decimals, supply, the quote asset, the phase, the mode, the creator, floorPriceX18, raw
QuoteamountIn, amountOut, fees, feesExact, refund, graduates, maxExtraNative
UnsignedTxEvery call or transaction one action needs, in order
floorPriceX18
The published floor in whole quote per whole token, × 1e18.
raw
The chain’s own decoded accounts.

Errors

codeWhen
no_clusterNo cluster is configured for the chain
not_foundNo launch, pool or position for the reference
not_tradeableThe launch is not trading, or the take cannot be listed whole
needs_traderA sell-back before graduation needs opts.trader
needs_launch_tableA sale trade needs the launch’s lookup table
program_versionThe cluster runs an earlier LODE program set
codeWhen
wrong_chainThe wallet is on another chain. Nothing was sent.
pendingSomething was submitted and the wait ended. Do not send the action again.
batch_failedThe wallet reports the EIP-5792 batch as failed
revertedA transaction reverted; the calls after it were not sent

Program version

This release builds for the LODE program set whose hook callbacks take four accounts, whose sell-back is stateless and which has sell_back_wsol. The mainnet-beta and devnet programs it lists are that set.

Check
createSolanaAdapter reads floor_hook’s ApprovedHook record before building a trade.
Earlier set
SolanaAdapterError('program_version')

Carpenter SDK

LODE’s Solana pools are Carpenter pools. @lodefoundation/carpenter-sdk installs with @lodefoundation/sdk-solana; liquidity and pool creation are documented on the Carpenter SDK page.