@elsoul/erpc-sdk 0.6.0 → 0.8.0

package/README.md

@@ -1,9 +1,10 @@
 # `@elsoul/erpc-sdk`
 
 Official type-safe TypeScript client for [ERPC](https://erpc.global). Use one
-client and one API key for Solana, Ethereum, Avalanche C/P/X chains, price data,
+client and an API key for Solana, Ethereum, Avalanche C/P/X chains, price data,
 indexed data, leader and validator data, analytics, subscriptions, and account
-information.
+information. Caller-owned direct endpoints can be selected for Solana,
+Ethereum, and Avalanche C-Chain JSON-RPC.
 
 ## Install
 
@@ -36,6 +37,265 @@ erpc.close()
 JSON-RPC method calls return pending requests. Call `.send()` to perform the
 network request.
 
+## Direct RPC endpoints (introduced in 0.8.0)
+
+Caller-owned direct endpoint overrides were introduced in `0.8.0` and require
+that package when installed from a registry. The `0.7.0` package does not
+include this API; check the package version badge and the [latest GitHub
+release](https://github.com/elsoul/erpc-sdk/releases/latest) for live
+publication status.
+
+Use a caller-owned endpoint without an eRPC API key by supplying at least one
+chain override. The HTTP URL is the complete JSON-RPC request target, so its
+path and query are preserved:
+
+```ts
+const erpc = createErpcClient({
+  ethereumRpc: {
+    httpUrl: 'https://node.example/customer/path?region=eu',
+  },
+})
+
+const chainId = await erpc.ethereum.rpc.eth_chainId().send()
+```
+
+The configured HTTP URL is treated as the final target. Redirect responses are
+returned as HTTP errors, and no redirected request is made.
+
+Direct HTTP requests use `credentials: 'omit'`, so ambient browser cookies and
+authentication are not sent implicitly. Add authentication explicitly through
+the endpoint's scoped headers when needed.
+
+Provide an independent WebSocket URL and headers when the node requires them:
+
+```ts
+import type { RpcEndpointConfig } from '@elsoul/erpc-sdk'
+
+const ethereumRpc: RpcEndpointConfig = {
+  httpUrl: 'https://node.example/rpc',
+  webSocketUrl: 'wss://node.example/socket',
+  headers: {
+    authorization: 'Bearer node-token',
+  },
+}
+
+const erpc = createErpcClient({
+  ethereumRpc,
+})
+```
+
+`solanaRpc`, `ethereumRpc`, and `avalancheCRpc` select direct Solana, Ethereum,
+and Avalanche C-Chain JSON-RPC transports. Without an API key, non-overridden
+chains and ERPC REST, native, and index services fail locally. The
+`RpcEndpointConfig.headers` field applies to direct HTTP requests only; those
+headers are never sent on WSS connections.
+
+## 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 reviewed DEX catalog and swap exports were introduced in `0.7.0`.
+Unsigned EVM preparation and simulation below were introduced in `0.8.0` and
+require that package.
+
+```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.
+
+The two reviewed EVM pools also support unsigned ERC-20 exact-input
+preparation and RPC simulation:
+
+```ts
+const request = {
+  chainId: DEX_CHAIN_IDS.ethereum,
+  poolDefinitionId: 'pool-0001',
+  inputTokenDeploymentId: tokens.ethereum.WETH,
+  outputTokenDeploymentId: tokens.ethereum.USDC,
+  amountIn: '1000000000000000000',
+  sender: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+  slippageBps: 50,
+  deadline: String(Math.floor(Date.now()/1000)+300),
+}
+
+const prepared = await erpc.swap.prepareExactInputSwap(request)
+
+const simulation = await erpc.swap.simulateExactInputSwap(request)
+```
+
+Preparation performs a fresh quote, validates the reviewed router and wrapped
+native deployment, and returns an immutable chain-bound unsigned transaction
+envelope. It does not create approval calldata, sign, send, or fill wallet
+fields. When a wallet API needs a raw transaction object, explicitly convert
+the envelope, for example:
+
+```ts
+const { chainId: _chainId, kind: _kind, ...walletTransaction } =
+  prepared.transaction
+await wallet.sendTransaction(walletTransaction)
+```
+
+Use the `simulation` result to inspect the canonical allowance and router
+amounts before asking the caller's wallet to manage allowance, signing, or
+broadcasting. The simulation call itself is read-only and uses only the
+configured RPC transport.
+
+## Optional Mayan Swift v2 bridge (introduced in 0.8.0)
+
+The `0.8.0` API adds the Mayan Swift v2 client as an explicit standalone adapter
+for the reviewed
+issued EURC routes between Ethereum and Solana. It is not attached to the
+default `ErpcClient`; construct it separately when the external provider and
+its solver, relayer, and explorer dependencies are acceptable:
+
+```ts
+import {
+  createMayanSwiftV2BridgeClient,
+  TOKEN_CHAIN_IDS,
+} from '@elsoul/erpc-sdk'
+
+const mayan = createMayanSwiftV2BridgeClient({
+  builderEndpoint: 'https://tx-builder.mayan.finance',
+  explorerEndpoint: 'https://explorer-api.mayan.finance/v3',
+  builderApiKey: 'provider-key',
+})
+const quotes = await mayan.quoteExactInput({
+  sourceChainId: TOKEN_CHAIN_IDS.ethereumMainnet,
+  destinationChainId: TOKEN_CHAIN_IDS.solanaMainnet,
+  sourceTokenDeploymentId: 'deployment-0011',
+  destinationTokenDeploymentId: 'deployment-0013',
+  amountIn: '1000000',
+  slippageBps: 50,
+})
+```
+
+The adapter posts the exact route request to Mayan's `/quote`, preserves the
+provider-signed quote text, and can build a structurally checked unsigned
+source transaction with `buildUnsigned`. It does not verify the provider
+signature locally or prove settlement, and it does not sign, approve, submit,
+refund, or broadcast transactions. For an EVM build, convert the returned
+chain-bound envelope before passing fields to a wallet API:
+
+```ts
+const built = await mayan.buildUnsigned({
+  quote: quotes[0],
+  swapperAddress: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  destinationAddress: '11111111111111111111111111111111',
+})
+if (built.transaction.kind === 'evm-unsigned-transaction') {
+  const { chainId: _chainId, kind: _kind, ...walletTransaction } =
+    built.transaction
+  await wallet.sendTransaction(walletTransaction)
+}
+```
+
+`builderEndpoint` and `explorerEndpoint` default to
+`https://tx-builder.mayan.finance` and `https://explorer-api.mayan.finance/v3`;
+set them to caller-approved base URLs to customize the provider endpoints.
+`getStatus` reads the indexed status endpoint and reports the provider assertion
+as unverified local settlement state. `builderApiKey` is a separate Mayan
+build-only key sent only to `/build`; quote and status calls do not receive it,
+and no eRPC credential is forwarded.
+
 ## Namespaces
 
 | Namespace | Purpose |
@@ -141,6 +401,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)