erpc-sdk 0.8.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c09be34b5be49350b250f9cf7c879440de8503264c61fbd0d75da963beaf2cb
-  data.tar.gz: 0ee3a441159ce7a6b36183652b8e00e94d83ccc9f889d9f24a0fafa1b76fe9ab
+  metadata.gz: 48fb4d773602547b8b938cc0f5e20f3f46c00b905d20beda739c0ae7b5edcaad
+  data.tar.gz: 581ac31956aa8f63e1d4e3d40808e798aa96a542e9580f0cb452c6c597263339
 SHA512:
-  metadata.gz: a1b216fa77159a6fe15f69ec322af3034d260d76e6f0e9d9e2d0352ad3847674e084fd5010307698bb0e2f184af679ec548c79f4340c9450bf3a4a151838d555
-  data.tar.gz: 0640a3bc0a51a257fd17f6fc62daac00ad98391acaed502a99bbfab739a3e9de6de51d0e7c8853a7725ffbfda9083b9c9e6f195dfe30ab7e836014eb7e076a25
+  metadata.gz: c5a83daf119e875927486500e389a5741bdf3fcc0e502d51fb9a01bad6f7801cdff34c416eef7e08ae4e24be37d5ecc2c6b61521f21b42d70f516378a50119fc
+  data.tar.gz: bc07e411ed03ea21642c485ccbf318a7e4bdca365ba93bb2a013b86cd79af854bcd16614662e7033d291d87d821004e55913c3ac4c0c2aceb53423aaee25a340

data/LICENSE

@@ -2,6 +2,77 @@ MIT License
 
 Copyright (c) 2026 ELSOUL LABO B.V.
 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+Upstream Mayan Finance source notice
+
+The following notice is retained for the local bridge construction boundary
+reviewed from Mayan Finance swap-sdk commit
+c4c98031aaad9264d17630d7b4de0cb18688cf78 (SHA-256:
+a5b74ba954fd256feffa4c25251a0cbbfb7002af43278e3e4e6268a2e8208865).
+Adapted local path: packages/ruby/lib/erpc_sdk/bridge_local.rb. The Ruby
+implementation adds bounded serialization, hashing, validation, and read-only
+transport integration; no signing or custody code is included.
+
+Third-party MIT notice: pinned Mayan source commit
+c4c98031aaad9264d17630d7b4de0cb18688cf78
+(source LICENSE SHA-256: a5b74ba954fd256feffa4c25251a0cbbfb7002af43278e3e4e6268a2e8208865)
+
+The MIT License (MIT)
+Copyright (c) 2022-2026 Mayan Finance
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+Official npm Mayan swap-sdk 15.2.2 oracle notice
+
+The following notice is retained for reference-only vectors from the official
+npm @mayanfinance/swap-sdk 15.2.2 package (SHA-256:
+3333053878e484331d629fb35ba704b0a635f26b9d81d9c5d51ab2d5817f4744).
+Reference-only oracle source: installed package utilities used to freeze
+cross-language vectors; it is not a Ruby runtime dependency.
+
+Third-party MIT notice: npm oracle @mayanfinance/swap-sdk 15.2.2
+(oracle LICENSE SHA-256: 3333053878e484331d629fb35ba704b0a635f26b9d81d9c5d51ab2d5817f4744)
+
+The MIT License (MIT)
+Copyright (c) 2019-2020 Hugo Di Francesco
+
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

data/README.md

@@ -5,10 +5,17 @@ Avalanche C/P/X-chain JSON-RPC, indexed data, analytics, WebSocket subscriptions
 price REST and server-sent events, account usage, and scoped Cloud reads.
 
 ```bash
-gem install erpc-sdk
+# After RubyGems lists 0.9.1:
+gem install erpc-sdk -v 0.9.1
+# For local validation, use the public 0.9.0 gem or this source checkout.
 ```
 
-Ruby 3.1 or newer is required. The gem has no runtime dependencies.
+Ruby 3.1 or newer is required. Local Mayan unsigned construction uses the
+approved native `digest-keccak` 0.0.7 runtime dependency.
+
+This source/release cohort targets `0.9.1`; check the
+[RubyGems release metadata](https://rubygems.org/api/v1/versions/erpc-sdk.json)
+for current package availability.
 
 ## Quick start
 
@@ -242,8 +249,11 @@ See the [Solana v1 guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/
 
 ## 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
+`MayanSwiftV2BridgeClient` is an explicit standalone adapter for the reviewed issued EURC
+routes between Ethereum mainnet and Solana mainnet. The public `0.9.0` gem contains
+the native USDC and local-builder additions alongside EURC. The `0.9.1` package
+also includes these APIs as the source/release cohort target.
+The adapter 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:
@@ -252,17 +262,18 @@ endpoints separately when needed:
 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
+  {
+    "sourceChainId" => ERPC::TokenChainIDs::ETHEREUM_MAINNET,
+    "destinationChainId" => ERPC::TokenChainIDs::SOLANA_MAINNET,
+    "sourceTokenDeploymentId" => "deployment-0011",
+    "destinationTokenDeploymentId" => "deployment-0013",
+    "amountIn" => "100000000",
+    "slippageBps" => 50
+  }
 )
 ```
 
@@ -271,12 +282,104 @@ 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
+source EURC orders), while native USDC uses direct forwarding with no source
+swap or Jupiter dependency. This optional adapter is separate from the SDK's configured
+RPC-only swap helpers. Native USDC Ethereum builds use the reviewed
+`0xe4269fc4` selector. 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.
+`builder_api_key` is build-only and is never sent to quote or Explorer. The
+local default guard can be bypassed with `allow_unauthenticated_build: true` at
+any configured endpoint, including the default endpoint; this only permits a
+request and does not change provider authentication. It is never an eRPC
+credential.
+`BridgeError#code` provides stable secret-free errors.
+
+Select native USDC with its exact deployment IDs:
+
+```ruby
+quotes = bridge.quote_exact_input(
+  {
+    "sourceChainId" => ERPC::TokenChainIDs::ETHEREUM_MAINNET,
+    "destinationChainId" => ERPC::TokenChainIDs::SOLANA_MAINNET,
+    "sourceTokenDeploymentId" => "deployment-0008",
+    "destinationTokenDeploymentId" => "deployment-0010",
+    "amountIn" => "100000000",
+    "slippageBps" => 50
+  }
+)
+```
+
+The public `0.9.0` gem supports the EURC bridge, native USDC, and local-builder
+support. The `0.9.1` package carries these APIs as the source/release cohort target.
+
+### Local unsigned Mayan construction
+
+The source checkout also exposes explicit keyless local construction for the
+four reviewed native EURC and USDC routes. It keeps the hosted quote unchanged,
+fetches the EURC source-swap instructions when required, reads only the
+matching caller-configured source RPC, and returns an unsigned EVM or Solana
+transaction. It never loads keys, signs, approves, submits, or falls back to
+the hosted `/build` endpoint.
+
+```ruby
+bridge = ERPC::MayanSwiftV2BridgeClient.new(
+  local_build: {
+    source_swap_endpoint: "https://price-api.mayan.finance/v3",
+    ethereum_rpc: ERPC::RpcEndpointConfig.new(
+      http_url: "https://ethereum.example/rpc",
+      headers: { "authorization" => "Bearer node-token" }
+    )
+  }
+)
+
+context = {
+  "quote" => quote,
+  "swapperAddress" => "0x1111111111111111111111111111111111111111",
+  "destinationAddress" => "HQhyrHjgq5ftgsibxdUwLvDZ5HT4c9bNuBWJMmZvTd5b",
+  "orderNonce" => "0x00112233445566778899aabbccddeeff"
+}
+plan = bridge.prepare_source_swap(context)
+unsigned = bridge.build_local_unsigned(context.merge("sourceSwapPlan" => plan))
+```
+
+`orderNonce` is caller-supplied public entropy and must be a fresh lowercase
+`0x` plus 32 hexadecimal digits. A local build requires the configured RPC for
+the source chain; RPC headers stay on that RPC request and are never forwarded
+to Mayan. The returned validation fields describe structural construction and
+do not claim provider-signature verification, signing, or settlement.
+
+## Wallets, signing, and Mayan authentication
+
+The Ruby SDK does not load wallet or private-key material and does not sign
+transactions. `sender`, `from`, `swapperAddress`, and `feePayer` are public
+addresses; ERPC API keys, direct-RPC headers, and Mayan service keys authenticate
+services and are not signer keys. Swap preparation and Mayan builds return
+unsigned data. After an application-owned wallet signs it, submit the
+serialized bytes through the selected ERPC RPC method; the SDK performs that
+RPC request and does not perform cryptographic signing. Approval policy, fees,
+nonces or blockhashes, review, and confirmation remain in the caller's wallet
+flow.
+
+See the [common wallet and signing responsibilities](https://github.com/elsoul/erpc-sdk/blob/main/README.md#wallets-and-signing)
+and the [TypeScript examples for signing and broadcast](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/signing-and-broadcast.md)
+for worked external-wallet flows. The TypeScript examples are consumer
+integrations and do not add runtime dependencies to this Ruby gem.
+
+Mayan's [official quote API documentation](https://docs.mayan.finance/integration/quote-api#api-key)
+and the [pinned transaction-builder authentication guidance](https://github.com/mayan-finance/tx-builder/blob/e966f16a155cd9091b02ef5d9b91c3f837c228ad/README.md#authentication)
+describe the provider key as optional. Ruby applies a local safety guard:
+`build_unsigned` requires a separate `builder_api_key` unless the caller
+explicitly sets `allow_unauthenticated_build: true`. That option permits a
+keyless request to the configured or default builder endpoint; it grants no
+permission at the provider. The builder key is sent only to `/build`, never to
+`/quote` or Explorer, and is never reused as an ERPC credential.
+
+In the anonymous recheck at 2026-09-17 11:27 UTC, four EURC/USDC quotes returned
+HTTP 200 and four hosted builder requests returned HTTP 401. This dated
+observation records the current provider discrepancy and does not establish a
+universal or permanent key requirement; the deployed provider revision is
+unknown, and no authenticated build or funds evidence was collected.
 
 ## Namespaces