@elsoul/erpc-sdk 0.6.0 → 0.7.0

package/README.md

@@ -36,6 +36,117 @@ erpc.close()
 JSON-RPC method calls return pending requests. Call `.send()` to perform the
 network request.
 
+## Offline token catalog
+
+The token catalog is bundled with the package, so lookups do not need an
+`ErpcClient`, API key, or network request. Deployment IDs are opaque and the
+chain aliases expose those IDs directly:
+
+```ts
+import {
+  TOKEN_CHAIN_IDS,
+  findTokenDeploymentsBySymbol,
+  listTokenDeployments,
+  tokens,
+} from '@elsoul/erpc-sdk'
+
+const usdcByChain = {
+  ethereum: findTokenDeploymentsBySymbol(
+    TOKEN_CHAIN_IDS.ethereumMainnet,
+    'USDC',
+  ),
+  solana: findTokenDeploymentsBySymbol(TOKEN_CHAIN_IDS.solanaMainnet, 'USDC'),
+  avalancheC: findTokenDeploymentsBySymbol(
+    TOKEN_CHAIN_IDS.avalancheCMainnet,
+    'USDC',
+  ),
+}
+
+const canonicalEthereumUsdcId = tokens.ethereum.USDC
+const usdDeployments = listTokenDeployments({ stableCurrency: 'USD' })
+```
+
+The result includes every matching deployment and its status, decimals,
+standard, address, and flattened asset metadata. See the
+[canonical registry guide](https://github.com/elsoul/erpc-sdk/blob/main/registry/README.md)
+for the source data and ID policy.
+
+## Offline token rankings
+
+Ranking data is bundled as an immutable snapshot and is available without an
+API key or network request:
+
+```ts
+import {
+  TOKEN_CHAIN_IDS,
+  TOKEN_RANKINGS_METADATA,
+  listTokenRankings,
+} from '@elsoul/erpc-sdk'
+
+const ethereumRankings = listTokenRankings(TOKEN_CHAIN_IDS.ethereumMainnet)
+console.log({ status: TOKEN_RANKINGS_METADATA.status, ethereumRankings })
+```
+
+Rows use the reviewed ranking metric recorded in
+`TOKEN_RANKINGS_METADATA`. For the native total-supply-value metric, values are
+exact rational values in atomic native units. The snapshot can be unconfigured
+or partial, has no current-time filtering, and does not fetch live prices or
+supply data; check its metadata before presenting a ranking as current.
+
+## Offline DEX and pool catalog
+
+DEX deployments, pool addresses, native/wrapped relationships, and
+chain-qualified aliases are bundled as generated data. These lookups are
+offline and use opaque IDs, so an Ethereum USDC address cannot be confused
+with an Avalanche or Solana deployment:
+
+The published package baseline is currently `0.6.0`. The DEX catalog and swap
+exports described below are in the source tree for the unreleased `0.7.0`
+line and are not part of published `0.6.0` packages yet.
+
+```ts
+import {
+  DEX_CHAIN_IDS,
+  dexes,
+  findPoolDefinitionsByPair,
+  getNativeWrapDefinition,
+  pools,
+  tokens,
+} from '@elsoul/erpc-sdk'
+
+const ethereumPools = findPoolDefinitionsByPair(
+  DEX_CHAIN_IDS.ethereum,
+  tokens.ethereum.WETH,
+  tokens.ethereum.USDC,
+)
+const uniswap = dexes.ethereum.UNISWAP_V2
+const weth = getNativeWrapDefinition(tokens.ethereum.ETH)
+const pool = pools.ethereum.UNISWAP_V2_USDC_WETH
+```
+
+The reviewed Ethereum Uniswap V2 and Avalanche LFJ legacy constant-product
+pools support RPC-only exact-input quotes. Solana Orca and Raydium records are
+available for lookup while their CLMM quote adapters are being added. Catalog
+growth adds lookup and monitoring data; it does not implicitly add swap
+eligibility:
+
+```ts
+const quote = await erpc.swap.quoteExactInput({
+  chainId: DEX_CHAIN_IDS.ethereum,
+  poolDefinitionId: pool,
+  inputTokenDeploymentId: tokens.ethereum.WETH,
+  outputTokenDeploymentId: tokens.ethereum.USDC,
+  amountIn: '1000000000000000000',
+})
+
+console.log(quote.amountOut)
+```
+
+Quotes read the configured EVM RPC at one EIP-1898 block snapshot and apply
+the constant-product formula locally. The request does not build, sign,
+simulate, or broadcast a transaction; route selection, slippage, bridging,
+and Solana CLMM execution are separate capabilities.
+
 ## Namespaces
 
 | Namespace | Purpose |
@@ -141,6 +252,7 @@ const result = await erpc.solana.rpc
 ## Documentation
 
 - [Complete guide](https://github.com/elsoul/erpc-sdk#readme)
+- [Solana transaction v1 guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/solana-v1.md)
 - [Method availability](https://github.com/elsoul/erpc-sdk/blob/main/docs/METHODS.md)
 - [Roadmap](https://github.com/elsoul/erpc-sdk/blob/main/ROADMAP.md)
 - [Security policy](https://github.com/elsoul/erpc-sdk/blob/main/SECURITY.md)