@elsoul/erpc-sdk 0.7.0 → 0.8.1

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,59 @@ 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
@@ -100,9 +154,9 @@ 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.
+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 {
@@ -147,6 +201,101 @@ 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 |