@elsoul/erpc-sdk 0.8.1 → 0.9.1

package/LICENSE

@@ -2,6 +2,59 @@ 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.
+
+-------------------------------------------------------------------------------
+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.
+
+-------------------------------------------------------------------------------
+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

package/README.md

@@ -1,20 +1,28 @@
 # `@elsoul/erpc-sdk`
 
 Official type-safe TypeScript client for [ERPC](https://erpc.global). Use one
-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. Caller-owned direct endpoints can be selected for Solana,
-Ethereum, and Avalanche C-Chain JSON-RPC.
+client and an API key for Base, Solana, Ethereum, Avalanche C/P/X chains, price
+data, indexed data, leader and validator data, analytics, subscriptions, and
+account information. Base is exposed as a read-only JSON-RPC facade; caller-owned
+direct endpoints can be selected for Base, Solana, Ethereum, and Avalanche
+C-Chain JSON-RPC.
+
+The Base facade documented below has been available since `0.9.0`. This
+source/release cohort targets `0.9.1`; check the
+[npm registry versions](https://registry.npmjs.org/%40elsoul%2Ferpc-sdk) for
+current package availability.
 
 ## Install
 
 ```bash
-npm install @elsoul/erpc-sdk
-# or: pnpm add @elsoul/erpc-sdk
+# After the npm registry lists 0.9.1:
+npm install @elsoul/erpc-sdk@0.9.1
+# or: pnpm add @elsoul/erpc-sdk@0.9.1
+# For local validation, use the public 0.9.0 package or this source checkout.
 ```
 
-The package has no runtime dependencies and includes ESM, CommonJS, and
-TypeScript declarations. Node.js 20 or later is supported.
+The package includes its ESM, CommonJS, and TypeScript declarations. Node.js 20
+or later is supported.
 
 ## Quick start
 
@@ -29,8 +37,9 @@ const erpc = createErpcClient({ apiKey })
 const slot = await erpc.solana.rpc.getSlot().send()
 const chainId = await erpc.ethereum.rpc.eth_chainId().send()
 const avalancheChainId = await erpc.avalanche.rpc.eth_chainId().send()
+const baseChainId = await erpc.base.rpc.eth_chainId().send()
 
-console.log({ slot, chainId, avalancheChainId })
+console.log({ slot, chainId, avalancheChainId, baseChainId })
 erpc.close()
 ```
 
@@ -62,6 +71,10 @@ 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.
 
+For direct HTTP transports, the public `endpoint` property is diagnostic
+metadata containing only the origin/root. The private request target still
+preserves the configured path, query order, and percent encoding exactly.
+
 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.
@@ -84,12 +97,108 @@ const erpc = createErpcClient({
 })
 ```
 
-`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
+`solanaRpc`, `ethereumRpc`, `avalancheCRpc`, and `baseRpc` select direct Solana,
+Ethereum, Avalanche C-Chain, and Base JSON-RPC transports. `baseRpc` accepts
+only an HTTP URL and scoped HTTP headers because the Base facade has no
+WebSocket or subscription surface. 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.
 
+## Base read-only RPC (available since `0.9.0`)
+
+The `0.9.0` API-key client uses `https://base.erpc.global/` at the root JSON-RPC
+path.
+The first check for a Base connection should be `eth_chainId()` and must return
+`0x2105` (Base mainnet). The following uses the catalog's Base EURC record and
+formats the raw response with integer arithmetic:
+
+```ts
+import {
+  createErpcClient,
+  getTokenDeployment,
+  tokens,
+} from '@elsoul/erpc-sdk'
+
+const erpc = createErpcClient({ apiKey: process.env.ERPC_API_KEY! })
+const wallet = '0x7A5837f5bB52C53e08fcFf214c2Cd11daa8EF9EE'
+const eurc = getTokenDeployment(tokens.base.EURC)
+if (eurc?.address === null || eurc === undefined) {
+  throw new Error('Base EURC is missing from the catalog')
+}
+
+const chainId = await erpc.base.rpc.eth_chainId().send()
+if (chainId !== '0x2105') throw new Error(`Unexpected Base chain: ${chainId}`)
+
+const nativeWei = BigInt(
+  await erpc.base.rpc.eth_getBalance(wallet, '0x3167564').send(),
+)
+const calldata = `0x70a08231${wallet.slice(2).padStart(64, '0')}`
+const eurcAtomic = BigInt(
+  await erpc.base.rpc.eth_call(
+    { to: eurc.address, data: calldata },
+    '0x3167564',
+  ).send(),
+)
+
+const formatUnits = (value: bigint, decimals: number): string => {
+  const scale = 10n ** BigInt(decimals)
+  const whole = value / scale
+  const fraction = (value % scale).toString().padStart(decimals, '0').replace(/0+$/u, '')
+  return fraction.length === 0 ? whole.toString() : `${whole}.${fraction}`
+}
+
+const eurcDisplay = formatUnits(eurcAtomic, eurc.decimals)
+// Pinned review read: eurcAtomic === 5_500_000n and eurcDisplay === '5.5'.
+console.log({ chainId, nativeWei, eurcAtomic, eurcDecimals: eurc.decimals, eurcDisplay })
+erpc.close()
+```
+
+For a keyless caller-owned endpoint, use `baseRpc`. Its URL path and query are
+sent exactly as configured, and its headers stay scoped to Base:
+
+```ts
+const erpc = createErpcClient({
+  baseRpc: {
+    httpUrl: process.env.ERPC_BASE_RPC_URL!,
+    headers: { authorization: 'Bearer node-token' },
+  },
+})
+
+const chainId = await erpc.base.rpc.eth_chainId().send()
+```
+
+The Base client exposes only `rpc`; the inner read-only facade has exactly
+`endpoint`, `eth_chainId`, `eth_getBalance`, and `eth_call`. It does not provide
+raw, batch, subscription, signing, or broadcast methods. `baseEndpoint` forwards
+the main API key and global headers, so use it only for a caller-trusted,
+eRPC-compatible host. `baseRpc` takes precedence over it and over global
+headers; it sends only credentials explicitly scoped inside the direct override.
+
+## Wallets, signing, and broadcast
+
+`ErpcClient` has no wallet, private-key, or signer configuration. Swap
+preparation and Mayan `buildUnsigned` return unsigned transaction envelopes;
+the caller owns account selection, allowance changes, nonce and fee policy,
+transaction review, key custody, signing, broadcast, and confirmation. The
+`from`, `sender`, `swapperAddress`, and `feePayer` fields are public identity
+checks, not signing authority. A pending RPC request's `.send()` performs the
+network request and does not sign bytes.
+
+| Concern | Owner |
+| --- | --- |
+| Key or hardware-wallet custody | Caller application or wallet provider |
+| Transaction and allowance review | Caller application and user |
+| Cryptographic signing | External wallet or signer |
+| Signed-byte broadcast | Caller-selected ERPC RPC method |
+| Confirmation and settlement interpretation | Caller application |
+
+See the [shared wallet and signing model](https://github.com/elsoul/erpc-sdk/blob/main/README.md#wallets-and-signing)
+and the [TypeScript signing and broadcast guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/signing-and-broadcast.md)
+for initialized ethers 6 and `@solana/web3.js` 1.x examples. The guide keeps
+the selected RPC URL identical for network checks and sends signed bytes only
+through ERPC.
+
 ## Offline token catalog
 
 The token catalog is bundled with the package, so lookups do not need an
@@ -225,27 +334,22 @@ 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)
-```
+fields. Review `prepared.transaction`, then pass the typed envelope to an
+external signer and the ERPC-only broadcast helper in the
+[TypeScript signing and broadcast guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/signing-and-broadcast.md).
 
 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)
+## Optional Mayan Swift v2 bridge
 
-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:
+The published `0.8.1` API provides 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 {
@@ -256,7 +360,6 @@ import {
 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,
@@ -268,25 +371,19 @@ const quotes = await mayan.quoteExactInput({
 })
 ```
 
+This keyless quote example reflects the provider's documented optional-key
+policy. `buildUnsigned` has a separate SDK guard: supply a caller-managed
+`builderApiKey` in a build client, or explicitly set
+`allowUnauthenticatedBuild: true` to permit a keyless attempt. The opt-in does
+not override provider authentication.
+
 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)
-}
-```
+refund, or broadcast transactions. Pass its typed unsigned envelope to an
+external signer only after review; the signing and ERPC-only broadcast flow is
+shown in the [TypeScript signing and broadcast guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/signing-and-broadcast.md).
 
 `builderEndpoint` and `explorerEndpoint` default to
 `https://tx-builder.mayan.finance` and `https://explorer-api.mayan.finance/v3`;
@@ -296,6 +393,67 @@ 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.
 
+Mayan authentication has three separate layers:
+
+| Layer | Behavior |
+| --- | --- |
+| Mayan documentation | The quote and transaction-builder documents describe the service key as optional. |
+| SDK policy | `buildUnsigned` requires `builderApiKey` by default; `allowUnauthenticatedBuild: true` only permits the caller's keyless HTTP attempt. |
+| Dated hosted observation | On 2026-09-17, four EURC/USDC quotes returned HTTP 200 without keys; default builds made no request, while explicit keyless `/build` attempts returned HTTP 401. This is bounded evidence, not a permanent provider requirement. |
+
+The public `0.9.0` package supports the reviewed issued EURC directions and
+native USDC direct routes. Native USDC uses Mayan's direct SWIFT route and does
+not add Jupiter or another hosted source-swap dependency.
+
+The `0.8.1` maintenance patch updated the Workers fetch invocation boundary;
+it did not include the native USDC or local unsigned-builder paths that are
+present in the public `0.9.0` package.
+
+### Local unsigned construction
+
+The public `0.9.0` package exposes an explicit keyless construction path for
+the reviewed EURC and native USDC directions. Pass a hosted normalized quote
+and a fresh public 16-byte `orderNonce` to `prepareSourceSwap`, then pass its
+plan to `buildLocalUnsigned`:
+
+```ts
+const localClient = createMayanSwiftV2BridgeClient({
+  localBuild: {
+    sourceSwapEndpoint: 'https://price-api.mayan.finance/v3',
+    ethereumRpc: { httpUrl: 'https://your-ethereum-rpc.example' },
+    solanaRpc: { httpUrl: 'https://your-solana-rpc.example' },
+  },
+})
+
+const context = {
+  quote: quotes[0],
+  swapperAddress: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  destinationAddress: 'HQhyrHjgq5ftgsibxdUwLvDZ5HT4c9bNuBWJMmZvTd5b',
+  orderNonce: '0x00112233445566778899aabbccddeeff',
+}
+const sourceSwapPlan = await localClient.prepareSourceSwap(context)
+const unsigned = await localClient.buildLocalUnsigned({
+  ...context,
+  sourceSwapPlan,
+})
+```
+
+`buildLocalUnsigned` requires the explicitly configured source RPC matching the
+source chain. It performs bounded read-only identity and byte preflight, keeps
+the original quote unchanged, and returns an unsigned EVM or Solana envelope.
+Local source-swap requests are anonymous and use no Mayan builder key; direct
+USDC uses `{ kind: 'none' }` and makes no source-swap request. There is no
+fallback to hosted `/build`, and the local path never creates keys, approves,
+signs, submits, broadcasts, or claims settlement. The caller owns wallet
+custody and all signing and ERPC broadcast steps described in the
+[TypeScript signing and broadcast guide](https://github.com/elsoul/erpc-sdk/blob/main/packages/typescript/docs/signing-and-broadcast.md).
+
+These local methods and native USDC routes are included in the public `0.9.0`
+baseline and the source/release cohort targets `0.9.1`. The bridge API remains
+an explicit standalone EURC/native-USDC adapter with optional external provider
+dependencies and configured source-RPC requirements, while normal swaps
+continue to use configured RPC and local logic.
+
 ## Namespaces
 
 | Namespace | Purpose |
@@ -385,7 +543,7 @@ const monthlyUsage = await cloud.usage.getMonthlyApiKeyUsage()
 
 Catalog, credit, and resource results are projected onto documented public
 fields. Interactive login and operating-system keychain storage belong to
-`@elsoul/erpc-cli`.
+the ERPC command-line client.
 
 ## Raw methods