erpc-sdk 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4152582a8b2cdb14a5b98a90761f07abf0ab2313540e5f46cef71d0111a6c531
-  data.tar.gz: 6f8d52e59d11fe4aa9d7d81af2941c65e59adfb98b5bade3a478f25c91d2bc52
+  metadata.gz: e1e41b728c27ddf8d794aa91d44a2503204b00f6953580d0db2498d44a5b041b
+  data.tar.gz: 5dc759af0fe505cd30f6fb45cf43344687d2df1f7aff34cb4b66b8e787419e8b
 SHA512:
-  metadata.gz: 8f14e31048992941c30e753cf0ad84e066063ec667b66d5718c4d442acf2e5e1202b9bb7d70c391f720f32554cb518cde25de19c0166da4c2722cbe2ac66b0bf
-  data.tar.gz: '094c74f0c2939dab9312171da51889a121b8a1f6baed947bc11942ebde119211373f785abf5d8d81b8b1f9cf4818e3b2b8d6bedfe9ace572a7ce6beab765b73a'
+  metadata.gz: 982fb52b52b3e88855eb4405aece06bf5f76518202cd990458ae9955b1796b4756cd61db2373b86072e75db60f4371d9674a4d7b4e927b7deba898a47130bc26
+  data.tar.gz: d174e090167c4a1b45a2b35f7d19dacffad5e57b5d8842fbf9335c9c4354f4df7df9c08fa83665ec9f97376f60fc4678696ac39f0e54f5499b664b9333146bed

data/README.md

@@ -28,11 +28,256 @@ ensure
 end
 ```
 
+## Dedicated RPC endpoints (introduced in 0.8.0)
+
+Supply a full HTTP(S) JSON-RPC URL to use a customer-owned node without an
+eRPC API key. The URL path and query are sent exactly as provided. Direct URLs
+are final HTTP request targets; the Ruby adapter does not follow redirects.
+Caller-owned direct endpoint overrides were introduced in `0.8.0` and require
+that gem version when installed from a registry. The published `0.7.0` gem does
+not include them; check the package version badge and the [latest GitHub
+release](https://github.com/elsoul/erpc-sdk/releases/latest) for live
+publication status.
+
+```ruby
+config = ERPC::ClientConfig.new(
+  ethereum_rpc: ERPC::RpcEndpointConfig.new(
+    http_url: "https://node.example/rpc/customer?token=..."
+  )
+)
+erpc = ERPC::Client.new(config)
+```
+
+An independent WebSocket URL enables subscriptions. Scoped headers apply to
+direct HTTP requests for that RPC endpoint.
+
+```ruby
+config = ERPC::ClientConfig.new(
+  ethereum_rpc: ERPC::RpcEndpointConfig.new(
+    http_url: "https://node.example/rpc",
+    websocket_url: "wss://ws.example/socket?token=...",
+    headers: { "authorization" => "Bearer node-token" }
+  )
+)
+```
+
+## Offline token catalog
+
+The gem bundles a generated token catalog for Ethereum, Solana, and Avalanche
+C-Chain. Lookups are synchronous and offline: they do not need a client, API
+key, registry checkout, JSON parsing, or network access.
+
+```ruby
+require "erpc_sdk"
+
+ethereum_usdc = ERPC::TokenCatalog.find_token_deployments_by_symbol(
+  ERPC::TokenChainIDs::ETHEREUM_MAINNET,
+  "USDC"
+).first
+native_sol = ERPC::TokenCatalog.get_native_token_deployment(
+  ERPC::TokenChainIDs::SOLANA_MAINNET
+)
+
+puts ethereum_usdc.fetch(:decimals) # 6
+puts native_sol.fetch(:symbol)      # SOL
+puts ERPC::Tokens::Ethereum.fetch(:USDC) # opaque deployment ID
+```
+
+Deployment records include their flattened asset identity, chain ID, symbol,
+decimals, standard, address, lifecycle status, and replacement reference. Use
+`list_token_deployments(chain_id: ..., stable_currency: ...)` to filter while
+keeping legacy, winding-down, and retired records visible. The canonical
+registry and its evidence are documented in the [token catalog registry
+README](https://github.com/elsoul/erpc-sdk/blob/main/registry/README.md).
+
+## Offline token rankings
+
+The gem also bundles the generated token-ranking snapshot. Ranking metadata
+uses the exact `schema_version`, `metric`, `as_of`, `content_digest`,
+`status`, `coverage`, and `source_ids` fields from the registry, and all
+nested values are frozen. Read the bundled metadata for the current `status`,
+`metric`, `as_of`, `content_digest`, and `coverage` before presenting a result
+as current; the metadata is the source of truth for whether rows are available
+and how much coverage they represent.
+
+```ruby
+rankings = ERPC::TokenRankings.list_token_rankings(
+  ERPC::TokenChainIDs::ETHEREUM_MAINNET
+)
+puts ERPC::TokenRankings::TOKEN_RANKINGS_METADATA.fetch(:status)
+puts rankings.length
+```
+
+`list_token_rankings` matches the complete chain ID exactly. Empty, unknown,
+and special strings return the same frozen empty array. It never performs
+network I/O, reads the current clock, or filters by observation time.
+
+When a reviewed snapshot is populated, the approved native metric represents
+total supply multiplied by the direct native-pool price. It does not represent
+circulating market capitalization. Coverage remains explicit in metadata and
+may be `partial`; unavailable observations stay out of ranked rows rather than
+being treated as zero.
+
+## Offline DEX and pool catalog
+
+The source tree bundles the generated DEX deployment, pool, and native/wrapped
+token catalog. These lookups are synchronous and offline, and the returned
+records are frozen. The published `0.7.0` gem includes these DEX and swap
+exports.
+
+```ruby
+pool = ERPC::DexCatalog.get_pool_definition("pool-0001")
+puts pool.fetch(:address)
+puts ERPC::Dexes::Ethereum.fetch(:UNISWAP_V2)
+puts ERPC::Pools::AvalancheC.fetch(:LFJ_LEGACY_WAVAX_USDC)
+
+matches = ERPC::DexCatalog.find_pool_definitions_by_pair(
+  ERPC::DexChainIDs::SOLANA_MAINNET,
+  "deployment-0013",
+  "deployment-0006"
+)
+```
+
+The catalog currently contains Uniswap V2 on Ethereum and LFJ legacy
+constant-product on Avalanche C-Chain, plus lookup-only Orca Whirlpools and
+Raydium CLMM records on Solana. Pair lookup is unordered and returns stable
+pool-ID order. `get_native_wrap_definition` accepts a native token deployment
+ID and returns its chain-bound wrapped deployment.
+
+## RPC-only swap quotes
+
+`erpc.swap.quote_exact_input` performs an exact-input quote for the two EVM
+constant-product pools through the client's configured RPC transports. It
+reads the factory, pool, reserves, and block snapshot using the EIP-1898 block
+hash selector, validates the final headers, and computes the result locally.
+Amounts and block quantities are decimal strings; no hosted aggregator or
+additional API is required.
+
+```ruby
+quote = erpc.swap.quote_exact_input(
+  chainId: ERPC::DexChainIDs::ETHEREUM_MAINNET,
+  poolDefinitionId: ERPC::Pools::Ethereum.fetch(:UNISWAP_V2_USDC_WETH),
+  inputTokenDeploymentId: ERPC::Tokens::Ethereum.fetch(:WETH),
+  outputTokenDeploymentId: ERPC::Tokens::Ethereum.fetch(:USDC),
+  amountIn: "1000000000000000000"
+)
+
+puts quote.fetch("amountOut")
+```
+
+`SwapQuoteError#code` exposes deterministic validation codes such as
+`SWAP_STATE_STALE` and `SWAP_UNSUPPORTED_ADAPTER`. Existing transport,
+timeout, and JSON-RPC errors retain their native class. Solana pool records
+are available for lookup; their CLMM adapters are not yet quote-enabled.
+Quote eligibility is a reviewed handwritten boundary for the exact WETH/USDC
+Uniswap V2 tuple on Ethereum and WAVAX/USDC LFJ legacy tuple on Avalanche,
+including chain, pool, factory, token addresses, decimals, ERC-20 standards,
+adapter, and fee fields. New catalog records do not automatically become
+quote-enabled; an otherwise valid request outside those tuples returns
+`SWAP_UNSUPPORTED_TOKEN` before RPC.
+Transaction building, signing, sending, route search, native wrapping, and
+cross-chain bridging are outside this quote API.
+
+## Unsigned swap preparation and simulation
+
+For the reviewed Ethereum Uniswap V2 and Avalanche LFJ V1 pools, the client
+can prepare an unsigned ERC-20-to-ERC-20 router call and simulate it against a
+fresh RPC snapshot. The methods use the selected dedicated chain transport
+when one is configured.
+
+```ruby
+request = {
+  chainId: ERPC::DexChainIDs::ETHEREUM_MAINNET,
+  poolDefinitionId: ERPC::Pools::Ethereum.fetch(:UNISWAP_V2_USDC_WETH),
+  inputTokenDeploymentId: ERPC::Tokens::Ethereum.fetch(:WETH),
+  outputTokenDeploymentId: ERPC::Tokens::Ethereum.fetch(:USDC),
+  amountIn: "1000000000000000000",
+  sender: "0x1111111111111111111111111111111111111111",
+  recipient: "0x2222222222222222222222222222222222222222",
+  slippageBps: 50,
+  deadline: (Time.now.to_i+300).to_s
+}
+
+preparation = erpc.swap.prepare_exact_input_swap(request)
+simulation = erpc.swap.simulate_exact_input_swap(request)
+puts preparation.fetch("minimumAmountOut")
+puts simulation.fetch("amountOut")
+```
+
+The preparation contains a chain-bound transaction envelope. Convert its
+fields to the wallet library's native request type and convert the CAIP-2
+`chainId` separately when that library expects a numeric network ID:
+
+```ruby
+envelope = preparation.fetch("transaction")
+wallet_request = {
+  chain_id: Integer(envelope.fetch("chainId").delete_prefix("eip155:")),
+  from: envelope.fetch("from"),
+  to: envelope.fetch("to"),
+  data: envelope.fetch("data"),
+  value: envelope.fetch("value")
+}
+```
+
+The SDK never creates approval calldata, changes allowances, signs, or sends
+the envelope. Simulation checks the input-token allowance before calling the
+router and validates the returned amounts. `SwapExecutionError#code` exposes
+stable execution codes such as `SWAP_INSUFFICIENT_ALLOWANCE`,
+`SWAP_SIMULATION_REVERTED`, and `SWAP_INVALID_SIMULATION`; transport and
+non-revert JSON-RPC errors retain their native classes.
+
 Both exact wire names (`getSlot`, `eth_chainId`) and idiomatic snake-case
 aliases (`get_slot`, `eth_chain_id`) create inert requests. Network I/O starts
 only when `send` is called. `request` restricts calls to the namespace catalog;
 `raw` is the forward-compatible escape hatch.
 
+For Solana v1 transactions, pass numeric `maxSupportedTransactionVersion` in
+the request options for `get_transaction` and `get_block`. Responses remain
+opaque Ruby hashes: v1 values include `transaction.message.transactionConfig`,
+legacy and v0 values omit that field, and unrelated response fields are
+preserved. For serialized transactions larger than 1232 bytes, pass the exact
+base64 payload with `"encoding" => "base64"` to `send_transaction` or
+`simulate_transaction`; the SDK forwards the request and response unchanged.
+See the [Solana v1 guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/solana-v1.md).
+
+## Optional Mayan Swift v2 bridge (introduced in 0.8.0)
+
+The `0.8.0` API's `MayanSwiftV2BridgeClient` is an explicit standalone adapter for the reviewed
+issued EURC routes between Ethereum mainnet and Solana mainnet. It does not
+attach to `ERPC::Client`, inherit eRPC credentials or headers, or make any
+request during construction. Configure the Mayan builder and Explorer
+endpoints separately when needed:
+
+```ruby
+bridge = ERPC::MayanSwiftV2BridgeClient.new(
+  builder_endpoint: "https://tx-builder.mayan.finance",
+  explorer_endpoint: "https://explorer-api.mayan.finance/v3",
+  builder_api_key: ENV.fetch("MAYAN_BUILDER_API_KEY"),
+  http_adapter: ERPC::NetHttpAdapter.new
+)
+
+quotes = bridge.quote_exact_input(
+  "sourceChainId" => ERPC::TokenChainIDs::ETHEREUM_MAINNET,
+  "destinationChainId" => ERPC::TokenChainIDs::SOLANA_MAINNET,
+  "sourceTokenDeploymentId" => "deployment-0011",
+  "destinationTokenDeploymentId" => "deployment-0013",
+  "amountIn" => "100000000",
+  "slippageBps" => 50
+)
+```
+
+The adapter exposes `quote_exact_input`, `build_unsigned`, and `get_status`.
+Builds return unsigned, structurally checked provider transactions and an
+Ethereum allowance description; the SDK does not approve, sign, broadcast,
+submit, cancel, refund, or claim settlement verification. Provider source
+swaps use Mayan's disclosed internal USDC path (and Jupiter v6 for Solana
+source orders), so this optional adapter is separate from the SDK's configured
+RPC-only swap helpers. The defaults are `https://tx-builder.mayan.finance` for
+quote/build and `https://explorer-api.mayan.finance/v3` for indexed status; set
+`builder_endpoint` and `explorer_endpoint` to customize them. The
+`builder_api_key` is a separate Mayan build-only key and is never an eRPC
+credential. `BridgeError#code` provides stable secret-free errors.
+
 ## Namespaces
 
 | Namespace | Purpose |