npm package: @spicenet-io/spiceflow-core
Description: Single source of truth for chain configs, token lists, logos, ABIs, and shared utilities across spiceflow repos.
Latest version: 0.3.5

# @spicenet-io/spiceflow-core

Single source of truth for chain configs, token lists, logos, ABIs, and shared utilities across spiceflow repos.

## Install

```
npm install @spicenet-io/spiceflow-core
```

## What's in here

### Chains

`CHAINS` is a record of all supported chains keyed by chain ID. Each entry has id, name, display name, network (mainnet/testnet), native currency, delegate contract address, block explorer, rpc url, and logo.

Helper functions: `getChainMeta(chainId)`, `getChainsByNetwork(network)`, `getChainIdsByNetwork(network)`, `getMainnetChains()`, `getTestnetChains()`, `getDelegateContract(chainId)`.

### Tokens

`TOKENS` is the official token list. Each token has symbol, name, equivalence group, logo, and deployments across chains (address, decimals, network per chain).

Helper functions: `getTokensForChain(chainId)`, `getTokenByAddress(address, chainId)`, `getEquivalentAddresses(tokenAddress)`, `areEquivalent(a, b)`, `isUsdDenominated(address)`, `isBtcDenominated(address)`.

### Logos

All chain and token logos are bundled as base64 data URIs in the package. They work directly in img src attributes with no network requests. To add a new logo, drop the PNG in `logos/` and reference it in the chain or token list. `npm run build` auto generates the base64 file.

### Utilities

`isNativeToken(address)` checks if an address is a native token (zero address, 0x0, or 0xeee...eee).

`normalizeNativeTokenAddress(address)` normalizes any native token address to the zero address.

`convertAmountBetweenDecimals(amount, fromDecimals, toDecimals)` converts token amounts between different decimal precisions.

`formatTokenAmount(amount, decimals)` formats a bigint token amount into a human readable string.

`truncateAddress(address)` shortens an address for display.

`withRetry(fn, maxRetries, delayMs)` retries an async function with exponential backoff.

Constants: `NATIVE_TOKEN_ADDRESS`, `ZERO_ADDRESS`, `ESCROW_ADDRESS`.

### ABIs

`DELEGATE_ABI`, `ERC20_ABI`, `WCBTC_ABI`.

### Authorization

`hashChainBatches(chainCalls)` hashes chain call batches for intent signing.

`getIntentHash(signatureType, nbf, exp, chainBatches)` computes the intent hash.

`getAccountNonce(address, publicClient)` gets the account nonce from chain.

### Core SDK

`SpiceFlowCore` class for building and submitting intents. Handles delegation signing, chain batch construction, intent signing, and transaction submission.

### HTTP

`fetchWithRetry(url, init, opts)` is a fetch wrapper with retry and exponential backoff.

`submitTransaction(baseUrl, request)` submits a transaction to the relayer API.

`getIntentStepStatus(txApiUrl, intentId, stepId)` checks intent execution status.

`prepareRFQT(txApiUrl, request)` prepares an RFQT quote.

## Adding a token

1. Drop the logo PNG in `logos/`
2. Add the token entry in `src/tokens/list.ts` with symbol, name, equivalence group, logo reference, and deployments
3. `npm run build` and publish

## Adding a chain

1. Drop the logo PNG in `logos/` if it's a new chain logo
2. Add the chain entry in `src/chains/list.ts`
3. Add token deployments on that chain in `src/tokens/list.ts`
4. `npm run build` and publish