Exchange Integration

Native LICN exchange integration is published for testnet-only integration testing under exchange-testnet-v0.5.221. This page is the exchange-facing portal version of the package: metadata, address handling, deposits, withdrawals, finality, archive expectations, operations contacts, and validation gates are documented here directly. GitHub remains the immutable source and audit trail.

Testnet Package

The current exchange package is for native LICN testing on lichen-testnet-1. It is intended for exchange engineering, wallet/custody integration, deposit/withdrawal rehearsal, archive/history verification, and reconciliation testing before mainnet launch.

Exchange Chain Metadata

Addressing And Accounting

prefilter: ^[1-9A-HJ-NP-Za-km-z]{32,44}$

valid_native_address(address):
    if not matches(address, "^[1-9A-HJ-NP-Za-km-z]{32,44}$"):
        return false
    decoded = base58_decode(address)
    return len(decoded) == 32

Deposit Cookbook

The recommended model is one native Lichen address per exchange user or account allocation. Native LICN base transfers do not require a memo or tag. If pooled deposit addresses are used, user attribution is an exchange-owned off-chain ledger responsibility.

1. Generate or allocate a native account for the user.
2. Persist the user-to-address assignment before displaying the address.
3. Poll getTransactionsByAddress for the deposit address; WebSocket slot events may wake the poller but do not replace archive-backed reconciliation.
4. Fetch every candidate transaction with getTransaction.
5. Confirm that the transaction transfers native LICN to the assigned address.
6. Require confirmation_status = "finalized" plus the configured operational buffer.
7. Credit raw spores exactly once using the transaction hash and credited account as the idempotency key.
8. Reconcile address balance, credited deposits, pending sweeps, and hot/cold balances.

Withdrawal Cookbook

Use a cold wallet for the majority reserve, a limited hot wallet for normal withdrawals, and deposit wallets that sweep according to the exchange custody policy.

1. Validate the destination as a native Base58 address decoding to exactly 32 bytes.
2. Convert the requested withdrawal amount to spores before transaction construction.
3. Check hot-wallet spendable balance in spores.
4. Build and sign a native transfer transaction with the target native chain ID.
5. Submit through canonical sendTransaction.
6. Persist the returned native transaction hash before any retry.
7. Poll getTransaction until finalized plus buffer.
8. Mark the withdrawal complete once, then reconcile the hot wallet, ledger, and fee spend.

Finality And Archive

Canonical JSON-RPC Cookbook

All examples use the canonical JSON-RPC route at / and public testnet endpoint.

curl -s https://testnet-api.lichen.network \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot","params":[{"commitment":"finalized"}]}'

curl -s https://testnet-api.lichen.network \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getFeeConfig","params":[]}'

curl -s https://testnet-api.lichen.network \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBalance","params":["<native_base58_address>"]}'

curl -s https://testnet-api.lichen.network \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":["<tx_hash_hex>"]}'

curl -s https://testnet-api.lichen.network \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getTransactionsByAddress","params":["<native_base58_address>",{"limit":100}]}'

curl -s https://testnet-api.lichen.network \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendTransaction","params":["<base64_signed_native_transaction>"]}'

Operations

Validation Gates

• Keep address validation vectors passing before publishing or changing a regex.
• Keep deterministic finality plus the selected exchange buffer validated on a local three-validator testnet.
• Keep archive-backed getTransaction, getBlock, and address history covered across hot/cold data and restart.
• Keep the deposit, credit, sweep, withdrawal, retry, and reconciliation simulation passing locally.
• Clean up every local stack run and prove validator, custody, faucet, and source-chain mock processes are stopped.
• Keep the public testnet exchange simulation evidence attached to the signed recovery release.
• Keep the published exchange package tag, public developer page, and testnet-scope readiness gate aligned before outreach.
• Do not publish a mainnet package until the mainnet launch exchange handoff and full-scope readiness gate pass.

Mainnet Handoff

Mainnet is not live and is excluded from this exchange package. Before any mainnet exchange package exists, the mainnet launch runbook must close the exchange handoff gate, public mainnet RPC and WebSocket endpoints must pass readiness, archive/history must be verified on mainnet, a dust deposit/withdrawal flow must pass, and the public readiness gate must be rerun with --scope full.

python3 scripts/qa/exchange_public_readiness.py --scope full --status-approved --release-tag-selected

Source And Artifacts

The portal carries the reviewer-facing content directly. The release-tagged GitHub links below are retained as source, checksum, and audit references.