@tychilabs/stonfi-gasless-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tychi Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# STON.fi Gasless SDK
+
+[![npm version](https://img.shields.io/npm/v/@tychilabs/stonfi-gasless-sdk.svg)](https://www.npmjs.com/package/@tychilabs/stonfi-gasless-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Universal Gas Framework SDK for paying TON transaction fees with STON tokens.
+
+**By Tychi Labs**
+
+## Overview
+
+The STON.fi Gasless SDK enables developers to build applications where users pay transaction fees with STON tokens instead of TON. This eliminates the friction of requiring users to hold native tokens for gas, making blockchain interactions more accessible and user-friendly.
+
+## Why UGF?
+
+Traditional blockchain transactions create barriers for new users who must acquire native tokens just to pay gas fees. Universal Gas Framework solves this by:
+
+- **Simplifying User Experience** - Users can transact using only STON tokens, removing the need to manage multiple token types
+- **Supporting DeFi Ecosystem** - Locked STON provides liquidity to STON.fi, strengthening the broader ecosystem
+- **Enabling Gasless Flows** - Developers can create seamless onboarding experiences where users never think about gas fees
+- **Maintaining Security** - All transactions are cryptographically signed and verified on-chain
+
+Whether you're building a DEX, NFT marketplace, or any dApp on TON, UGF enables truly gasless user experiences while leveraging STON's liquidity.
+
+## How It Works
+
+1. Users lock STON tokens in the UGF escrow contract
+2. Locked STON becomes an x402 balance used for gas payments
+3. Your application requests a quote via the SDK
+4. User signs the payment digest
+5. UGF verifies the signature and deducts STON
+6. The contract pays TON gas fees on the user's behalf
+7. Transaction executes seamlessly
+
+No relaying, no wrapped tokens - just direct gas payment with STON.
+
+## Installation
+
+```bash
+npm install @tychilabs/stonfi-gasless-sdk
+```
+
+## Requirements
+
+- Node.js 16 or higher
+- `@ton/core` >= 0.63.0 (peer dependency)
+- API Key - Contact us at support@tychilabs.com to get started
+
+## Features
+
+- **STON Gas Payments** - Pay transaction fees with STON instead of TON
+- **Cryptographic Signing** - Built-in utilities for digest signing and verification
+- **Full TypeScript Support** - Complete type definitions for all API interactions
+- **Simple, Intuitive API** - Clean interfaces that follow modern JavaScript patterns
+- **Comprehensive Error Handling** - Typed error classes for precise error management
+- **Production Ready** - Battle-tested code with proper validation and security measures
+
+## Documentation
+
+Complete guides and references to get you started:
+
+- [Quick Start Guide](./docs/QUICKSTART.md) - Get up and running in 5 minutes
+- [API Reference](./docs/API.md) - Detailed documentation of all SDK methods
+
+## Use Cases
+
+- **DEX Integrations** - Enable token swaps without requiring TON for gas
+- **NFT Marketplaces** - Let users mint and trade NFTs using only STON
+- **Gaming dApps** - Simplify in-game transactions by eliminating gas fee complexity
+- **Onboarding Flows** - Create seamless signup experiences without native token requirements
+- **DeFi Applications** - Build lending, staking, or yield farming platforms with gasless UX
+
+## Coming Soon
+
+**ston.universalgasframework.com** - Self-service portal for API key management, analytics, and monitoring
+
+## Getting Help
+
+We're here to support your integration:
+
+- **Technical Issues** - [GitHub Issues](https://github.com/TychiWallet/stonfi-gasless-sdk/issues)
+- **Integration Support** - Email us at yash@tychilabs.com
+- **Feature Requests** - Open a discussion on GitHub
+
+## Contributing
+
+We welcome contributions from the community. Please see our contributing guidelines and feel free to submit issues or pull requests.
+
+## License
+
+MIT © Tychi Labs

package/dist/index.cjs

@@ -0,0 +1,369 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_CONFIG: () => DEFAULT_CONFIG,
+  GasLimitExceededError: () => GasLimitExceededError,
+  InsufficientBalanceError: () => InsufficientBalanceError,
+  InvalidChainError: () => InvalidChainError,
+  InvalidPaymentCoinError: () => InvalidPaymentCoinError,
+  InvalidSignatureError: () => InvalidSignatureError,
+  MissingDigestError: () => MissingDigestError,
+  NetworkError: () => NetworkError,
+  PayerMismatchError: () => PayerMismatchError,
+  QuoteExpiredError: () => QuoteExpiredError,
+  QuoteNotFoundError: () => QuoteNotFoundError,
+  StatusNotFoundError: () => StatusNotFoundError,
+  UGFClient: () => UGFClient,
+  UGFError: () => UGFError,
+  UnauthorizedError: () => UnauthorizedError,
+  formatSTON: () => formatSTON,
+  fromNano: () => fromNano,
+  isValidBufferPct: () => isValidBufferPct,
+  isValidGasEstimate: () => isValidGasEstimate,
+  isValidHex: () => isValidHex,
+  isValidTONAddress: () => isValidTONAddress,
+  parseBackendError: () => parseBackendError,
+  signDigest: () => signDigest,
+  toNano: () => toNano,
+  verifySignature: () => verifySignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/errors.ts
+var UGFError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "UGFError";
+  }
+};
+var QuoteNotFoundError = class extends UGFError {
+  constructor() {
+    super("quote not found or expired", "QUOTE_NOT_FOUND");
+  }
+};
+var QuoteExpiredError = class extends UGFError {
+  constructor() {
+    super("quote expired", "QUOTE_EXPIRED");
+  }
+};
+var PayerMismatchError = class extends UGFError {
+  constructor() {
+    super("payer mismatch", "PAYER_MISMATCH");
+  }
+};
+var InvalidSignatureError = class extends UGFError {
+  constructor() {
+    super("invalid signature", "INVALID_SIGNATURE");
+  }
+};
+var InsufficientBalanceError = class extends UGFError {
+  constructor() {
+    super("insufficient locked balance", "INSUFFICIENT_BALANCE");
+  }
+};
+var InvalidChainError = class extends UGFError {
+  constructor() {
+    super("invalid chain", "INVALID_CHAIN");
+  }
+};
+var InvalidPaymentCoinError = class extends UGFError {
+  constructor() {
+    super("invalid payment coin", "INVALID_COIN");
+  }
+};
+var GasLimitExceededError = class extends UGFError {
+  constructor() {
+    super("gas exceeds 0.5 TON limit", "GAS_LIMIT_EXCEEDED");
+  }
+};
+var MissingDigestError = class extends UGFError {
+  constructor() {
+    super("missing digest", "MISSING_DIGEST");
+  }
+};
+var StatusNotFoundError = class extends UGFError {
+  constructor() {
+    super("status not found", "STATUS_NOT_FOUND");
+  }
+};
+var UnauthorizedError = class extends UGFError {
+  constructor() {
+    super("unauthorized", "UNAUTHORIZED");
+  }
+};
+var NetworkError = class extends UGFError {
+  constructor(message = "network error") {
+    super(message, "NETWORK_ERROR");
+  }
+};
+function parseBackendError(message) {
+  const lowerMsg = message.toLowerCase();
+  if (lowerMsg.includes("quote not found") || lowerMsg.includes("expired")) {
+    return new QuoteNotFoundError();
+  }
+  if (lowerMsg.includes("quote expired")) {
+    return new QuoteExpiredError();
+  }
+  if (lowerMsg.includes("payer mismatch")) {
+    return new PayerMismatchError();
+  }
+  if (lowerMsg.includes("invalid signature")) {
+    return new InvalidSignatureError();
+  }
+  if (lowerMsg.includes("insufficient")) {
+    return new InsufficientBalanceError();
+  }
+  if (lowerMsg.includes("invalid chain")) {
+    return new InvalidChainError();
+  }
+  if (lowerMsg.includes("invalid payment coin")) {
+    return new InvalidPaymentCoinError();
+  }
+  if (lowerMsg.includes("gas exceeds")) {
+    return new GasLimitExceededError();
+  }
+  if (lowerMsg.includes("missing digest")) {
+    return new MissingDigestError();
+  }
+  if (lowerMsg.includes("status not found")) {
+    return new StatusNotFoundError();
+  }
+  if (lowerMsg.includes("unauthorized")) {
+    return new UnauthorizedError();
+  }
+  return new NetworkError(message);
+}
+
+// src/api/quote.ts
+async function getQuote(apiUrl, request, apiKey) {
+  const res = await fetch(`${apiUrl}/quote`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    },
+    body: JSON.stringify(request)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/api/payment.ts
+async function submitPayment(apiUrl, request, apiKey) {
+  const res = await fetch(`${apiUrl}/payment/submit`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    },
+    body: JSON.stringify(request)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/api/status.ts
+async function getPaymentStatus(apiUrl, digest, apiKey) {
+  const res = await fetch(`${apiUrl}/payment/status?digest=${digest}`, {
+    headers: {
+      "X-API-Key": apiKey
+    }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/api/info.ts
+async function getSTONInfo(apiUrl, address, apiKey) {
+  const res = await fetch(`${apiUrl}/ston/info/${address}`, {
+    headers: {
+      "X-API-Key": apiKey
+    }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/core/client.ts
+var UGFClient = class {
+  /**
+   * Create a new UGF client
+   * @param config - Configuration with API URL and optional API key
+   */
+  constructor(config) {
+    this.apiUrl = config.apiUrl;
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Get a quote for gasless payment
+   * @param request - Quote request parameters
+   * @returns Quote with digest and payment details
+   */
+  async getQuote(request) {
+    return getQuote(this.apiUrl, request, this.apiKey);
+  }
+  /**
+   * Submit a signed payment
+   * @param request - Payment submission with signature
+   * @returns Payment status
+   */
+  async submitPayment(request) {
+    return submitPayment(this.apiUrl, request, this.apiKey);
+  }
+  /**
+   * Check payment status
+   * @param digest - Payment digest
+   * @returns Current payment status
+   */
+  async getPaymentStatus(digest) {
+    return getPaymentStatus(this.apiUrl, digest, this.apiKey);
+  }
+  /**
+   * Get user's STON balance info
+   * @param address - User's TON address
+   * @returns STON and x402 balance details
+   */
+  async getSTONInfo(address) {
+    return getSTONInfo(this.apiUrl, address, this.apiKey);
+  }
+};
+
+// src/core/config.ts
+var DEFAULT_CONFIG = {
+  apiUrl: "https://stonfi.universalgasframework.com"
+};
+
+// src/utils/formatting.ts
+function toNano(amount) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  return Math.floor(num * 1e9).toString();
+}
+function fromNano(nanotons, decimals = 6) {
+  const num = typeof nanotons === "string" ? parseFloat(nanotons) : nanotons;
+  return (num / 1e9).toFixed(decimals);
+}
+function formatSTON(amount, decimals = 2) {
+  return parseFloat(fromNano(amount)).toFixed(decimals);
+}
+
+// src/utils/validation.ts
+var import_core = require("@ton/core");
+function isValidTONAddress(address) {
+  try {
+    import_core.Address.parse(address);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isValidHex(hex) {
+  return /^[0-9a-fA-F]+$/.test(hex) && hex.length % 2 === 0;
+}
+function isValidGasEstimate(nanotons) {
+  return nanotons > 0 && nanotons <= 5e8;
+}
+function isValidBufferPct(pct) {
+  return pct >= 0 && pct <= 50;
+}
+
+// src/crypto/signature.ts
+var import_tweetnacl = __toESM(require("tweetnacl"), 1);
+function signDigest(digestHex, privateKeyHex) {
+  const digest = hexToBytes(digestHex);
+  const secretKey = hexToBytes(privateKeyHex);
+  const signature = import_tweetnacl.default.sign.detached(digest, secretKey);
+  return bytesToHex(signature);
+}
+function verifySignature(digestHex, signatureHex, publicKeyHex) {
+  const digest = hexToBytes(digestHex);
+  const signature = hexToBytes(signatureHex);
+  const publicKey = hexToBytes(publicKeyHex);
+  return import_tweetnacl.default.sign.detached.verify(digest, signature, publicKey);
+}
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CONFIG,
+  GasLimitExceededError,
+  InsufficientBalanceError,
+  InvalidChainError,
+  InvalidPaymentCoinError,
+  InvalidSignatureError,
+  MissingDigestError,
+  NetworkError,
+  PayerMismatchError,
+  QuoteExpiredError,
+  QuoteNotFoundError,
+  StatusNotFoundError,
+  UGFClient,
+  UGFError,
+  UnauthorizedError,
+  formatSTON,
+  fromNano,
+  isValidBufferPct,
+  isValidGasEstimate,
+  isValidHex,
+  isValidTONAddress,
+  parseBackendError,
+  signDigest,
+  toNano,
+  verifySignature
+});

package/dist/index.d.cts

@@ -0,0 +1,218 @@
+/**
+ * UGF client configuration
+ */
+interface UGFConfig {
+    /** UGF API base URL */
+    apiUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: Partial<UGFConfig>;
+
+/**
+ * Request to get a gasless payment quote
+ */
+interface QuoteRequest {
+    /** Payment token (always "STON") */
+    payment_coin: string;
+    /** User's TON wallet address */
+    payer_address: string;
+    /** Blockchain network (always "TON") */
+    payment_chain: string;
+    /** Optional transaction object */
+    tx_object?: string;
+    /** Destination chain ID (always "TON") */
+    dest_chain_id: string;
+    /** Gas estimate in nanotons */
+    gas_ton_estimate: number;
+    /** Buffer percentage (0-50, default 0) */
+    buffer_pct?: number;
+}
+/**
+ * Response containing quote details and payment digest
+ */
+interface QuoteResponse {
+    /** STON amount required for payment (in nanotons) */
+    payment_amount: string;
+    /** Payment token (STON) */
+    payment_coin: string;
+    /** Payment blockchain (TON) */
+    payment_chain: string;
+    /** Payment destination address */
+    payment_to: string;
+    /** Payment mode identifier */
+    payment_mode: string;
+    /** Gas amount in nanotons */
+    gas_amount: string;
+    /** Unique digest for this quote */
+    digest: string;
+    /** Unix timestamp when quote expires */
+    expires_at: number;
+    /** User's locked x402 STON balance */
+    locked_x402_ston_balance: string;
+}
+
+interface PaymentRequest {
+    digest: string;
+    payer_address: string;
+    signature: string;
+    public_key: string;
+}
+interface PaymentResponse {
+    status: string;
+    digest: string;
+}
+
+interface StatusResponse {
+    status: "pending" | "completed" | "failed";
+    digest: string;
+}
+
+interface STONInfoResponse {
+    address: string;
+    ston_balance: string;
+    x402_ston_balance: string;
+    escrow_address: string;
+    min_bridge_ston: string;
+    cached: boolean;
+}
+
+/**
+ * Main UGF SDK client for interacting with the Universal Gas Framework API
+ */
+declare class UGFClient {
+    private apiUrl;
+    private apiKey;
+    /**
+     * Create a new UGF client
+     * @param config - Configuration with API URL and optional API key
+     */
+    constructor(config: UGFConfig);
+    /**
+     * Get a quote for gasless payment
+     * @param request - Quote request parameters
+     * @returns Quote with digest and payment details
+     */
+    getQuote(request: QuoteRequest): Promise<QuoteResponse>;
+    /**
+     * Submit a signed payment
+     * @param request - Payment submission with signature
+     * @returns Payment status
+     */
+    submitPayment(request: PaymentRequest): Promise<PaymentResponse>;
+    /**
+     * Check payment status
+     * @param digest - Payment digest
+     * @returns Current payment status
+     */
+    getPaymentStatus(digest: string): Promise<StatusResponse>;
+    /**
+     * Get user's STON balance info
+     * @param address - User's TON address
+     * @returns STON and x402 balance details
+     */
+    getSTONInfo(address: string): Promise<STONInfoResponse>;
+}
+
+/**
+ * Convert TON amount to nanotons
+ */
+declare function toNano(amount: string | number): string;
+/**
+ * Convert nanotons to TON
+ */
+declare function fromNano(nanotons: string | number, decimals?: number): string;
+/**
+ * Format STON amount (same as TON, 9 decimals)
+ */
+declare function formatSTON(amount: string, decimals?: number): string;
+
+/** Validate TON address format */
+declare function isValidTONAddress(address: string): boolean;
+/** Validate hex string */
+declare function isValidHex(hex: string): boolean;
+/** Validate gas estimate (must be > 0 and <= 0.5 TON) */
+declare function isValidGasEstimate(nanotons: number): boolean;
+/** Validate buffer percentage (0-50) */
+declare function isValidBufferPct(pct: number): boolean;
+
+/** Base error for all UGF SDK errors */
+declare class UGFError extends Error {
+    code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/** Quote not found or expired */
+declare class QuoteNotFoundError extends UGFError {
+    constructor();
+}
+/** Quote has expired */
+declare class QuoteExpiredError extends UGFError {
+    constructor();
+}
+/** Payer address doesn't match quote */
+declare class PayerMismatchError extends UGFError {
+    constructor();
+}
+/** Signature verification failed */
+declare class InvalidSignatureError extends UGFError {
+    constructor();
+}
+/** Insufficient x402 STON balance */
+declare class InsufficientBalanceError extends UGFError {
+    constructor();
+}
+/** Invalid blockchain chain */
+declare class InvalidChainError extends UGFError {
+    constructor();
+}
+/** Invalid payment coin type */
+declare class InvalidPaymentCoinError extends UGFError {
+    constructor();
+}
+/** Gas estimate exceeds 0.5 TON limit */
+declare class GasLimitExceededError extends UGFError {
+    constructor();
+}
+/** Missing digest parameter */
+declare class MissingDigestError extends UGFError {
+    constructor();
+}
+/** Payment status not found */
+declare class StatusNotFoundError extends UGFError {
+    constructor();
+}
+/** Invalid or missing API key */
+declare class UnauthorizedError extends UGFError {
+    constructor();
+}
+/** Network or server error */
+declare class NetworkError extends UGFError {
+    constructor(message?: string);
+}
+/**
+ * Parse backend error message and return specific error type
+ * @param message - Error message from backend
+ * @returns Specific error instance
+ */
+declare function parseBackendError(message: string): Error;
+
+/**
+ * Sign a digest with ed25519 private key
+ * @param digestHex - Hex string of digest to sign
+ * @param privateKeyHex - 64-byte ed25519 private key in hex
+ * @returns Signature as hex string
+ */
+declare function signDigest(digestHex: string, privateKeyHex: string): string;
+/**
+ * Verify a signature
+ * @param digestHex - Original digest
+ * @param signatureHex - Signature to verify
+ * @param publicKeyHex - 32-byte ed25519 public key in hex
+ * @returns True if valid
+ */
+declare function verifySignature(digestHex: string, signatureHex: string, publicKeyHex: string): boolean;
+
+export { DEFAULT_CONFIG, GasLimitExceededError, InsufficientBalanceError, InvalidChainError, InvalidPaymentCoinError, InvalidSignatureError, MissingDigestError, NetworkError, PayerMismatchError, type PaymentRequest, type PaymentResponse, QuoteExpiredError, QuoteNotFoundError, type QuoteRequest, type QuoteResponse, type STONInfoResponse, StatusNotFoundError, type StatusResponse, UGFClient, type UGFConfig, UGFError, UnauthorizedError, formatSTON, fromNano, isValidBufferPct, isValidGasEstimate, isValidHex, isValidTONAddress, parseBackendError, signDigest, toNano, verifySignature };

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+/**
+ * UGF client configuration
+ */
+interface UGFConfig {
+    /** UGF API base URL */
+    apiUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: Partial<UGFConfig>;
+
+/**
+ * Request to get a gasless payment quote
+ */
+interface QuoteRequest {
+    /** Payment token (always "STON") */
+    payment_coin: string;
+    /** User's TON wallet address */
+    payer_address: string;
+    /** Blockchain network (always "TON") */
+    payment_chain: string;
+    /** Optional transaction object */
+    tx_object?: string;
+    /** Destination chain ID (always "TON") */
+    dest_chain_id: string;
+    /** Gas estimate in nanotons */
+    gas_ton_estimate: number;
+    /** Buffer percentage (0-50, default 0) */
+    buffer_pct?: number;
+}
+/**
+ * Response containing quote details and payment digest
+ */
+interface QuoteResponse {
+    /** STON amount required for payment (in nanotons) */
+    payment_amount: string;
+    /** Payment token (STON) */
+    payment_coin: string;
+    /** Payment blockchain (TON) */
+    payment_chain: string;
+    /** Payment destination address */
+    payment_to: string;
+    /** Payment mode identifier */
+    payment_mode: string;
+    /** Gas amount in nanotons */
+    gas_amount: string;
+    /** Unique digest for this quote */
+    digest: string;
+    /** Unix timestamp when quote expires */
+    expires_at: number;
+    /** User's locked x402 STON balance */
+    locked_x402_ston_balance: string;
+}
+
+interface PaymentRequest {
+    digest: string;
+    payer_address: string;
+    signature: string;
+    public_key: string;
+}
+interface PaymentResponse {
+    status: string;
+    digest: string;
+}
+
+interface StatusResponse {
+    status: "pending" | "completed" | "failed";
+    digest: string;
+}
+
+interface STONInfoResponse {
+    address: string;
+    ston_balance: string;
+    x402_ston_balance: string;
+    escrow_address: string;
+    min_bridge_ston: string;
+    cached: boolean;
+}
+
+/**
+ * Main UGF SDK client for interacting with the Universal Gas Framework API
+ */
+declare class UGFClient {
+    private apiUrl;
+    private apiKey;
+    /**
+     * Create a new UGF client
+     * @param config - Configuration with API URL and optional API key
+     */
+    constructor(config: UGFConfig);
+    /**
+     * Get a quote for gasless payment
+     * @param request - Quote request parameters
+     * @returns Quote with digest and payment details
+     */
+    getQuote(request: QuoteRequest): Promise<QuoteResponse>;
+    /**
+     * Submit a signed payment
+     * @param request - Payment submission with signature
+     * @returns Payment status
+     */
+    submitPayment(request: PaymentRequest): Promise<PaymentResponse>;
+    /**
+     * Check payment status
+     * @param digest - Payment digest
+     * @returns Current payment status
+     */
+    getPaymentStatus(digest: string): Promise<StatusResponse>;
+    /**
+     * Get user's STON balance info
+     * @param address - User's TON address
+     * @returns STON and x402 balance details
+     */
+    getSTONInfo(address: string): Promise<STONInfoResponse>;
+}
+
+/**
+ * Convert TON amount to nanotons
+ */
+declare function toNano(amount: string | number): string;
+/**
+ * Convert nanotons to TON
+ */
+declare function fromNano(nanotons: string | number, decimals?: number): string;
+/**
+ * Format STON amount (same as TON, 9 decimals)
+ */
+declare function formatSTON(amount: string, decimals?: number): string;
+
+/** Validate TON address format */
+declare function isValidTONAddress(address: string): boolean;
+/** Validate hex string */
+declare function isValidHex(hex: string): boolean;
+/** Validate gas estimate (must be > 0 and <= 0.5 TON) */
+declare function isValidGasEstimate(nanotons: number): boolean;
+/** Validate buffer percentage (0-50) */
+declare function isValidBufferPct(pct: number): boolean;
+
+/** Base error for all UGF SDK errors */
+declare class UGFError extends Error {
+    code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/** Quote not found or expired */
+declare class QuoteNotFoundError extends UGFError {
+    constructor();
+}
+/** Quote has expired */
+declare class QuoteExpiredError extends UGFError {
+    constructor();
+}
+/** Payer address doesn't match quote */
+declare class PayerMismatchError extends UGFError {
+    constructor();
+}
+/** Signature verification failed */
+declare class InvalidSignatureError extends UGFError {
+    constructor();
+}
+/** Insufficient x402 STON balance */
+declare class InsufficientBalanceError extends UGFError {
+    constructor();
+}
+/** Invalid blockchain chain */
+declare class InvalidChainError extends UGFError {
+    constructor();
+}
+/** Invalid payment coin type */
+declare class InvalidPaymentCoinError extends UGFError {
+    constructor();
+}
+/** Gas estimate exceeds 0.5 TON limit */
+declare class GasLimitExceededError extends UGFError {
+    constructor();
+}
+/** Missing digest parameter */
+declare class MissingDigestError extends UGFError {
+    constructor();
+}
+/** Payment status not found */
+declare class StatusNotFoundError extends UGFError {
+    constructor();
+}
+/** Invalid or missing API key */
+declare class UnauthorizedError extends UGFError {
+    constructor();
+}
+/** Network or server error */
+declare class NetworkError extends UGFError {
+    constructor(message?: string);
+}
+/**
+ * Parse backend error message and return specific error type
+ * @param message - Error message from backend
+ * @returns Specific error instance
+ */
+declare function parseBackendError(message: string): Error;
+
+/**
+ * Sign a digest with ed25519 private key
+ * @param digestHex - Hex string of digest to sign
+ * @param privateKeyHex - 64-byte ed25519 private key in hex
+ * @returns Signature as hex string
+ */
+declare function signDigest(digestHex: string, privateKeyHex: string): string;
+/**
+ * Verify a signature
+ * @param digestHex - Original digest
+ * @param signatureHex - Signature to verify
+ * @param publicKeyHex - 32-byte ed25519 public key in hex
+ * @returns True if valid
+ */
+declare function verifySignature(digestHex: string, signatureHex: string, publicKeyHex: string): boolean;
+
+export { DEFAULT_CONFIG, GasLimitExceededError, InsufficientBalanceError, InvalidChainError, InvalidPaymentCoinError, InvalidSignatureError, MissingDigestError, NetworkError, PayerMismatchError, type PaymentRequest, type PaymentResponse, QuoteExpiredError, QuoteNotFoundError, type QuoteRequest, type QuoteResponse, type STONInfoResponse, StatusNotFoundError, type StatusResponse, UGFClient, type UGFConfig, UGFError, UnauthorizedError, formatSTON, fromNano, isValidBufferPct, isValidGasEstimate, isValidHex, isValidTONAddress, parseBackendError, signDigest, toNano, verifySignature };

package/dist/index.js

@@ -0,0 +1,308 @@
+// src/utils/errors.ts
+var UGFError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "UGFError";
+  }
+};
+var QuoteNotFoundError = class extends UGFError {
+  constructor() {
+    super("quote not found or expired", "QUOTE_NOT_FOUND");
+  }
+};
+var QuoteExpiredError = class extends UGFError {
+  constructor() {
+    super("quote expired", "QUOTE_EXPIRED");
+  }
+};
+var PayerMismatchError = class extends UGFError {
+  constructor() {
+    super("payer mismatch", "PAYER_MISMATCH");
+  }
+};
+var InvalidSignatureError = class extends UGFError {
+  constructor() {
+    super("invalid signature", "INVALID_SIGNATURE");
+  }
+};
+var InsufficientBalanceError = class extends UGFError {
+  constructor() {
+    super("insufficient locked balance", "INSUFFICIENT_BALANCE");
+  }
+};
+var InvalidChainError = class extends UGFError {
+  constructor() {
+    super("invalid chain", "INVALID_CHAIN");
+  }
+};
+var InvalidPaymentCoinError = class extends UGFError {
+  constructor() {
+    super("invalid payment coin", "INVALID_COIN");
+  }
+};
+var GasLimitExceededError = class extends UGFError {
+  constructor() {
+    super("gas exceeds 0.5 TON limit", "GAS_LIMIT_EXCEEDED");
+  }
+};
+var MissingDigestError = class extends UGFError {
+  constructor() {
+    super("missing digest", "MISSING_DIGEST");
+  }
+};
+var StatusNotFoundError = class extends UGFError {
+  constructor() {
+    super("status not found", "STATUS_NOT_FOUND");
+  }
+};
+var UnauthorizedError = class extends UGFError {
+  constructor() {
+    super("unauthorized", "UNAUTHORIZED");
+  }
+};
+var NetworkError = class extends UGFError {
+  constructor(message = "network error") {
+    super(message, "NETWORK_ERROR");
+  }
+};
+function parseBackendError(message) {
+  const lowerMsg = message.toLowerCase();
+  if (lowerMsg.includes("quote not found") || lowerMsg.includes("expired")) {
+    return new QuoteNotFoundError();
+  }
+  if (lowerMsg.includes("quote expired")) {
+    return new QuoteExpiredError();
+  }
+  if (lowerMsg.includes("payer mismatch")) {
+    return new PayerMismatchError();
+  }
+  if (lowerMsg.includes("invalid signature")) {
+    return new InvalidSignatureError();
+  }
+  if (lowerMsg.includes("insufficient")) {
+    return new InsufficientBalanceError();
+  }
+  if (lowerMsg.includes("invalid chain")) {
+    return new InvalidChainError();
+  }
+  if (lowerMsg.includes("invalid payment coin")) {
+    return new InvalidPaymentCoinError();
+  }
+  if (lowerMsg.includes("gas exceeds")) {
+    return new GasLimitExceededError();
+  }
+  if (lowerMsg.includes("missing digest")) {
+    return new MissingDigestError();
+  }
+  if (lowerMsg.includes("status not found")) {
+    return new StatusNotFoundError();
+  }
+  if (lowerMsg.includes("unauthorized")) {
+    return new UnauthorizedError();
+  }
+  return new NetworkError(message);
+}
+
+// src/api/quote.ts
+async function getQuote(apiUrl, request, apiKey) {
+  const res = await fetch(`${apiUrl}/quote`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    },
+    body: JSON.stringify(request)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/api/payment.ts
+async function submitPayment(apiUrl, request, apiKey) {
+  const res = await fetch(`${apiUrl}/payment/submit`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    },
+    body: JSON.stringify(request)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/api/status.ts
+async function getPaymentStatus(apiUrl, digest, apiKey) {
+  const res = await fetch(`${apiUrl}/payment/status?digest=${digest}`, {
+    headers: {
+      "X-API-Key": apiKey
+    }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/api/info.ts
+async function getSTONInfo(apiUrl, address, apiKey) {
+  const res = await fetch(`${apiUrl}/ston/info/${address}`, {
+    headers: {
+      "X-API-Key": apiKey
+    }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw parseBackendError(text);
+  }
+  const data = await res.json();
+  return data;
+}
+
+// src/core/client.ts
+var UGFClient = class {
+  /**
+   * Create a new UGF client
+   * @param config - Configuration with API URL and optional API key
+   */
+  constructor(config) {
+    this.apiUrl = config.apiUrl;
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Get a quote for gasless payment
+   * @param request - Quote request parameters
+   * @returns Quote with digest and payment details
+   */
+  async getQuote(request) {
+    return getQuote(this.apiUrl, request, this.apiKey);
+  }
+  /**
+   * Submit a signed payment
+   * @param request - Payment submission with signature
+   * @returns Payment status
+   */
+  async submitPayment(request) {
+    return submitPayment(this.apiUrl, request, this.apiKey);
+  }
+  /**
+   * Check payment status
+   * @param digest - Payment digest
+   * @returns Current payment status
+   */
+  async getPaymentStatus(digest) {
+    return getPaymentStatus(this.apiUrl, digest, this.apiKey);
+  }
+  /**
+   * Get user's STON balance info
+   * @param address - User's TON address
+   * @returns STON and x402 balance details
+   */
+  async getSTONInfo(address) {
+    return getSTONInfo(this.apiUrl, address, this.apiKey);
+  }
+};
+
+// src/core/config.ts
+var DEFAULT_CONFIG = {
+  apiUrl: "https://stonfi.universalgasframework.com"
+};
+
+// src/utils/formatting.ts
+function toNano(amount) {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  return Math.floor(num * 1e9).toString();
+}
+function fromNano(nanotons, decimals = 6) {
+  const num = typeof nanotons === "string" ? parseFloat(nanotons) : nanotons;
+  return (num / 1e9).toFixed(decimals);
+}
+function formatSTON(amount, decimals = 2) {
+  return parseFloat(fromNano(amount)).toFixed(decimals);
+}
+
+// src/utils/validation.ts
+import { Address } from "@ton/core";
+function isValidTONAddress(address) {
+  try {
+    Address.parse(address);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isValidHex(hex) {
+  return /^[0-9a-fA-F]+$/.test(hex) && hex.length % 2 === 0;
+}
+function isValidGasEstimate(nanotons) {
+  return nanotons > 0 && nanotons <= 5e8;
+}
+function isValidBufferPct(pct) {
+  return pct >= 0 && pct <= 50;
+}
+
+// src/crypto/signature.ts
+import nacl from "tweetnacl";
+function signDigest(digestHex, privateKeyHex) {
+  const digest = hexToBytes(digestHex);
+  const secretKey = hexToBytes(privateKeyHex);
+  const signature = nacl.sign.detached(digest, secretKey);
+  return bytesToHex(signature);
+}
+function verifySignature(digestHex, signatureHex, publicKeyHex) {
+  const digest = hexToBytes(digestHex);
+  const signature = hexToBytes(signatureHex);
+  const publicKey = hexToBytes(publicKeyHex);
+  return nacl.sign.detached.verify(digest, signature, publicKey);
+}
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export {
+  DEFAULT_CONFIG,
+  GasLimitExceededError,
+  InsufficientBalanceError,
+  InvalidChainError,
+  InvalidPaymentCoinError,
+  InvalidSignatureError,
+  MissingDigestError,
+  NetworkError,
+  PayerMismatchError,
+  QuoteExpiredError,
+  QuoteNotFoundError,
+  StatusNotFoundError,
+  UGFClient,
+  UGFError,
+  UnauthorizedError,
+  formatSTON,
+  fromNano,
+  isValidBufferPct,
+  isValidGasEstimate,
+  isValidHex,
+  isValidTONAddress,
+  parseBackendError,
+  signDigest,
+  toNano,
+  verifySignature
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tychilabs/stonfi-gasless-sdk",
+  "version": "0.0.1",
+  "description": "Universal Gas Framework SDK for gasless payments - pay TON transaction fees with STON token",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "ton",
+    "tonchain",
+    "ston",
+    "stonfi",
+    "gasless",
+    "gas-fee",
+    "ugf",
+    "universal-gas",
+    "defi",
+    "blockchain",
+    "payments",
+    "transaction"
+  ],
+  "homepage": "https://github.com/TychiWallet/stonfi-gasless-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/TychiWallet/stonfi-gasless-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TychiWallet/stonfi-gasless-sdk.git"
+  },
+  "license": "MIT",
+  "author": "yash@tychilabs.com",
+  "type": "module",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3"
+  },
+  "peerDependencies": {
+    "@ton/core": ">=0.63.0"
+  }
+}