ryt-sdk 1.0.9 → 1.0.10

package/dist/provider.d.ts

@@ -1,49 +1,82 @@
 import { ethers } from "ethers";
 import type { SDKConfig } from "./config";
 /**
- * RYTProvider is a provider instance that connects to the blockchain and allows interaction with it.
+ * Unified blockchain provider instance used across RYT SDK.
+ *
+ * Provides a single interface for interacting with:
+ * - Browser wallet providers (if available)
+ * - RPC-based blockchain nodes (fallback)
+ *
+ * Automatically selects the most appropriate transport layer
+ * based on runtime environment and configuration.
  */
 export default class RYTProvider {
     private provider;
     /**
-     * Create a new RYTProvider instance
+     * Creates a new provider instance.
      *
-     * @param config - SDK configuration containing RPC URLs
-     * @param rpcUrl - Optional override RPC URL. If not provided, uses first config RPC URL
+     * Selection priority:
+     * 1. Injected wallet provider (if enabled and available)
+     * 2. RPC provider from config or override
      *
-     * @example
-     * ```ts
-     * const provider = new RYTProvider(config);
-     * ```
+     * @param config - SDK configuration containing chain and provider settings
+     * @param rpcUrl - Optional override RPC endpoint (takes priority over config)
+     *
+     * @throws Error if no valid provider source is available
      */
     constructor(config: SDKConfig, rpcUrl?: string);
     /**
-     * Returns the provider instance
+     * Returns the underlying provider instance.
+     *
+     * This may be either:
+     * - Browser-based provider (wallet-connected)
+     * - RPC-based provider (node connection)
      *
      * @returns provider instance
      */
-    getProvider(): ethers.JsonRpcProvider;
+    getProvider(): ethers.BrowserProvider | ethers.JsonRpcProvider;
+    /**
+     * Returns a signer for transaction signing.
+     *
+     * Available only when using a browser wallet provider.
+     *
+     * @throws Error if provider is not a browser wallet instance
+     * @returns Signer instance for transaction signing
+     */
+    getSigner(): Promise<ethers.Signer>;
     /**
-     * Get the latest block number from the blockchain
+     * Retrieves the connected wallet address.
      *
-     * @returns Promise resolving to latest block number
+     * Requires an active browser wallet connection.
      *
-     * @example
-     * ```ts
-     * const blockNumber = await provider.getBlockNumber();
-     * ```
+     * @returns Wallet address string
+     */
+    getAddress(): Promise<string>;
+    /**
+     * Retrieves the current network information.
+     *
+     * @returns Network metadata including chainId and name
+     */
+    getNetwork(): Promise<ethers.Network>;
+    /**
+     * Retrieves the latest block number from the blockchain.
+     *
+     * @returns Latest block number
      */
     getBlockNumber(): Promise<number>;
     /**
-     * Get balance of a given address in wei
+     * Retrieves the balance of an address.
      *
-     * @param address - Ethereum-style wallet address
-     * @returns Promise resolving to balance in wei (BigInt-compatible)
+     * @param address - Valid Ethereum-compatible address
+     * @returns Balance in wei
      *
-     * @example
-     * ```ts
-     * const balance = await provider.getBalance("0x123...");
-     * ```
+     * @throws Error if address is invalid
      */
     getBalance(address: string): Promise<bigint>;
+    /**
+     * Checks whether the provider is using a browser wallet.
+     *
+     * @returns true if injected wallet is active, false if RPC is used
+     */
+    isInjected(): boolean;
 }

package/dist/provider.js

@@ -1,28 +1,46 @@
 import { ethers } from "ethers";
+import { getRYT } from "./utils/ryt";
 /**
- * RYTProvider is a provider instance that connects to the blockchain and allows interaction with it.
+ * Unified blockchain provider instance used across RYT SDK.
+ *
+ * Provides a single interface for interacting with:
+ * - Browser wallet providers (if available)
+ * - RPC-based blockchain nodes (fallback)
+ *
+ * Automatically selects the most appropriate transport layer
+ * based on runtime environment and configuration.
  */
 export default class RYTProvider {
     /**
-     * Create a new RYTProvider instance
+     * Creates a new provider instance.
      *
-     * @param config - SDK configuration containing RPC URLs
-     * @param rpcUrl - Optional override RPC URL. If not provided, uses first config RPC URL
+     * Selection priority:
+     * 1. Injected wallet provider (if enabled and available)
+     * 2. RPC provider from config or override
      *
-     * @example
-     * ```ts
-     * const provider = new RYTProvider(config);
-     * ```
+     * @param config - SDK configuration containing chain and provider settings
+     * @param rpcUrl - Optional override RPC endpoint (takes priority over config)
+     *
+     * @throws Error if no valid provider source is available
      */
     constructor(config, rpcUrl) {
-        const rpc = rpcUrl ?? config.rpcUrls[0];
+        const rpc = rpcUrl ?? config.rpcUrls?.[0];
+        const injected = getRYT();
+        if (injected && config.enableBrowserWallet !== false) {
+            this.provider = new ethers.BrowserProvider(injected);
+            return;
+        }
         if (!rpc) {
-            throw new Error("No RPC URL provided in config or constructor");
+            throw new Error("No provider available (no RPC or wallet)");
         }
         this.provider = new ethers.JsonRpcProvider(rpc);
     }
     /**
-     * Returns the provider instance
+     * Returns the underlying provider instance.
+     *
+     * This may be either:
+     * - Browser-based provider (wallet-connected)
+     * - RPC-based provider (node connection)
      *
      * @returns provider instance
      */
@@ -30,33 +48,66 @@ export default class RYTProvider {
         return this.provider;
     }
     /**
-     * Get the latest block number from the blockchain
+     * Returns a signer for transaction signing.
      *
-     * @returns Promise resolving to latest block number
+     * Available only when using a browser wallet provider.
      *
-     * @example
-     * ```ts
-     * const blockNumber = await provider.getBlockNumber();
-     * ```
+     * @throws Error if provider is not a browser wallet instance
+     * @returns Signer instance for transaction signing
+     */
+    async getSigner() {
+        if (!(this.provider instanceof ethers.BrowserProvider)) {
+            throw new Error("Signer not available in RPC mode");
+        }
+        return await this.provider.getSigner();
+    }
+    /**
+     * Retrieves the connected wallet address.
+     *
+     * Requires an active browser wallet connection.
+     *
+     * @returns Wallet address string
+     */
+    async getAddress() {
+        const signer = await this.getSigner();
+        return await signer.getAddress();
+    }
+    /**
+     * Retrieves the current network information.
+     *
+     * @returns Network metadata including chainId and name
+     */
+    async getNetwork() {
+        return await this.provider.getNetwork();
+    }
+    /**
+     * Retrieves the latest block number from the blockchain.
+     *
+     * @returns Latest block number
      */
     async getBlockNumber() {
         return await this.provider.getBlockNumber();
     }
     /**
-     * Get balance of a given address in wei
+     * Retrieves the balance of an address.
      *
-     * @param address - Ethereum-style wallet address
-     * @returns Promise resolving to balance in wei (BigInt-compatible)
+     * @param address - Valid Ethereum-compatible address
+     * @returns Balance in wei
      *
-     * @example
-     * ```ts
-     * const balance = await provider.getBalance("0x123...");
-     * ```
+     * @throws Error if address is invalid
      */
     async getBalance(address) {
         if (!ethers.isAddress(address)) {
-            throw new Error(`Invalid address: ${address}`);
+            throw new Error("Invalid address");
         }
         return await this.provider.getBalance(address);
     }
+    /**
+     * Checks whether the provider is using a browser wallet.
+     *
+     * @returns true if injected wallet is active, false if RPC is used
+     */
+    isInjected() {
+        return this.provider instanceof ethers.BrowserProvider;
+    }
 }

package/dist/utils/ryt.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Minimal EIP-1193 provider interface.
+ *
+ * Represents a browser-injected wallet provider such as:
+ * - MetaMask
+ * - Rabby
+ * - Coinbase Wallet
+ *
+ * This interface standardizes communication with injected wallets
+ * using the EIP-1193 request/response pattern.
+ */
+export interface RYTProvider {
+    request: (args: {
+        method: string;
+        params?: any[];
+    }) => Promise<any>;
+    on?: (event: string, handler: (...args: any[]) => void) => void;
+    removeListener?: (event: string, handler: (...args: any[]) => void) => void;
+}
+/**
+ * Safely retrieves the injected provider from the browser.
+ *
+ * This function:
+ * - Works in browser environments only
+ * - Is SSR-safe (Next.js / Vite / Node.js compatible)
+ * - Returns undefined if no wallet is installed
+ *
+ * @returns provider instance if available, otherwise undefined
+ *
+ * @example
+ * const ryt = getRYT();
+ * if (ryt) {
+ *   console.log("Wallet is available");
+ * }
+ */
+export declare function getRYT(): RYTProvider | undefined;
+/**
+ * Checks whether an injected wallet is available.
+ *
+ * This is a convenience helper around `getRYT()`.
+ * Useful for conditionally enabling wallet-based features.
+ *
+ * @returns true if a wallet (MetaMask / similar) is detected, otherwise false
+ *
+ * @example
+ * if (!hasRYT()) {
+ *   alert("Please install MetaMask");
+ * }
+ */
+export declare function hasRYT(): boolean;
+/**
+ * Requests account access from the user's wallet.
+ *
+ * This triggers the wallet popup (e.g. MetaMask approval dialog)
+ * using the EIP-1193 `eth_requestAccounts` method.
+ *
+ * Requirements:
+ * - Must be called in a browser environment
+ * - Requires an injected wallet (MetaMask, etc.)
+ *
+ * @returns Promise resolving to an array of connected wallet addresses
+ *
+ * @throws Error if no injected wallet is available
+ *
+ * @example
+ * const accounts = await requestAccounts();
+ * console.log(accounts[0]);
+ */
+export declare function requestAccounts(): Promise<string[]>;

package/dist/utils/ryt.js

@@ -0,0 +1,64 @@
+/**
+ * Safely retrieves the injected provider from the browser.
+ *
+ * This function:
+ * - Works in browser environments only
+ * - Is SSR-safe (Next.js / Vite / Node.js compatible)
+ * - Returns undefined if no wallet is installed
+ *
+ * @returns provider instance if available, otherwise undefined
+ *
+ * @example
+ * const ryt = getRYT();
+ * if (ryt) {
+ *   console.log("Wallet is available");
+ * }
+ */
+export function getRYT() {
+    if (typeof globalThis === "undefined")
+        return undefined;
+    const eth = globalThis.ethereum;
+    if (!eth)
+        return undefined;
+    return eth;
+}
+/**
+ * Checks whether an injected wallet is available.
+ *
+ * This is a convenience helper around `getRYT()`.
+ * Useful for conditionally enabling wallet-based features.
+ *
+ * @returns true if a wallet (MetaMask / similar) is detected, otherwise false
+ *
+ * @example
+ * if (!hasRYT()) {
+ *   alert("Please install MetaMask");
+ * }
+ */
+export function hasRYT() {
+    return !!getRYT();
+}
+/**
+ * Requests account access from the user's wallet.
+ *
+ * This triggers the wallet popup (e.g. MetaMask approval dialog)
+ * using the EIP-1193 `eth_requestAccounts` method.
+ *
+ * Requirements:
+ * - Must be called in a browser environment
+ * - Requires an injected wallet (MetaMask, etc.)
+ *
+ * @returns Promise resolving to an array of connected wallet addresses
+ *
+ * @throws Error if no injected wallet is available
+ *
+ * @example
+ * const accounts = await requestAccounts();
+ * console.log(accounts[0]);
+ */
+export async function requestAccounts() {
+    const eth = getRYT();
+    if (!eth)
+        throw new Error("No injected wallet found");
+    return eth.request({ method: "eth_requestAccounts" });
+}

package/dist/utils/units.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Converts human-readable token amount into smallest unit (wei-like format).
+ *
+ *
+ * @param amount - human readable value (e.g. "1.5")
+ * @param decimals - token decimals (e.g. 18)
+ * @returns bigint in smallest unit
+ *
+ * @example
+ * parseTokenUnits("1.5", 18)
+ */
+export declare function parseTokenUnits(amount: string, decimals: number): bigint;
+/**
+ * Converts smallest unit back to human-readable value.
+ *
+ *
+ * @param value - bigint or string
+ * @param decimals - token decimals
+ */
+export declare function formatTokenUnits(value: bigint | string, decimals: number): string;

package/dist/utils/units.js

@@ -0,0 +1,25 @@
+import { ethers } from "ethers";
+/**
+ * Converts human-readable token amount into smallest unit (wei-like format).
+ *
+ *
+ * @param amount - human readable value (e.g. "1.5")
+ * @param decimals - token decimals (e.g. 18)
+ * @returns bigint in smallest unit
+ *
+ * @example
+ * parseTokenUnits("1.5", 18)
+ */
+export function parseTokenUnits(amount, decimals) {
+    return ethers.parseUnits(amount, decimals);
+}
+/**
+ * Converts smallest unit back to human-readable value.
+ *
+ *
+ * @param value - bigint or string
+ * @param decimals - token decimals
+ */
+export function formatTokenUnits(value, decimals) {
+    return ethers.formatUnits(value, decimals);
+}

package/dist/wallet.d.ts

@@ -1,63 +1,94 @@
 import { ethers } from "ethers";
 import type RYTProvider from "./provider";
 /**
- * Transaction request type
+ * Transaction request structure for blockchain operations.
  */
 export type TxRequest = ethers.TransactionRequest;
 /**
- * RYTWallet is a wallet instance that supports signing transactions and interacting with the blockchain.
+ * Unified wallet abstraction for RYT SDK.
+ *
+ * Supports:
+ * - Private key wallets (Node.js / backend)
+ * - Browser injected wallets (MetaMask, Rabby, etc.)
+ *
+ * Automatically adapts behavior based on runtime environment.
  */
 export default class RYTWallet {
-    private wallet;
+    private signer;
     /**
-     * Create a new RYTWallet instance
+     * Create a new wallet instance.
      *
-     * @param privateKey - Ethereum private key (0x...)
-     * @param provider - Optional RYTProvider instance for network access
+     * The wallet can operate in two modes:
      *
-     * @example
-     * ```ts
+     * 1. Backend mode (private key provided)
+     *    - Full signing capability
+     *    - Used in Node.js scripts, servers, bots
+     *
+     * 2. Browser mode (injected wallet)
+     *    - Uses connected wallet (MetaMask, etc.)
+     *    - No private key required or allowed
+     *
+     * @param signerOrPrivateKey
+     * - string → private key (backend mode)
+     * - signer → injected browser signer
+     *
+     * @param provider Optional provider instance for network access
+     *
+     * @throws Error if invalid input is provided
+     *
+     * @example Backend:
      * const wallet = new RYTWallet(PRIVATE_KEY, provider);
-     * ```
+     *
+     * @example Browser:
+     * const wallet = new RYTWallet(signer);
      */
-    constructor(privateKey: string, provider?: RYTProvider);
+    constructor(signerOrPrivateKey: string | ethers.Signer, provider?: RYTProvider);
     /**
-     * Returns the wallet address
+     * Get wallet address.
      *
      * @returns Wallet public address
      *
      * @example
-     * ```ts
-     * const address = wallet.getAddress();
-     * ```
+     * const address = await wallet.getAddress();
      */
-    getAddress(): string;
+    getAddress(): Promise<string>;
     /**
-     * Get wallet balance in wei
+     * Get wallet balance in wei.
      *
-     * @returns Promise resolving to balance (bigint)
+     * Requires connected provider (RPC or injected).
      *
-     * @throws Error if provider is not connected
+     * @returns Balance in wei
      *
-     * @example
-     * ```ts
-     * const balance = await wallet.getBalance();
-     * ```
+     * @throws Error if provider is not available
      */
     getBalance(): Promise<bigint>;
     /**
-     * Send a signed transaction
+     * Send a blockchain transaction.
      *
-     * @param tx - Transaction object (to, value, data, etc.)
-     * @returns Promise resolving to transaction response
+     * Works in both:
+     * - Backend (signed via private key)
+     * - Browser (signed via MetaMask / injected wallet)
+     *
+     * @param tx Transaction request object
+     * @returns Transaction response
      *
      * @example
-     * ```ts
      * await wallet.sendTransaction({
-     *   to: "0xabc...",
-     *   value: ethers.parseEther("0.01")
+     *   to: "0x...",
+     *   value: "0.01"
      * });
-     * ```
      */
     sendTransaction(tx: TxRequest): Promise<ethers.TransactionResponse>;
+    /**
+     * Check if wallet is connected to a provider.
+     *
+     * @returns true if provider is available
+     */
+    isConnected(): boolean;
+    /**
+     * Get underlying signer instance.
+     *
+     * Useful for advanced contract interactions.
+     */
+    getSigner(): ethers.Signer;
 }