ryt-sdk 1.0.8 → 1.0.10

package/dist/config.d.ts

@@ -1,39 +1,102 @@
-/**
- * Configuration options for initializing the RYT SDK
- */
 export interface SDKConfig {
     /**
-     * Chain ID of the target blockchain network
-     * @example 1 (Ethereum Mainnet), 137 (Polygon)
+     * Chain ID of the target blockchain network.
+     *
+     * This determines which network the SDK will interact with.
+     * Must match the EVM chain ID of the connected network.
+     *
+     * @example 1 (Ethereum Mainnet)
+     * @example 137 (Polygon)
+     * @example 247 (Custom testnet)
      */
     chainId: number;
     /**
-     * List of RPC endpoints used to communicate with the blockchain
-     * The SDK may use fallback logic if multiple URLs are provided
-     * @example ["https://rpc1.example.com", "https://rpc2.example.com"]
+     * List of RPC endpoints used for blockchain communication.
+     *
+     * - Required in Node.js environments
+     * - Used as fallback when no injected wallet is available in browser
+     * - The SDK may try multiple URLs for redundancy
+     *
+     * @example
+     * ["https://rpc1.example.com", "https://rpc2.example.com"]
      */
-    rpcUrls: string[];
+    rpcUrls?: string[];
     /**
-     * Optional block explorer base URL for the network
-     * Used to generate transaction/address links if provided
+     * Optional block explorer base URL.
+     *
+     * Used to generate transaction or address links in UI.
+     *
      * @example "https://etherscan.io"
+     * @example "https://polygonscan.com"
      */
     explorer?: string;
+    /**
+     * Enables browser wallet support.
+     *
+     * If enabled, SDK will attempt to use:
+     * - window.ethereum (MetaMask, Rabby, etc.)
+     *
+     * If disabled, SDK will strictly use RPC provider.
+     *
+     * @default true
+     */
+    enableBrowserWallet?: boolean;
+    /**
+     * Prefer injected wallet provider (window.ethereum) over RPC.
+     *
+     * When true:
+     * - Browser wallets are prioritized
+     * - RPC is used only as fallback
+     *
+     * @default true
+     */
+    preferInjectedProvider?: boolean;
 }
 /**
- * Validates and normalizes SDK configuration
+ * Detects whether the SDK is running in a browser environment.
+ *
+ * This is used internally to:
+ * - Choose between injected wallet vs RPC provider
+ * - Prevent Node-only logic from running in frontend
+ *
+ * @returns {boolean}
+ * true if running in browser AND MetaMask (or injected wallet) is available
+ *
+ * @example
+ * if (isBrowser()) {
+ *   console.log("Running in frontend dApp mode");
+ * }
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Validates and normalizes SDK configuration.
+ *
+ * This function ensures:
+ * - Required fields are present
+ * - Chain ID is valid
+ * - RPC URLs are correctly formatted (when required)
+ * - Environment-specific rules are enforced
+ *
+ * It supports both:
+ * - Browser dApps (MetaMask / injected wallets)
+ * - Node.js backend scripts (RPC only)
+ *
+ * @param {SDKConfig} config - User-provided SDK configuration
  *
- * @param config - User-provided SDK configuration
- * @returns Validated and normalized configuration
+ * @returns {SDKConfig} - Normalized and validated configuration
  *
- * @throws Error if required fields are missing or invalid
+ * @throws {Error}
+ * - If config is missing
+ * - If chainId is invalid
+ * - If RPC URLs are missing in backend mode
+ * - If RPC URLs are malformed
+ * - If explorer URL is invalid
  *
  * @example
- * ```ts
  * const config = validateConfig({
- *   chainId: 1234,
- *   rpcUrls: ["http://localhost:8545"]
+ *   chainId: 247,
+ *   rpcUrls: ["https://rpc.testnet.io"],
+ *   explorer: "https://explorer.testnet.io",
  * });
- * ```
  */
 export declare function validateConfig(config: SDKConfig): SDKConfig;

package/dist/config.js

@@ -1,18 +1,52 @@
+import { hasRYT } from "./utils/ryt";
 /**
- * Validates and normalizes SDK configuration
+ * Detects whether the SDK is running in a browser environment.
  *
- * @param config - User-provided SDK configuration
- * @returns Validated and normalized configuration
+ * This is used internally to:
+ * - Choose between injected wallet vs RPC provider
+ * - Prevent Node-only logic from running in frontend
  *
- * @throws Error if required fields are missing or invalid
+ * @returns {boolean}
+ * true if running in browser AND MetaMask (or injected wallet) is available
+ *
+ * @example
+ * if (isBrowser()) {
+ *   console.log("Running in frontend dApp mode");
+ * }
+ */
+export function isBrowser() {
+    return typeof window !== "undefined";
+}
+/**
+ * Validates and normalizes SDK configuration.
+ *
+ * This function ensures:
+ * - Required fields are present
+ * - Chain ID is valid
+ * - RPC URLs are correctly formatted (when required)
+ * - Environment-specific rules are enforced
+ *
+ * It supports both:
+ * - Browser dApps (MetaMask / injected wallets)
+ * - Node.js backend scripts (RPC only)
+ *
+ * @param {SDKConfig} config - User-provided SDK configuration
+ *
+ * @returns {SDKConfig} - Normalized and validated configuration
+ *
+ * @throws {Error}
+ * - If config is missing
+ * - If chainId is invalid
+ * - If RPC URLs are missing in backend mode
+ * - If RPC URLs are malformed
+ * - If explorer URL is invalid
  *
  * @example
- * ```ts
  * const config = validateConfig({
- *   chainId: 1234,
- *   rpcUrls: ["http://localhost:8545"]
+ *   chainId: 247,
+ *   rpcUrls: ["https://rpc.testnet.io"],
+ *   explorer: "https://explorer.testnet.io",
  * });
- * ```
  */
 export function validateConfig(config) {
     if (!config) {
@@ -21,17 +55,49 @@ export function validateConfig(config) {
     if (typeof config.chainId !== "number" || isNaN(config.chainId)) {
         throw new Error("Invalid chainId: must be a valid number");
     }
-    if (!Array.isArray(config.rpcUrls) || config.rpcUrls.length === 0) {
-        throw new Error("rpcUrls must be a non-empty array");
+    const enableBrowserWallet = config.enableBrowserWallet ?? true;
+    const preferInjectedProvider = config.preferInjectedProvider ?? true;
+    /**
+     * -----------------------------
+     * Frontend (Browser) validation
+     * -----------------------------
+     * Ensures at least one provider is available:
+     * - MetaMask (window.ethereum)
+     * - OR RPC fallback
+     */
+    if (isBrowser() && enableBrowserWallet) {
+        if (!hasRYT() && (!config.rpcUrls || config.rpcUrls.length === 0)) {
+            throw new Error("No injected wallet detected and no RPC fallback provided");
+        }
     }
-    for (const url of config.rpcUrls) {
-        if (typeof url !== "string" || !url.startsWith("http")) {
-            throw new Error(`Invalid RPC URL: ${url}`);
+    /**
+     * -----------------------------
+     * Backend validation (Node.js)
+     * -----------------------------
+     * RPC is mandatory in backend mode.
+     */
+    if (!isBrowser()) {
+        if (!config.rpcUrls || config.rpcUrls.length === 0) {
+            throw new Error("rpcUrls are required in backend mode");
+        }
+        for (const url of config.rpcUrls) {
+            if (typeof url !== "string" || !url.startsWith("http")) {
+                throw new Error(`Invalid RPC URL: ${url}`);
+            }
         }
     }
-    if (config.explorer !== undefined &&
-        (typeof config.explorer !== "string" || config.explorer.length === 0)) {
-        throw new Error("explorer must be a valid URL string if provided");
+    /**
+     * Explorer validation (optional field)
+     */
+    if (config.explorer &&
+        (typeof config.explorer !== "string" || config.explorer.length < 5)) {
+        throw new Error("Invalid explorer URL");
     }
-    return config;
+    return {
+        chainId: config.chainId,
+        rpcUrls: config.rpcUrls,
+        explorer: config.explorer,
+        enableBrowserWallet,
+        preferInjectedProvider,
+    };
 }

package/dist/contract.d.ts

@@ -67,7 +67,9 @@ export interface LibraryDeployOptions {
  * ----------------------------------------------------
  *
  * Supports:
- * - Read / Write contract calls
+ * - Read / Write contract calls (frontend + backend)
+ * - Browser wallet interactions (MetaMask, injected wallets)
+ * - Server-side wallet usage (private key)
  * - CREATE deployment
  * - CREATE2 deployment
  * - Minimal proxy (EIP-1167)
@@ -80,23 +82,32 @@ export default class RYTContract {
     /**
      * Create a new contract instance
      *
+     * Works in:
+     * - Browser (injected wallet signer)
+     * - Backend (private key wallet)
+     * - Read-only mode (RPC provider)
+     *
      * @param address - deployed contract address (optional)
      * @param abi - contract ABI
-     * @param signerOrProvider - wallet or provider instance
+     * @param signerOrProvider - wallet, signer or provider
      */
-    constructor(address: string | null, abi: any[], signerOrProvider: RYTWallet | ethers.Provider | any);
+    constructor(address: string | null, abi: any[], signerOrProvider: RYTWallet | ethers.Signer | ethers.Provider | any);
     /**
      * Call a read-only contract method
      *
-     * @param method - contract function name
+     * @param method - function name
      * @param params - function arguments
-     * @returns result of contract call
+     * @returns contract result
      */
     read(method: string, ...params: any[]): Promise<any>;
     /**
      * Call a state-changing contract method
      *
-     * @param method - contract function name
+     * Works with:
+     * - MetaMask / browser wallets
+     * - Backend private key wallets
+     *
+     * @param method - function name
      * @param params - function arguments
      * @returns transaction response
      */
@@ -104,7 +115,7 @@ export default class RYTContract {
     /**
      * Deploy a contract using CREATE opcode
      *
-     * @param options - deployment options
+     * @param options - deployment options (Requires signer (browser or backend wallet))
      * @returns updated contract instance
      */
     deploy(options: DeployOptions): Promise<this>;

package/dist/contract.js

@@ -5,11 +5,6 @@ import ERC1967Proxy from "@openzeppelin/contracts/build/contracts/ERC1967Proxy.j
  * -----------------------------
  * Internal helper: Link libraries into bytecode
  * -----------------------------
- *
- * @param bytecode - raw contract bytecode
- * @param linkReferences - compiler link references
- * @param libraries - deployed library addresses
- * @returns linked bytecode string
  */
 async function linkLibraries(bytecode, linkReferences, libraries) {
     let linked = bytecode.startsWith("0x") ? bytecode.slice(2) : bytecode;
@@ -34,7 +29,7 @@ async function linkLibraries(bytecode, linkReferences, libraries) {
         linked =
             linked.slice(0, start * 2) +
                 address.padStart(length * 2, "0") +
-                linked.slice((start + length) * 2);
+                linked.slice((start + (length - 1)) * 2);
     }
     return linked;
 }
@@ -44,7 +39,9 @@ async function linkLibraries(bytecode, linkReferences, libraries) {
  * ----------------------------------------------------
  *
  * Supports:
- * - Read / Write contract calls
+ * - Read / Write contract calls (frontend + backend)
+ * - Browser wallet interactions (MetaMask, injected wallets)
+ * - Server-side wallet usage (private key)
  * - CREATE deployment
  * - CREATE2 deployment
  * - Minimal proxy (EIP-1167)
@@ -55,15 +52,24 @@ export default class RYTContract {
     /**
      * Create a new contract instance
      *
+     * Works in:
+     * - Browser (injected wallet signer)
+     * - Backend (private key wallet)
+     * - Read-only mode (RPC provider)
+     *
      * @param address - deployed contract address (optional)
      * @param abi - contract ABI
-     * @param signerOrProvider - wallet or provider instance
+     * @param signerOrProvider - wallet, signer or provider
      */
     constructor(address, abi, signerOrProvider) {
-        this.wallet = signerOrProvider instanceof RYTWallet ? signerOrProvider : null;
+        this.wallet =
+            signerOrProvider instanceof RYTWallet ? signerOrProvider : null;
         const provider = signerOrProvider?.getProvider?.() || signerOrProvider;
+        const signer = signerOrProvider instanceof RYTWallet
+            ? signerOrProvider.getSigner()
+            : signerOrProvider;
         this.contract = address
-            ? new ethers.Contract(address, abi, this.wallet ? this.wallet["wallet"] : provider)
+            ? new ethers.Contract(address, abi, signer ?? provider)
             : null;
     }
     // ----------------------------------------------------
@@ -72,9 +78,9 @@ export default class RYTContract {
     /**
      * Call a read-only contract method
      *
-     * @param method - contract function name
+     * @param method - function name
      * @param params - function arguments
-     * @returns result of contract call
+     * @returns contract result
      */
     read(method, ...params) {
         if (!this.contract)
@@ -84,7 +90,11 @@ export default class RYTContract {
     /**
      * Call a state-changing contract method
      *
-     * @param method - contract function name
+     * Works with:
+     * - MetaMask / browser wallets
+     * - Backend private key wallets
+     *
+     * @param method - function name
      * @param params - function arguments
      * @returns transaction response
      */
@@ -99,16 +109,15 @@ export default class RYTContract {
     /**
      * Deploy a contract using CREATE opcode
      *
-     * @param options - deployment options
+     * @param options - deployment options (Requires signer (browser or backend wallet))
      * @returns updated contract instance
      */
     async deploy(options) {
         if (!this.wallet)
             throw new Error("Wallet required for deploy");
-        const factory = new ethers.ContractFactory(options.abi, options.bytecode, this.wallet["wallet"]);
-        const contract = await factory.deploy(...(options.args ?? []), {
-            value: options.value ?? 0,
-        });
+        const signer = this.wallet["getSigner"]?.() || this.wallet.getSigner();
+        const factory = new ethers.ContractFactory(options.abi, options.bytecode, signer);
+        const contract = await factory.deploy(...(options.args ?? []), { value: options.value ?? 0 });
         await contract.waitForDeployment();
         this.contract = contract;
         return this;
@@ -125,6 +134,7 @@ export default class RYTContract {
     async deployCreate2(options) {
         if (!this.wallet)
             throw new Error("Wallet required for deployCreate2");
+        const signer = this.wallet["getSigner"]?.() || this.wallet.getSigner();
         const encodedArgs = options.args && options.args.length > 0
             ? new ethers.Interface(options.abi).encodeDeploy(options.args)
             : "0x";
@@ -134,13 +144,11 @@ export default class RYTContract {
         ]);
         const factory = new ethers.Contract(options.factoryAddress, [
             "function deploy(bytes32 salt, bytes code) external payable returns (address)",
-        ], this.wallet["wallet"]);
+        ], signer);
         const addr = ethers.getCreate2Address(options.factoryAddress, options.salt, ethers.keccak256(creationCode));
-        const tx = options.value && options.value > 0
-            ? await factory.deploy(options.salt, creationCode, {
-                value: options.value,
-            })
-            : await factory.deploy(options.salt, creationCode);
+        const tx = await factory.deploy(options.salt, creationCode, {
+            value: options.value ?? 0,
+        });
         return {
             receipt: await tx.wait(),
             contractHash: addr,
@@ -158,13 +166,12 @@ export default class RYTContract {
     async deployClone(implementationAddress) {
         if (!this.wallet)
             throw new Error("Wallet required for deployClone");
+        const signer = this.wallet["getSigner"]?.() || this.wallet.getSigner();
         const bytecode = "0x3d602d80600a3d3981f3" +
             "363d3d373d3d3d363d73" +
             implementationAddress.slice(2) +
             "5af43d82803e903d91602b57fd5bf3";
-        const tx = await this.wallet["wallet"].sendTransaction({
-            data: bytecode,
-        });
+        const tx = await signer.sendTransaction({ data: bytecode });
         return await tx.wait();
     }
     // ----------------------------------------------------
@@ -179,17 +186,18 @@ export default class RYTContract {
     async deployUUPS(options) {
         if (!this.wallet)
             throw new Error("Wallet required for deployUUPS");
-        const implFactory = new ethers.ContractFactory(options.implementationAbi, options.implementationBytecode, this.wallet["wallet"]);
+        const signer = this.wallet["getSigner"]?.() || this.wallet.getSigner();
+        const implFactory = new ethers.ContractFactory(options.implementationAbi, options.implementationBytecode, signer);
         const impl = await implFactory.deploy();
         await impl.waitForDeployment();
         const implAddress = impl.target;
-        const proxyFactory = new ethers.ContractFactory(ERC1967Proxy.abi, ERC1967Proxy.bytecode, this.wallet["wallet"]);
+        const proxyFactory = new ethers.ContractFactory(ERC1967Proxy.abi, ERC1967Proxy.bytecode, signer);
         const proxy = await proxyFactory.deploy(implAddress, options.initData ?? "0x");
         await proxy.waitForDeployment();
         return new RYTContract(proxy.target, options.implementationAbi, this.wallet);
     }
     // ----------------------------------------------------
-    // Library-linked deployment
+    // Library-linked deployment (UNCHANGED STYLE)
     // ----------------------------------------------------
     /**
      * Deploy contract with Solidity libraries linked

package/dist/index.d.ts

@@ -1,38 +1,77 @@
+import { getRYT, hasRYT, requestAccounts } from "./utils/ryt";
+export { parseTokenUnits, formatTokenUnits } from "./utils/units";
 /**
  * ------------------------------------------------------
  * RYT SDK - Public Entry Point
  * ------------------------------------------------------
  *
- * This file exposes the main SDK modules:
- * - Provider (RPC layer)
- * - Wallet (signing layer)
- * - Contract (smart contract interaction layer)
+ * Exposes core SDK modules for:
+ * - Blockchain interaction (Provider)
+ * - Wallet management (Wallet)
+ * - Smart contracts (Contract layer)
  *
- * This is the ONLY file users should import from:
- *
- * @example
- * ```ts
- * import { RYTProvider, RYTWallet, RYTContract } from "ryt-sdk";
- * ```
+ * Works in:
+ * - Browser (MetaMask / injected wallets)
+ * - Node.js (RPC-based flows)
  */
 /**
- * Provider module for RPC interactions
+ * ------------------------------------------------------
+ * Core Modules
+ * ------------------------------------------------------
  */
 export { default as RYTProvider } from "./provider";
+export { default as RYTWallet } from "./wallet";
+export { default as RYTContract } from "./contract";
 /**
- * Wallet module for signing transactions
+ * ------------------------------------------------------
+ * Browser / Wallet Utilities
+ * ------------------------------------------------------
  */
-export { default as RYTWallet } from "./wallet";
 /**
- * Contract module for smart contract interactions
+ * Gets injected wallet provider (MetaMask, Rabby, etc.)
+ *
+ * @returns EIP-1193 provider or undefined
+ *
+ * @example
+ * const provider = getRYT();
  */
-export { default as RYTContract } from "./contract";
+export { getRYT };
+/**
+ * Checks if injected wallet is available in browser.
+ *
+ * @returns true if wallet is detected
+ *
+ * @example
+ * if (hasRYT()) console.log("Wallet ready");
+ */
+export { hasRYT };
+/**
+ * Requests wallet connection (opens MetaMask popup).
+ *
+ * @returns list of connected addresses
+ *
+ * @example
+ * const accounts = await requestAccounts();
+ */
+export { requestAccounts };
 /**
  * ------------------------------------------------------
- * Optional: Future unified SDK export (recommended)
+ * Convenience helpers (SDK-level safe checks)
  * ------------------------------------------------------
+ */
+/**
+ * Checks if running in browser environment.
  *
- * Uncomment when you want a single entry API:
+ * @returns true if window is available
+ */
+export declare const isBrowser: () => boolean;
+/**
+ * Checks if wallet is ready for use.
+ *
+ * Combines:
+ * - browser check
+ * - injected wallet check
  *
- * export { default as RYTClient } from "./client";
- */ 
+ * @returns true if wallet can be used
+ */
+export declare const isWalletAvailable: () => boolean;

package/dist/index.js

@@ -1,38 +1,81 @@
+import { getRYT, hasRYT, requestAccounts } from "./utils/ryt";
+export { parseTokenUnits, formatTokenUnits } from "./utils/units";
 /**
  * ------------------------------------------------------
  * RYT SDK - Public Entry Point
  * ------------------------------------------------------
  *
- * This file exposes the main SDK modules:
- * - Provider (RPC layer)
- * - Wallet (signing layer)
- * - Contract (smart contract interaction layer)
+ * Exposes core SDK modules for:
+ * - Blockchain interaction (Provider)
+ * - Wallet management (Wallet)
+ * - Smart contracts (Contract layer)
  *
- * This is the ONLY file users should import from:
- *
- * @example
- * ```ts
- * import { RYTProvider, RYTWallet, RYTContract } from "ryt-sdk";
- * ```
+ * Works in:
+ * - Browser (MetaMask / injected wallets)
+ * - Node.js (RPC-based flows)
  */
 /**
- * Provider module for RPC interactions
+ * ------------------------------------------------------
+ * Core Modules
+ * ------------------------------------------------------
  */
 export { default as RYTProvider } from "./provider";
+export { default as RYTWallet } from "./wallet";
+export { default as RYTContract } from "./contract";
 /**
- * Wallet module for signing transactions
+ * ------------------------------------------------------
+ * Browser / Wallet Utilities
+ * ------------------------------------------------------
  */
-export { default as RYTWallet } from "./wallet";
 /**
- * Contract module for smart contract interactions
+ * Gets injected wallet provider (MetaMask, Rabby, etc.)
+ *
+ * @returns EIP-1193 provider or undefined
+ *
+ * @example
+ * const provider = getRYT();
  */
-export { default as RYTContract } from "./contract";
+export { getRYT };
+/**
+ * Checks if injected wallet is available in browser.
+ *
+ * @returns true if wallet is detected
+ *
+ * @example
+ * if (hasRYT()) console.log("Wallet ready");
+ */
+export { hasRYT };
+/**
+ * Requests wallet connection (opens MetaMask popup).
+ *
+ * @returns list of connected addresses
+ *
+ * @example
+ * const accounts = await requestAccounts();
+ */
+export { requestAccounts };
 /**
  * ------------------------------------------------------
- * Optional: Future unified SDK export (recommended)
+ * Convenience helpers (SDK-level safe checks)
  * ------------------------------------------------------
+ */
+/**
+ * Checks if running in browser environment.
  *
- * Uncomment when you want a single entry API:
+ * @returns true if window is available
+ */
+export const isBrowser = () => {
+    return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+};
+/**
+ * Checks if wallet is ready for use.
+ *
+ * Combines:
+ * - browser check
+ * - injected wallet check
  *
- * export { default as RYTClient } from "./client";
- */ 
+ * @returns true if wallet can be used
+ */
+export const isWalletAvailable = () => {
+    return isBrowser() && hasRYT();
+};