gethstorage-sdk 0.0.0-stage → 5.0.2

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# gethstorage-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This SDK aims to standardize the interaction between applications and the EthStorage network to achieve reliable and
+efficient data management functionality.
+
+This SDK provides the `FlatDirectory` class, a higher-level data management tool that provides methods for uploading
+and downloading data of arbitrary size. Uploads are performed by sending the data through calldata.
+
+Click here to view [spec](./spec.md).
+
+# Installation
+
+Install the SDK using [npm](https://www.npmjs.com/package/gethstorage-sdk):
+
+```bash
+$ npm install gethstorage-sdk
+```
+
+# Example Usage
+
+## FlatDirectory
+
+### create
+
+Create a `FlatDirectory` instance.
+
+```js
+const { FlatDirectory } = require("gethstorage-sdk");
+
+const rpc = "https://rpc.beta.testnet.l2.quarkchain.io:8545";
+const ethStorageRpc = "https://rpc.beta.testnet.l2.ethstorage.io:9596";
+const privateKey = "0xabcd...";
+
+const flatDirectory = await FlatDirectory.create({
+    rpc: rpc,
+    ethStorageRpc: ethStorageRpc,
+    privateKey: privateKey,
+});
+```
+
+If `FlatDirectory` has been deployed, it can be set through the `address` field.
+
+```js
+const address = "0x987..."; // FlatDirectory address
+const flatDirectory = await FlatDirectory.create({
+    rpc: rpc,
+    ethStorageRpc: ethStorageRpc,
+    privateKey: privateKey,
+    address: address,
+});
+```
+
+If you only need the `download` function, you can create a `FlatDirectory` using the following pattern.
+
+```js
+const address = "0x987..."; // FlatDirectory address
+const flatDirectory = await FlatDirectory.create({
+    ethStorageRpc: 'https://rpc.beta.testnet.l2.ethstorage.io:9596',
+    address: address
+});
+```
+
+### deploy
+
+Deploy the implementation
+contract [FlatDirectory](https://github.com/ethstorage/evm-large-storage)
+for [EIP-5018](https://eips.ethereum.org/EIPS/eip-5018) standard.
+
+```js
+const contractAddress = await flatDirectory.deploy();
+console.log(`FlatDirectory address is ${contractAddress}.`);
+```
+
+### upload
+
+Upload `buffer | file` to the FlatDirectory. The content is sliced into chunks and each chunk is sent through calldata.
+
+```js
+const callback = {
+    onProgress: function (progress, count, isChange) {
+        console.log(`Uploaded ${progress} of ${count} chunks`);
+    },
+    onFail: function (err) {
+        console.log(err);
+    },
+    onFinish: function (totalUploadChunks, totalUploadSize, totalCost) {
+        console.log(`Total upload chunk count is ${totalUploadChunks}, size is ${totalUploadSize}, total cost is ${totalCost}`);
+    }
+};
+
+const request = {
+    key: "test.txt",
+    content: Buffer.from("big data"),
+    callback: callback
+}
+await flatDirectory.upload(request);
+```
+
+If you want to use `file`, it can be divided into browser and Node.js.
+
+Browser
+```javascript
+// <input id='fileToUpload' />
+const file = document.getElementById('fileToUpload').files[0];
+
+const request = {
+    key: "test.txt",
+    content: file,
+    callback: callback
+}
+await flatDirectory.upload(request);
+```
+
+Node.js
+```javascript
+const {NodeFile} = require("gethstorage-sdk/file");
+const file = new NodeFile("/usr/download/test.jpg");
+
+const request = {
+    key: "test.txt",
+    content: file,
+    callback: callback
+}
+await flatDirectory.upload(request);
+```
+
+### download
+
+Monitor the download progress by passing in a callback function.
+
+```js
+const key = "test.txt";
+await flatDirectory.download(key, {
+	onProgress: function (progress, count, chunk) {
+		console.log(`Download ${progress} of ${count} chunks, this chunk is ${Buffer.from(chunk).toString()}`);
+	},
+    onFail: function (error) {
+        console.error("Error download data:", error);
+    },
+    onFinish: function () {
+        console.log("Download success.");
+    }
+});
+```
+
+### estimateCost
+
+Estimate gas costs before uploading.
+
+```js
+const request = {
+    key: "example1.txt",
+    content: Buffer.from("large data to upload")
+}
+
+const cost = await flatDirectory.estimateCost(request);
+console.log(`Gas Cost: ${cost.gasCost}, Storage Cost: ${cost.storageCost}`);
+```
+
+Use `file`.
+
+Browser
+```javascript
+// <input id='fileToUpload' />
+const file = document.getElementById('fileToUpload').files[0];
+
+const request = {
+    key: "example1.txt",
+    content: file
+}
+const cost = await flatDirectory.estimateCost(request);
+console.log(`Gas Cost: ${cost.gasCost}, Storage Cost: ${cost.storageCost}`);
+```
+
+Node.js
+```javascript
+const {NodeFile} = require("gethstorage-sdk/file");
+const file = new NodeFile("/usr/download/test.jpg");
+
+const request = {
+    key: "example1.txt",
+    content: file
+}
+const cost = await flatDirectory.estimateCost(request);
+```
+
+
+### Chunk options
+
+Uploads are sliced into calldata chunks. Both `estimateCost` and `upload`
+requests accept two optional fields:
+
+| Field          | Type   | Default | Description                                              |
+|----------------|--------|---------|----------------------------------------------------------|
+| `maxChunkSize` | number | `64`    | data size of each chunk, in KB                            |
+| `maxChunks`    | number | `100`   | maximum number of chunks requested in a single call       |
+
+```js
+const request = {
+    key: "example1.txt",
+    content: Buffer.from("large data to upload"),
+    maxChunkSize: 32, // 32 KB per chunk
+    maxChunks: 120    // at most 120 chunks per request
+}
+await flatDirectory.upload({ ...request, callback });
+```
+
+`fetchHashes(keys, maxChunks)` accepts the same chunk limit as its second argument.

package/dist/browser/index.d.mts

@@ -0,0 +1,288 @@
+import { ethers, Contract } from 'ethers';
+
+declare const FlatDirectoryAbi: readonly string[];
+
+declare const ETHSTORAGE_MAPPING: Record<number, string>;
+/**
+ * On-chain max chunk size passed to the FlatDirectory constructor (uint32 maxChunkSize).
+ */
+declare const CONTRACT_MAX_CHUNK_SIZE: number;
+/**
+ * eth_call consumes gas, so we need to estimate the maximum number of chunks based on a 30 million gas limit.
+ * Additionally, we need to reserve a portion of the gas for the cost of the request parameters (which can vary dynamically).
+ */
+declare const MAX_CHUNKS: number;
+/**
+ * Calldata overhead of a single chunk, i.e. the difference between the chunk size
+ * configured by the user and the actual data size carried by the transaction.
+ */
+declare const CALLDATA_CHUNK_OVERHEAD: number;
+/**
+ * Default size of each data chunk when uploading by calldata, in KB.
+ */
+declare const DEFAULT_MAX_CHUNK_SIZE_KB: number;
+/**
+ * Default priority fee per gas (tip) for upload transactions, in wei.
+ * Used when the caller does not provide maxPriorityFeePerGas.
+ */
+declare const DEFAULT_PRIORITY_FEE_PER_GAS: bigint;
+/**
+ * Fraction applied to the latest-block base fee when deriving the default
+ * maxFeePerGas: baseFee * NUMERATOR / DENOMINATOR + priority fee.
+ * 11/10 = 1.1x, leaving headroom for one ~10% base-fee increase between blocks.
+ */
+declare const BASE_FEE_MULTIPLIER_NUMERATOR: bigint;
+declare const BASE_FEE_MULTIPLIER_DENOMINATOR: bigint;
+/**
+ * Gas fee model classification by chain.
+ *
+ * LEGACY_GAS_CHAIN_IDS: chains without an EIP-1559 base fee (legacy single-gasPrice
+ * model, price paid in full). BNB Smart Chain mainnet (56) and testnet (97).
+ *
+ * AVALANCHE_GAS_CHAIN_IDS: Avalanche C-Chain mainnet (43114) and Fuji testnet
+ * (43113). EIP-1559 like the default class, but the protocol enforces a minimum
+ * base fee of 25 nAVAX.
+ * All other chains use the default EIP-1559 mechanism (tip + 1.1x base fee).
+ */
+declare const LEGACY_GAS_CHAIN_IDS: ReadonlySet<number>;
+declare const AVALANCHE_GAS_CHAIN_IDS: ReadonlySet<number>;
+/**
+ * Minimum base fee per gas on Avalanche C-Chain (25 nAVAX), in wei.
+ * Used as a floor when deriving the default maxFeePerGas.
+ */
+declare const AVALANCHE_MIN_BASE_FEE_PER_GAS: bigint;
+/**
+ * Resolve the chunk size (in bytes) used to slice the content.
+ * @param maxChunkSizeKB - Chunk size in KB, falls back to DEFAULT_MAX_CHUNK_SIZE_KB when not set.
+ */
+declare function toChunkSizeBytes(maxChunkSizeKB?: number): number;
+
+declare const FlatDirectoryBytecode: string;
+
+interface NodeFile {
+    isNodeJs: boolean;
+    size: number;
+    start: number;
+    end: number;
+    slice(start: number, end: number): NodeFile;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+type BufferLike = Uint8Array;
+type FileLike = File | NodeFile;
+type ContentLike = BufferLike | FileLike;
+interface SDKConfig {
+    rpc?: string;
+    privateKey?: string;
+    ethStorageRpc?: string;
+    address?: string;
+}
+interface UploadCallback {
+    onProgress: (currentChunk: number, totalChunks: number, isChange: boolean) => void;
+    onFail: (error: Error) => void;
+    onFinish: (totalUploadChunks: number, totalUploadSize: number, totalCost: bigint) => void;
+    onTransactionSent?: (txHash: string, chunkIds: number[] | number) => void;
+}
+interface DownloadCallback {
+    onProgress: (currentChunk: number, totalChunks: number, chunkData: Uint8Array) => void;
+    onFail: (error: Error) => void;
+    onFinish: () => void;
+}
+/**
+ * Custom gas fees, in wei.
+ * EIP-1559 fields apply to EIP-1559 chains; gasPrice applies to legacy chains
+ * (e.g. BNB Chain). Unset fields fall back to chain-class defaults.
+ */
+interface GasFeeOptions {
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    gasPrice?: bigint;
+}
+/**
+ * Concrete fees resolved for a transaction, tagged by fee model.
+ * effectiveGasPrice is the expected price actually charged per gas unit:
+ * min(maxFeePerGas, baseFee + priorityFee) under EIP-1559, gasPrice on legacy chains.
+ */
+type ResolvedGasFees = {
+    type: 'eip1559';
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    effectiveGasPrice: bigint;
+} | {
+    type: 'legacy';
+    gasPrice: bigint;
+    effectiveGasPrice: bigint;
+};
+interface EstimateGasRequest {
+    key: string;
+    content: ContentLike;
+    /** Custom max fee per gas, in wei (EIP-1559). */
+    maxFeePerGas?: bigint;
+    /** Custom priority fee per gas, in wei (EIP-1559). */
+    maxPriorityFeePerGas?: bigint;
+    /** Custom gas price, in wei (legacy chains without EIP-1559, e.g. BNB Chain). */
+    gasPrice?: bigint;
+    chunkHashes?: string[];
+    /** Size of each data chunk, in KB. Defaults to DEFAULT_MAX_CHUNK_SIZE_KB. */
+    maxChunkSize?: number;
+    /** Maximum number of chunks requested in a single call. Defaults to MAX_CHUNKS. */
+    maxChunks?: number;
+}
+interface UploadRequest extends EstimateGasRequest {
+    callback: Partial<UploadCallback>;
+}
+interface CostEstimate {
+    storageCost: bigint;
+    gasCost: bigint;
+}
+interface TxCost {
+    normalGasCost: bigint;
+}
+interface UploadResult {
+    txCost: TxCost;
+    success: boolean;
+}
+interface FileBatch {
+    name: string;
+    chunkIds: number[];
+}
+interface UploadDetails {
+    fileMode: number;
+    oldChunkCount: number;
+    cost: bigint;
+}
+interface ChunkCountResult {
+    key: string;
+    chunkCount: number;
+}
+interface ChunkHashResult {
+    name: string;
+    chunkId: number;
+    hash: string;
+}
+
+declare const stringToHex: (s: string) => string;
+declare function getChainId(rpc: string): Promise<number>;
+declare function getContentChunk(content: ContentLike, start: number, end: number): Promise<Uint8Array<ArrayBuffer>>;
+declare function isBuffer(content: ContentLike): content is BufferLike;
+declare function isFile(content: ContentLike): content is FileLike;
+declare function isNodejs(): boolean;
+declare function calcTxCost(receipt: ethers.TransactionReceipt | null): TxCost;
+
+/**
+ * Generic transaction sender: owns the provider and wallet, and exposes
+ * gas price / send / receipt helpers used by the calldata upload path.
+ * Transactions are sent strictly one at a time; callers must await
+ * confirmation before sending the next transaction.
+ */
+declare class TxSender {
+    #private;
+    constructor(rpc: string, privateKey: string);
+    getChainId(): Promise<number>;
+    getFeeData(): Promise<ethers.FeeData>;
+    /**
+     * Base fee of the latest block (EIP-1559), or null on legacy chains.
+     */
+    getBaseFee(): Promise<bigint | null>;
+    /**
+     * Resolve concrete gas fees for a transaction, by chain fee model:
+     * - Legacy chains (no base fee, e.g. BNB Chain): a single gasPrice paid in full,
+     *   taken from the node unless overridden via custom.gasPrice.
+     * - Avalanche C-Chain: EIP-1559 with a protocol-enforced minimum base fee of
+     *   25 nAVAX; the node-reported base fee is clamped to that floor.
+     * - Other (EIP-1559) chains: tip defaults to 100 wei,
+     *   maxFeePerGas defaults to 1.1 * baseFee + tip (baseFee from the latest block).
+     * Caller-provided fields take precedence. effectiveGasPrice is the expected
+     * price actually charged per gas unit.
+     */
+    resolveGasFees(custom?: GasFeeOptions): Promise<ResolvedGasFees>;
+    waitForReceipt(hash: string): Promise<ethers.TransactionReceipt | null>;
+    getTransactionResult(hash: string): Promise<UploadResult>;
+    /**
+     * Sends a single transaction. No locking or manual nonce management:
+     * uploads are strictly sequential, so the wallet's automatic nonce
+     * handling is always up to date.
+     */
+    sendTx(tx: ethers.TransactionRequest): Promise<ethers.TransactionResponse>;
+}
+
+declare function getUploadInfo(contract: Contract, hexName: string): Promise<UploadDetails>;
+declare function getChunkCounts(contract: Contract, batch: string[]): Promise<ChunkCountResult[]>;
+declare function getChunkHashes(contract: Contract, batch: FileBatch[]): Promise<ChunkHashResult[]>;
+
+declare function stableRetry<T>(fn: (...args: unknown[]) => Promise<T>, ...args: unknown[]): Promise<T>;
+
+type index_TxSender = TxSender;
+declare const index_TxSender: typeof TxSender;
+declare const index_calcTxCost: typeof calcTxCost;
+declare const index_getChainId: typeof getChainId;
+declare const index_getChunkCounts: typeof getChunkCounts;
+declare const index_getChunkHashes: typeof getChunkHashes;
+declare const index_getContentChunk: typeof getContentChunk;
+declare const index_getUploadInfo: typeof getUploadInfo;
+declare const index_isBuffer: typeof isBuffer;
+declare const index_isFile: typeof isFile;
+declare const index_isNodejs: typeof isNodejs;
+declare const index_stableRetry: typeof stableRetry;
+declare const index_stringToHex: typeof stringToHex;
+declare namespace index {
+  export { index_TxSender as TxSender, index_calcTxCost as calcTxCost, index_getChainId as getChainId, index_getChunkCounts as getChunkCounts, index_getChunkHashes as getChunkHashes, index_getContentChunk as getContentChunk, index_getUploadInfo as getUploadInfo, index_isBuffer as isBuffer, index_isFile as isFile, index_isNodejs as isNodejs, index_stableRetry as stableRetry, index_stringToHex as stringToHex };
+}
+
+declare class FlatDirectory {
+    #private;
+    /**
+     * Private constructor - use create() factory method
+     */
+    private constructor();
+    static create(config: SDKConfig): Promise<FlatDirectory>;
+    /**
+     * Enable or disable logging
+     * @param value - true to enable logging, false to disable
+     */
+    setLogEnabled(value: boolean): void;
+    /**
+     * Deploy a new FlatDirectory contract
+     * @returns Contract address if successful, null otherwise
+     */
+    deploy(): Promise<string | null>;
+    /**
+     * Set a file as the default file
+     * @param filename - Name of the file to set as default
+     * @returns true if successful, false otherwise
+     */
+    setDefault(filename: string): Promise<boolean>;
+    /**
+     * Remove a file from the contract
+     * @param key - File key to remove
+     * @returns true if successful, false otherwise
+     */
+    remove(key: string): Promise<boolean>;
+    /**
+     * Download a file from the contract
+     * @param key - File key to download
+     * @param cb - Download callback object
+     */
+    download(key: string, cb?: DownloadCallback): Promise<void>;
+    /**
+     * Fetch chunk hashes for multiple files
+     * @param keys - Array of file keys
+     * @param maxChunks - Maximum number of chunks requested in a single call, defaults to MAX_CHUNKS
+     * @returns Object mapping file keys to their chunk hashes
+     */
+    fetchHashes(keys: string[], maxChunks?: number): Promise<Record<string, string[]>>;
+    /**
+     * Estimate cost for uploading a file
+     * @param request - Upload request details
+     * @returns Cost estimation object
+     */
+    estimateCost(request: EstimateGasRequest): Promise<CostEstimate>;
+    /**
+     * Upload a file to the contract
+     * @param request - Upload request details
+     * @throws Error if upload fails
+     */
+    upload(request: UploadRequest): Promise<void>;
+}
+
+export { AVALANCHE_GAS_CHAIN_IDS, AVALANCHE_MIN_BASE_FEE_PER_GAS, BASE_FEE_MULTIPLIER_DENOMINATOR, BASE_FEE_MULTIPLIER_NUMERATOR, type BufferLike, CALLDATA_CHUNK_OVERHEAD, CONTRACT_MAX_CHUNK_SIZE, type ChunkCountResult, type ChunkHashResult, type ContentLike, type CostEstimate, DEFAULT_MAX_CHUNK_SIZE_KB, DEFAULT_PRIORITY_FEE_PER_GAS, type DownloadCallback, ETHSTORAGE_MAPPING, type EstimateGasRequest, type FileBatch, type FileLike, FlatDirectory, FlatDirectoryAbi, FlatDirectoryBytecode, type GasFeeOptions, LEGACY_GAS_CHAIN_IDS, MAX_CHUNKS, type NodeFile, type ResolvedGasFees, type SDKConfig, type TxCost, type UploadCallback, type UploadDetails, type UploadRequest, type UploadResult, toChunkSizeBytes, index as utils };