erpc-sdk 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 317ffd5217863e2d5915a992ef7d997b268ecaaac07f7f34129441d40cbd2521
-  data.tar.gz: 06751bca8e281bf143d2dc80f043d91d8b806c167eebfce826460eeffe5eaf57
+  metadata.gz: e1e41b728c27ddf8d794aa91d44a2503204b00f6953580d0db2498d44a5b041b
+  data.tar.gz: 5dc759af0fe505cd30f6fb45cf43344687d2df1f7aff34cb4b66b8e787419e8b
 SHA512:
-  metadata.gz: ca330578c4e0c8c2055cd7a2dad65b500eec1bcae41d737ba81d570df40cbc6b2fe0245f2db10c48cffa2162fc96fd104c0ae8a733c12aa4dfd4457fa009c110
-  data.tar.gz: 426d7d68e2d89a6d2fca5e5ff3fbf8b84df4988c6324230f6aae19841ab165803f3a5634cbf8139de93f34b189473912e3c8ec7ba0148621fce11dffb5b68681
+  metadata.gz: 982fb52b52b3e88855eb4405aece06bf5f76518202cd990458ae9955b1796b4756cd61db2373b86072e75db60f4371d9674a4d7b4e927b7deba898a47130bc26
+  data.tar.gz: d174e090167c4a1b45a2b35f7d19dacffad5e57b5d8842fbf9335c9c4354f4df7df9c08fa83665ec9f97376f60fc4678696ac39f0e54f5499b664b9333146bed

data/README.md

@@ -28,6 +28,39 @@ 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
@@ -62,9 +95,10 @@ README](https://github.com/elsoul/erpc-sdk/blob/main/registry/README.md).
 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. The current snapshot is intentionally
-`unconfigured`, so its metric and `as_of` are `nil` and each chain lookup is
-empty until a reviewed snapshot is published.
+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(
@@ -88,8 +122,8 @@ being treated as zero.
 
 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.6.0` gem predates these exports; this
-source-tree feature is planned for unreleased `0.7.0`.
+records are frozen. The published `0.7.0` gem includes these DEX and swap
+exports.
 
 ```ruby
 pool = ERPC::DexCatalog.get_pool_definition("pool-0001")
@@ -144,6 +178,54 @@ quote-enabled; an otherwise valid request outside those tuples returns
 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;
@@ -158,6 +240,44 @@ 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 |