near-kit 0.0.0 → 0.1.0

package/dist/sandbox/sandbox.js

@@ -0,0 +1,341 @@
+/**
+ * NEAR Sandbox - Local testing environment
+ *
+ * Simple, explicit API for running a local NEAR node for testing.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import * as tar from "tar";
+const DEFAULT_VERSION = "2.9.0";
+const BINARY_NAME = "near-sandbox";
+const ARCHIVE_NAME = "near-sandbox.tar.gz";
+const DOWNLOAD_BASE = "https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore";
+const STARTUP_TIMEOUT = 60000;
+const DOWNLOAD_TIMEOUT = 120000;
+/**
+ * NEAR Sandbox instance
+ *
+ * Manages a local NEAR node for testing. Automatically cleans up on stop().
+ *
+ * @example
+ * ```typescript
+ * const sandbox = await Sandbox.start();
+ * const near = new Near({ network: sandbox });
+ * // ... run tests
+ * await sandbox.stop();
+ * ```
+ */
+export class Sandbox {
+    constructor(rpcUrl, networkId, rootAccount, homeDir, childProcess) {
+        this.rpcUrl = rpcUrl;
+        this.networkId = networkId;
+        this.rootAccount = rootAccount;
+        this.homeDir = homeDir;
+        this.process = childProcess;
+    }
+    /**
+     * Start a new sandbox instance
+     *
+     * Downloads the sandbox binary if needed, initializes a temporary directory,
+     * and starts the sandbox process.
+     *
+     * @param options - Optional configuration
+     * @returns Promise resolving to a running Sandbox instance
+     */
+    static async start(options = {}) {
+        const version = options.version ?? DEFAULT_VERSION;
+        const detached = options.detached ?? true;
+        // 1. Ensure binary is available
+        const binaryPath = await ensureBinary(version);
+        // 2. Create temporary home directory
+        const homeDir = await mkdtemp(path.join(os.tmpdir(), "near-sandbox-"));
+        // 3. Initialize sandbox
+        await runInit(binaryPath, homeDir);
+        // 4. Read validator key
+        const validatorKey = await loadValidatorKey(homeDir);
+        const rootAccount = {
+            id: validatorKey.account_id,
+            secretKey: validatorKey.secret_key ?? validatorKey.private_key ?? "",
+        };
+        // 5. Start sandbox process
+        const port = await findAvailablePort();
+        const networkPort = port + 1;
+        const childProcess = spawn(binaryPath, [
+            "--home",
+            homeDir,
+            "run",
+            "--rpc-addr",
+            `0.0.0.0:${port}`,
+            "--network-addr",
+            `0.0.0.0:${networkPort}`,
+        ], {
+            detached,
+            stdio: detached ? "ignore" : "pipe",
+        });
+        if (!childProcess.pid) {
+            throw new Error("Failed to start sandbox: no PID");
+        }
+        if (detached) {
+            childProcess.unref();
+        }
+        const rpcUrl = `http://127.0.0.1:${port}`;
+        // 6. Wait for RPC to be ready
+        await waitForReady(rpcUrl);
+        return new Sandbox(rpcUrl, "localnet", rootAccount, homeDir, childProcess);
+    }
+    /**
+     * Stop the sandbox and clean up
+     *
+     * Kills the sandbox process and removes temporary files.
+     */
+    async stop() {
+        if (this.process?.pid) {
+            const pid = this.process.pid;
+            try {
+                // Try to kill process group first (for detached processes)
+                process.kill(-pid, "SIGTERM");
+                await sleep(100);
+            }
+            catch {
+                // Try direct kill
+                try {
+                    process.kill(pid, "SIGTERM");
+                    await sleep(100);
+                }
+                catch {
+                    // Try SIGKILL as last resort
+                    try {
+                        process.kill(pid, "SIGKILL");
+                    }
+                    catch {
+                        // Process already dead
+                    }
+                }
+            }
+            this.process = undefined;
+        }
+        // Clean up temporary directory
+        try {
+            await rm(this.homeDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+// ==================== Helper Functions ====================
+/**
+ * Get platform identifier for downloading correct binary.
+ * @internal
+ */
+function getPlatformId() {
+    const system = os.platform();
+    const arch = os.arch();
+    const platform = system === "darwin" ? "Darwin" : "Linux";
+    const normalizedArch = arch === "x64" ? "x86_64" : arch;
+    if (!["x86_64", "arm64"].includes(normalizedArch)) {
+        throw new Error(`Unsupported architecture: ${arch}`);
+    }
+    if (system !== "darwin" && system !== "linux") {
+        throw new Error(`Unsupported platform: ${system}`);
+    }
+    return { system: platform, arch: normalizedArch };
+}
+/**
+ * Get directory for storing sandbox binaries.
+ * @internal
+ */
+function getBinaryDir() {
+    const dir = path.join(os.homedir(), ".near-kit", "sandbox", "bin");
+    return dir;
+}
+/**
+ * Download and extract sandbox binary.
+ * @internal
+ */
+async function downloadBinary(version) {
+    const { system, arch } = getPlatformId();
+    const destDir = getBinaryDir();
+    const filename = `${BINARY_NAME}-${version}`;
+    const dest = path.join(destDir, filename);
+    // Return if already exists
+    if (fs.existsSync(dest)) {
+        return dest;
+    }
+    const url = `${DOWNLOAD_BASE}/${system}-${arch}/${version}/${ARCHIVE_NAME}`;
+    const tmpDir = await mkdtemp(path.join(os.tmpdir(), "near-sandbox-download-"));
+    try {
+        const archivePath = path.join(tmpDir, ARCHIVE_NAME);
+        // Download with timeout
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT);
+        try {
+            const response = await fetch(url, { signal: controller.signal });
+            if (!response.ok) {
+                throw new Error(`Download failed: ${response.status} ${response.statusText}`);
+            }
+            if (!response.body) {
+                throw new Error("Response body is null");
+            }
+            const stream = fs.createWriteStream(archivePath);
+            // Convert DOM ReadableStream to Node.js ReadableStream
+            await pipeline(Readable.fromWeb(response.body), stream);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        // Extract archive (strip=1 removes top-level directory)
+        await tar.x({ file: archivePath, cwd: tmpDir, strip: 1 });
+        const extracted = path.join(tmpDir, BINARY_NAME);
+        if (!fs.existsSync(extracted)) {
+            throw new Error(`Binary ${BINARY_NAME} not found in archive`);
+        }
+        // Move to final location and make executable
+        await mkdir(path.dirname(dest), { recursive: true });
+        await fs.promises.rename(extracted, dest);
+        await fs.promises.chmod(dest, 0o755);
+        return dest;
+    }
+    catch (error) {
+        throw new Error(`Failed to download binary from ${url}: ${error}`);
+    }
+    finally {
+        await rm(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Ensure binary is available and return its path.
+ * @internal
+ */
+async function ensureBinary(version) {
+    return await downloadBinary(version);
+}
+/**
+ * Run sandbox init command.
+ * @internal
+ */
+async function runInit(binaryPath, homeDir) {
+    const args = ["--home", homeDir, "init", "--chain-id", "localnet"];
+    return new Promise((resolve, reject) => {
+        const child = spawn(binaryPath, args, { stdio: "pipe" });
+        let stderr = "";
+        child.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        child.on("exit", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                // Provide helpful error message for common issues
+                let errorMsg = `Sandbox init failed with code ${code}: ${stderr}`;
+                if (stderr.includes("file descriptor limit")) {
+                    errorMsg +=
+                        "\n\n" +
+                            "The sandbox requires at least 65,535 file descriptors.\n" +
+                            "Current limit can be checked with: ulimit -n\n\n" +
+                            "To fix on Linux, add to /etc/security/limits.conf:\n" +
+                            "  * soft nofile 65535\n" +
+                            "  * hard nofile 65535\n\n" +
+                            "To fix on macOS:\n" +
+                            "  sudo launchctl limit maxfiles 65536 200000\n\n" +
+                            "For Docker, add: --ulimit nofile=65535:65535\n\n" +
+                            "See: https://github.com/r-near/near-kit/blob/main/src/sandbox/README.md";
+                }
+                reject(new Error(errorMsg));
+            }
+        });
+        child.on("error", reject);
+    });
+}
+/**
+ * Load validator key from sandbox home directory.
+ * @internal
+ */
+async function loadValidatorKey(homeDir) {
+    const keyPath = path.join(homeDir, "validator_key.json");
+    try {
+        const data = await readFile(keyPath, "utf8");
+        return JSON.parse(data);
+    }
+    catch (error) {
+        throw new Error(`Failed to read validator key from ${keyPath}: ${error}`);
+    }
+}
+/**
+ * Find an available port by letting the OS choose.
+ * @internal
+ */
+async function findAvailablePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("Failed to get port"));
+                return;
+            }
+            const port = address.port;
+            server.close(() => {
+                resolve(port);
+            });
+        });
+    });
+}
+/**
+ * Ping sandbox RPC endpoint to check if it's ready.
+ * @internal
+ */
+async function pingRpc(url, timeoutMs = 1000) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: "status",
+                method: "status",
+                params: [],
+            }),
+            signal: controller.signal,
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Wait for sandbox to be ready.
+ * @internal
+ */
+async function waitForReady(rpcUrl, timeout = STARTUP_TIMEOUT) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+        if (await pingRpc(rpcUrl)) {
+            return;
+        }
+        await sleep(500);
+    }
+    throw new Error(`Sandbox failed to start within ${timeout}ms`);
+}
+/**
+ * Sleep helper.
+ * @internal
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/sandbox/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/utils/amount.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Amount utilities for NEAR tokens.
+ *
+ * All amounts must specify units explicitly:
+ * - `Amount.NEAR(10)` → `"10 NEAR"`
+ * - `Amount.yocto(1000n)` → `"1000 yocto"`
+ * - `"10 NEAR"` (string literal)
+ * - `"1000 yocto"` (string literal)
+ * - `1000n` (bigint literal, treated as yoctoNEAR)
+ *
+ * No bare numbers are accepted in order to prevent accidental unit confusion.
+ */
+/**
+ * Amount input type - must be a string with unit specification or bigint.
+ *
+ * Accepts:
+ * - Literal strings: "10 NEAR", "10.5 NEAR", "1000 yocto"
+ * - Constructor output: Amount.NEAR(10), Amount.yocto(1000n)
+ * - Raw bigint: 1000000n (interpreted as yoctoNEAR)
+ *
+ * For variables, use 'as const' to preserve literal type:
+ * @example
+ * const amount = "10 NEAR" as const
+ * const yocto = 1000000n  // Direct bigint is treated as yoctoNEAR
+ */
+export type AmountInput = `${number} NEAR` | `${number}.${number} NEAR` | `${number} yocto` | ReturnType<typeof Amount.NEAR> | ReturnType<typeof Amount.yocto> | bigint;
+/**
+ * Amount namespace - explicit constructors for NEAR values.
+ *
+ * @example
+ * Amount.NEAR(10)           // "10 NEAR"
+ * Amount.NEAR(10.5)         // "10.5 NEAR"
+ * Amount.NEAR("10.5")       // "10.5 NEAR"
+ * Amount.yocto(1000000n)    // "1000000 yocto"
+ * Amount.yocto("1000000")   // "1000000 yocto"
+ */
+export declare const Amount: {
+    /**
+     * Create a NEAR amount.
+     * @param value - Amount in NEAR.
+     * @returns Formatted string `"X NEAR"`.
+     */
+    readonly NEAR: (value: number | string) => string;
+    /**
+     * Create a yoctoNEAR amount (10^-24 NEAR).
+     * @param value - Amount in yoctoNEAR.
+     * @returns Formatted string `"X yocto"`.
+     */
+    readonly yocto: (value: bigint | string) => string;
+    /**
+     * Common amount constants.
+     */
+    readonly ZERO: "0 yocto";
+    readonly ONE_NEAR: "1 NEAR";
+    readonly ONE_YOCTO: "1 yocto";
+};
+/**
+ * Parse amount to yoctoNEAR.
+ *
+ * @param amount - Amount with unit (e.g., `"10 NEAR"`, `"1000 yocto"`) or bigint (treated as yoctoNEAR).
+ * @returns Amount in yoctoNEAR as a string.
+ * @throws Error If the format is invalid or ambiguous (e.g. bare numbers).
+ */
+export declare function parseAmount(amount: AmountInput): string;
+/**
+ * Format yoctoNEAR to human-readable NEAR
+ * @param yocto - Amount in yoctoNEAR
+ * @param options - Formatting options
+ * @returns Formatted string (e.g., "10.50 NEAR")
+ */
+export declare function formatAmount(yocto: string | bigint, options?: {
+    precision?: number;
+    includeSuffix?: boolean;
+    trimZeros?: boolean;
+}): string;
+//# sourceMappingURL=amount.d.ts.map

package/dist/utils/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../src/utils/amount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACnB,GAAG,MAAM,OAAO,GAChB,GAAG,MAAM,IAAI,MAAM,OAAO,GAC1B,GAAG,MAAM,QAAQ,GACjB,UAAU,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,GAC9B,UAAU,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,GAC/B,MAAM,CAAA;AAEV;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM;IACjB;;;;OAIG;2BACS,MAAM,GAAG,MAAM,KAAG,MAAM;IAIpC;;;;OAIG;4BACU,MAAM,GAAG,MAAM,KAAG,MAAM;IAIrC;;OAEG;;;;CAIK,CAAA;AAEV;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA+CvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GACA,MAAM,CA4BR"}

package/dist/utils/amount.js

@@ -0,0 +1,137 @@
+/**
+ * Amount utilities for NEAR tokens.
+ *
+ * All amounts must specify units explicitly:
+ * - `Amount.NEAR(10)` → `"10 NEAR"`
+ * - `Amount.yocto(1000n)` → `"1000 yocto"`
+ * - `"10 NEAR"` (string literal)
+ * - `"1000 yocto"` (string literal)
+ * - `1000n` (bigint literal, treated as yoctoNEAR)
+ *
+ * No bare numbers are accepted in order to prevent accidental unit confusion.
+ */
+import { YOCTO_PER_NEAR } from "../core/constants.js";
+/**
+ * Amount namespace - explicit constructors for NEAR values.
+ *
+ * @example
+ * Amount.NEAR(10)           // "10 NEAR"
+ * Amount.NEAR(10.5)         // "10.5 NEAR"
+ * Amount.NEAR("10.5")       // "10.5 NEAR"
+ * Amount.yocto(1000000n)    // "1000000 yocto"
+ * Amount.yocto("1000000")   // "1000000 yocto"
+ */
+export const Amount = {
+    /**
+     * Create a NEAR amount.
+     * @param value - Amount in NEAR.
+     * @returns Formatted string `"X NEAR"`.
+     */
+    NEAR(value) {
+        return `${value} NEAR`;
+    },
+    /**
+     * Create a yoctoNEAR amount (10^-24 NEAR).
+     * @param value - Amount in yoctoNEAR.
+     * @returns Formatted string `"X yocto"`.
+     */
+    yocto(value) {
+        return `${value} yocto`;
+    },
+    /**
+     * Common amount constants.
+     */
+    ZERO: "0 yocto",
+    ONE_NEAR: "1 NEAR",
+    ONE_YOCTO: "1 yocto",
+};
+/**
+ * Parse amount to yoctoNEAR.
+ *
+ * @param amount - Amount with unit (e.g., `"10 NEAR"`, `"1000 yocto"`) or bigint (treated as yoctoNEAR).
+ * @returns Amount in yoctoNEAR as a string.
+ * @throws Error If the format is invalid or ambiguous (e.g. bare numbers).
+ */
+export function parseAmount(amount) {
+    // Handle bigint directly (treated as yoctoNEAR)
+    if (typeof amount === "bigint") {
+        return amount.toString();
+    }
+    const trimmed = amount.trim();
+    // Parse "X NEAR" format (case insensitive)
+    const nearMatch = trimmed.match(/^([\d.]+)\s+NEAR$/i);
+    if (nearMatch) {
+        // Safe to use non-null assertion after match check
+        // biome-ignore lint/style/noNonNullAssertion: regex capture group guaranteed to exist when match succeeds
+        const value = nearMatch[1];
+        return parseNearToYocto(value);
+    }
+    // Parse "X yocto" format
+    const yoctoMatch = trimmed.match(/^(\d+)\s+yocto$/i);
+    if (yoctoMatch) {
+        // Safe to use non-null assertion after match check
+        // biome-ignore lint/style/noNonNullAssertion: regex capture group guaranteed to exist when match succeeds
+        return yoctoMatch[1];
+    }
+    // Common mistake: bare number
+    if (/^[\d.]+$/.test(trimmed)) {
+        throw new Error(`Ambiguous amount: "${amount}". Did you mean "${amount} NEAR"?\n` +
+            `  - Use Amount.NEAR(${amount}) for NEAR\n` +
+            `  - Use Amount.yocto(${amount}n) for yoctoNEAR\n` +
+            `  - Or write "${amount} NEAR" or "${amount} yocto"\n` +
+            `  - Or pass ${amount}n as bigint for yoctoNEAR\n` +
+            `\n` +
+            `💡 TypeScript tip: Use 'as const' for variables:\n` +
+            `   const amount = "10 NEAR" as const`);
+    }
+    // Invalid format
+    throw new Error(`Invalid amount format: "${amount}"\n` +
+        `Expected formats:\n` +
+        `  - "10 NEAR" or Amount.NEAR(10)\n` +
+        `  - "1000000 yocto" or Amount.yocto(1000000n)\n` +
+        `  - 1000000n (bigint, treated as yoctoNEAR)`);
+}
+/**
+ * Format yoctoNEAR to human-readable NEAR
+ * @param yocto - Amount in yoctoNEAR
+ * @param options - Formatting options
+ * @returns Formatted string (e.g., "10.50 NEAR")
+ */
+export function formatAmount(yocto, options) {
+    const { precision = 2, includeSuffix = true, trimZeros = false, } = options || {};
+    const amount = typeof yocto === "string" ? BigInt(yocto) : yocto;
+    const wholePart = amount / YOCTO_PER_NEAR;
+    const fracPart = amount % YOCTO_PER_NEAR;
+    let result;
+    if (fracPart === BigInt(0)) {
+        result = wholePart.toString();
+    }
+    else {
+        const fracStr = fracPart.toString().padStart(24, "0");
+        let decimals = fracStr.substring(0, precision);
+        if (trimZeros) {
+            decimals = decimals.replace(/0+$/, "");
+        }
+        result = decimals ? `${wholePart}.${decimals}` : wholePart.toString();
+    }
+    return includeSuffix ? `${result} NEAR` : result;
+}
+/**
+ * Internal: Parse NEAR value to yoctoNEAR
+ * Note: The caller (parseAmount) already validates the format with the same regex,
+ * so the value is guaranteed to match [\d.]+ pattern when it reaches this function.
+ */
+function parseNearToYocto(value) {
+    // Split into whole and fractional parts
+    const parts = value.split(".");
+    const wholePart = parts[0] || "0";
+    const fracPart = (parts[1] || "").padEnd(24, "0").substring(0, 24);
+    // Check for negative values
+    if (wholePart.startsWith("-")) {
+        throw new Error("NEAR amount must be non-negative");
+    }
+    // Convert to yoctoNEAR
+    const yocto = BigInt(wholePart) * YOCTO_PER_NEAR + BigInt(fracPart);
+    return yocto.toString();
+}
+//# sourceMappingURL=amount.js.map

package/dist/utils/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../src/utils/amount.ts"],"names":[],"mappings":"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"}

package/dist/utils/gas.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gas utilities for NEAR transactions.
+ *
+ * Gas amounts should specify units explicitly:
+ * - `Gas.Tgas(30)` → `"30 Tgas"`
+ * - `"30 Tgas"` (string literal)
+ *
+ * Raw gas units (e.g. `"30000000000000"`) are also supported for advanced use cases.
+ */
+/**
+ * Gas input type - string with unit specification.
+ *
+ * Accepts:
+ * - Literal strings: "30 Tgas", "30.5 Tgas"
+ * - Raw gas strings: "30000000000000"
+ * - Constructor output: Gas.Tgas(30)
+ *
+ * For variables, use 'as const' to preserve literal type:
+ * @example
+ * const gas = "30 Tgas" as const
+ */
+export type GasInput = `${number} Tgas` | `${number}.${number} Tgas` | `${number}` | ReturnType<typeof Gas.Tgas>;
+/**
+ * Gas namespace - explicit constructors.
+ *
+ * @example
+ * Gas.Tgas(30)        // "30 Tgas"
+ * Gas.Tgas(300)       // "300 Tgas"
+ */
+export declare const Gas: {
+    /**
+     * Create gas amount in TGas (teragas).
+     * @param value - Amount in TGas.
+     */
+    readonly Tgas: (value: number | string) => string;
+    /**
+     * Common gas amounts.
+     */
+    readonly DEFAULT: "30 Tgas";
+    readonly MAX: "300 Tgas";
+};
+/**
+ * Parse gas string to raw gas units.
+ *
+ * @param gas - Gas with unit (e.g., `"30 Tgas"`) or raw gas number.
+ * @returns Gas in raw units as a string.
+ */
+export declare function parseGas(gas: GasInput | number): string;
+/**
+ * Format gas to TGas.
+ *
+ * @param gas - Gas in raw units.
+ * @param precision - Decimal places (default: 2).
+ * @returns Formatted gas with `' Tgas'` suffix.
+ */
+export declare function formatGas(gas: string | bigint, precision?: number): string;
+/**
+ * Convert TGas to raw gas units.
+ * @param tgas - Amount in TGas.
+ * @returns Gas amount as string.
+ */
+export declare function toGas(tgas: number): string;
+/**
+ * Convert raw gas to TGas.
+ * @param gas - Gas amount in raw units.
+ * @returns Amount in TGas.
+ */
+export declare function toTGas(gas: string | bigint): number;
+//# sourceMappingURL=gas.d.ts.map

package/dist/utils/gas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../../src/utils/gas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAChB,GAAG,MAAM,OAAO,GAChB,GAAG,MAAM,IAAI,MAAM,OAAO,GAC1B,GAAG,MAAM,EAAE,GACX,UAAU,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,CAAA;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,GAAG;IACd;;;OAGG;2BACS,MAAM,GAAG,MAAM,KAAG,MAAM;IAIpC;;OAEG;;;CAGK,CAAA;AAEV;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CA6BvD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,SAAI,GAAG,MAAM,CAIrE;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGnD"}