@appliedblockchain/silentdatarollup-ethers-provider-fireblocks 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# Silent Data [Rollup] Providers - Ethers Provider Fireblocks Package
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Prerequisites](#prerequisites)
+- [Integration](#integration)
+  - [Fireblocks Integration](#fireblocks-integration)
+    - [Installing Fireblocks Integration Dependencies](#installing-fireblocks-integration-dependencies)
+    - [Fireblocks Integration Example](#fireblocks-integration-example)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+- [Additional Resources](#additional-resources)
+
+## Introduction
+
+Custom providers for Silent Data [Rollup], compatible with ethers.js for Fireblocks integration.
+
+## Prerequisites
+
+- Node.js (version 18 or higher)
+- npm
+- Basic knowledge of Ethereum and smart contracts
+- Ethers.js v6
+
+## Integration
+
+### Fireblocks Integration
+
+#### Installing Fireblocks Integration Dependencies
+
+```bash
+npm install @appliedblockchain/silentdatarollup-core @appliedblockchain/silentdatarollup-ethers-provider-fireblocks ethers@6 @fireblocks/fireblocks-web3-provider
+```
+
+#### Fireblocks Integration Example
+
+```typescript
+import {
+  ApiBaseUrl,
+  ChainId,
+  FireblocksWeb3Provider,
+} from '@fireblocks/fireblocks-web3-provider'
+import {
+  BaseConfig,
+  SilentDataRollupContract,
+} from '@appliedblockchain/silentdatarollup-core'
+import { SilentDataRollupFireblocksProvider } from '@appliedblockchain/silentdatarollup-ethers-provider-fireblocks'
+
+const RPC_URL = 'SILENT_DATA_ROLLUP_RPC_URL'
+
+const eip1193Provider = new FireblocksWeb3Provider({
+  privateKey: 'FIREBLOCKS_PATH_TO_PRIVATE_KEY',
+  apiKey: 'FIREBLOCKS_API_KEY',
+  vaultAccountIds: 'FIREBLOCKS_VAULT_ACCOUNT_ID',
+  assetId: ASSETS[ChainId.SEPOLIA].assetId,
+  chainId: ChainId.SEPOLIA,
+  apiBaseUrl: ApiBaseUrl.Sandbox, // If using a sandbox workspace
+  rpcUrl: 'SILENT_DATA_ROLLUP_RPC_URL',
+})
+
+const silentdataOptions: BaseConfig = {
+  authSignatureType: SignatureType.EIP712, // Optional, defaults to RAW
+  delegate: true, // Optional, defaults to false
+}
+
+const provider = new SilentDataRollupFireblocksProvider({
+  ethereum: eip1193Provider,
+  silentdataOptions,
+})
+const balance = await provider.getBalance('YOUR_ADDRESS')
+console.log(balance)
+
+const signer = await provider.getSigner()
+const contractAddress = 'YOUR_CONTRACT_ADDRESS'
+const abi = [
+  /* Your contract ABI */
+]
+const methodsToSign = ['balance'] // Contract read calls that require signing
+
+const contract = new SilentDataRollupContract(
+  contractAddress,
+  abi,
+  signer,
+  methodsToSign,
+)
+
+const tokenBalance = await contract.balance('YOUR_ADDRESS')
+console.log(tokenBalance)
+```
+
+**Note:** The SilentDataRollupFireblocksProvider adds an additional namespace on top of the Fireblocks provider for debugging purposes. This namespace is the same as the Fireblocks namespace with an additional `:silentdata-interceptor` suffix. For example, if the Fireblocks namespace is `fireblocks:web3-provider`, the SilentData provider's namespace would be `fireblocks:web3-provider:silentdata-interceptor`.
+
+To enable debugging for the SilentData interceptor, you can set the following environment variable:
+
+```bash
+DEBUG=fireblocks:web3-provider:silentdata-interceptor
+```
+
+This will output debug information specific to the SilentData interceptor, helping you troubleshoot issues related to the Silent Data [Rollup] integration with Fireblocks.
+
+## Troubleshooting
+
+If you encounter any issues, please check the following:
+
+1. Ensure you're using the correct RPC URL for your desired network.
+2. Verify that the Fireblocks configuration is correctly set up and ensure your user and API keys are valid.
+3. Ensure that your token is active on the SilentData AppChains dashboard.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## Additional Resources
+
+- [Silent Data [Rollup] Documentation](https://docs.silentdata.com)
+- [Ethers.js Documentation](https://docs.ethers.org/v6/)
+- [Fireblocks Developer Documentation](https://developers.fireblocks.com/api)
+- [Fireblocks Web3 Provider](https://developers.fireblocks.com/reference/evm-web3-provider)

package/dist/index.d.mts

@@ -0,0 +1,65 @@
+import { BaseConfig } from '@appliedblockchain/silentdatarollup-core';
+import { BrowserProvider, Eip1193Provider, Networkish, BrowserProviderOptions } from 'ethers';
+
+declare const DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR = "fireblocks-web3-provider:silentdata-interceptor";
+
+declare class SilentDataRollupFireblocksProvider extends BrowserProvider {
+    private lastNonce;
+    private ethereum;
+    private network;
+    private _options;
+    private config;
+    private baseProvider;
+    constructor({ ethereum, network, options, config, }: {
+        ethereum: Eip1193Provider;
+        network?: Networkish;
+        options?: BrowserProviderOptions;
+        config?: BaseConfig;
+    });
+    /**
+     * Manages and returns the next available nonce for a given address.
+     *
+     * This method implements a local nonce management system to handle concurrent
+     * transactions and potential network delays. It's necessary because:
+     * 1. Multiple transactions can be initiated before earlier ones are confirmed.
+     * 2. We need to ensure each transaction uses a unique, incrementing nonce.
+     *
+     * The method works by:
+     * - Tracking the last used nonce for each address.
+     * - Comparing it with the current network nonce.
+     * - Always returning a nonce higher than both the network nonce and the last used nonce.
+     *
+     * This approach helps prevent nonce conflicts and ensures transactions can be
+     * sent in rapid succession without waiting for network confirmation.
+     *
+     * @param address - The Ethereum address for which to get the next nonce.
+     * @returns A Promise that resolves to the next available nonce as a number.
+     */
+    private getNextNonce;
+    /**
+     * Custom method to handle transaction creation, signing, and broadcasting.
+     *
+     * This method is necessary because:
+     * 1. When using Fireblocks to sign a transaction with CONTRACT_CALL,
+     *    Fireblocks also broadcasts the transaction to the specified chain
+     *    on the Fireblocks provider configuration.
+     * 2. We need to manually handle the transaction creation process instead of
+     *    delegating everything to Fireblocks, as we need to broadcast it to our
+     *    own nodes.
+     * 3. When populating a transaction (e.g., getting the nonce), we need to make
+     *    requests with auth headers to our RPC.
+     *
+     * This custom implementation allows us to control the entire process,
+     * from transaction creation to signing and broadcasting. It ensures that
+     * the necessary authenticated requests are made when populating the transaction,
+     * and that the final transaction is broadcast to our specific nodes.
+     *
+     * @param payload - The transaction payload to be sent
+     * @returns The transaction hash
+     */
+    sendTransaction(payload: any): Promise<string | null>;
+    private setupInterceptor;
+    clone(): SilentDataRollupFireblocksProvider;
+}
+
+export { DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR, SilentDataRollupFireblocksProvider };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { BaseConfig } from '@appliedblockchain/silentdatarollup-core';
+import { BrowserProvider, Eip1193Provider, Networkish, BrowserProviderOptions } from 'ethers';
+
+declare const DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR = "fireblocks-web3-provider:silentdata-interceptor";
+
+declare class SilentDataRollupFireblocksProvider extends BrowserProvider {
+    private lastNonce;
+    private ethereum;
+    private network;
+    private _options;
+    private config;
+    private baseProvider;
+    constructor({ ethereum, network, options, config, }: {
+        ethereum: Eip1193Provider;
+        network?: Networkish;
+        options?: BrowserProviderOptions;
+        config?: BaseConfig;
+    });
+    /**
+     * Manages and returns the next available nonce for a given address.
+     *
+     * This method implements a local nonce management system to handle concurrent
+     * transactions and potential network delays. It's necessary because:
+     * 1. Multiple transactions can be initiated before earlier ones are confirmed.
+     * 2. We need to ensure each transaction uses a unique, incrementing nonce.
+     *
+     * The method works by:
+     * - Tracking the last used nonce for each address.
+     * - Comparing it with the current network nonce.
+     * - Always returning a nonce higher than both the network nonce and the last used nonce.
+     *
+     * This approach helps prevent nonce conflicts and ensures transactions can be
+     * sent in rapid succession without waiting for network confirmation.
+     *
+     * @param address - The Ethereum address for which to get the next nonce.
+     * @returns A Promise that resolves to the next available nonce as a number.
+     */
+    private getNextNonce;
+    /**
+     * Custom method to handle transaction creation, signing, and broadcasting.
+     *
+     * This method is necessary because:
+     * 1. When using Fireblocks to sign a transaction with CONTRACT_CALL,
+     *    Fireblocks also broadcasts the transaction to the specified chain
+     *    on the Fireblocks provider configuration.
+     * 2. We need to manually handle the transaction creation process instead of
+     *    delegating everything to Fireblocks, as we need to broadcast it to our
+     *    own nodes.
+     * 3. When populating a transaction (e.g., getting the nonce), we need to make
+     *    requests with auth headers to our RPC.
+     *
+     * This custom implementation allows us to control the entire process,
+     * from transaction creation to signing and broadcasting. It ensures that
+     * the necessary authenticated requests are made when populating the transaction,
+     * and that the final transaction is broadcast to our specific nodes.
+     *
+     * @param payload - The transaction payload to be sent
+     * @returns The transaction hash
+     */
+    sendTransaction(payload: any): Promise<string | null>;
+    private setupInterceptor;
+    clone(): SilentDataRollupFireblocksProvider;
+}
+
+export { DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR, SilentDataRollupFireblocksProvider };