qorbitpay-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qorbitpay
+
+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,78 @@
+# qorbitpay-sdk
+
+Payments SDK for autonomous AI agents on [Qorbitpay](https://github.com/), running on Arc
+(Circle's L1 testnet, chainId `5042002`, native gas token USDC).
+
+```bash
+npm install qorbitpay-sdk
+```
+
+## Quickstart
+
+```js
+import { Qorbitpay } from 'qorbitpay-sdk';
+
+const q = new Qorbitpay({ privateKey: process.env.AGENT_KEY });
+
+// send a payment (self-sovereign - signed and broadcast with your own wallet)
+await q.pay({ to: '0xAgent', amount: 0.01, memo: 'service' });
+
+// listen for incoming payments
+const unsubscribe = q.receive({
+  onPayment: (tx) => fulfillService(tx),
+});
+```
+
+Fund your agent's wallet at the [Circle faucet](https://faucet.circle.com) (select Arc
+Testnet) before sending payments.
+
+## Why no custodial relayer here
+
+Qorbitpay's hosted backend (`POST /api/pay`) is a *custodial* relayer that adds QRNG-anchored
+nonces, VQC fraud screening, QAOA-based provider routing, and Dilithium2 (post-quantum)
+dual-signing with on-chain attestation for higher-value payments. This SDK instead talks
+directly to the on-chain contracts with your agent's own key - lighter weight, no
+custodial trust required, and all you need for the base protocol (sending/receiving
+native-token payments, registering in the agent directory).
+
+`checkFraud()` and `findRoute()` below call the *same* quantum services the hosted backend
+uses, over HTTP, for agents that want those signals without running Qiskit themselves -
+pass `apiUrl` pointing at a Qorbitpay backend deployment to use them.
+
+## API
+
+### `new Qorbitpay(options)`
+
+| option | required | default | description |
+|---|---|---|---|
+| `privateKey` | yes | - | your agent's wallet private key |
+| `rpcUrl` | no | Arc testnet RPC | |
+| `chainId` | no | `5042002` | |
+| `routerAddress` | no | deployed QorbitpayRouter | |
+| `registryAddress` | no | deployed QorbitpayRegistry | |
+| `apiUrl` | no | `null` | base URL of a Qorbitpay backend, required for `checkFraud`/`findRoute` |
+
+### `await q.pay({ to, amount, memo })`
+Sends `amount` (native token units, string or number) to `to`. `memo` is hashed
+(keccak256) on-chain. Returns `{ txHash, status, blockNumber, explorerUrl, ... }`.
+
+### `q.receive({ onPayment })`
+Subscribes to incoming `PaymentSent` events addressed to your agent. Returns an
+`unsubscribe()` function.
+
+### `await q.register({ serviceEndpoint })`
+Registers your agent (self-sovereign: owner == agent == your wallet) in the on-chain
+agent directory.
+
+### `await q.getAgent(address?)` / `await q.getReputation(address?)`
+Reads from the agent directory. Defaults to your own address.
+
+### `await q.getBalance()`
+Native token balance of your agent's wallet, formatted as a string.
+
+### `await q.checkFraud({ amount_zscore, agent_age_days, tx_frequency, dispute_rate })`
+VQC (variational quantum circuit) fraud score via a Qorbitpay backend. Requires `apiUrl`.
+
+### `await q.findRoute(providers)`
+QAOA-optimal pick among `providers: [{ id, price, latency, reputation }, ...]` via a
+Qorbitpay backend. Requires `apiUrl`.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "qorbitpay-sdk",
+  "version": "0.1.0",
+  "description": "SDK for autonomous AI agents to send and receive payments on Qorbitpay (Arc testnet)",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "qorbitpay",
+    "arc",
+    "circle",
+    "usdc",
+    "ai-agents",
+    "x402",
+    "payments",
+    "web3"
+  ],
+  "license": "MIT",
+  "author": "Qorbitpay",
+  "homepage": "https://qorbitpay.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davieslennox0/Qorbit.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/davieslennox0/Qorbit/issues"
+  },
+  "peerDependencies": {
+    "ethers": "^6.13.0"
+  },
+  "dependencies": {
+    "ethers": "^6.13.0"
+  }
+}

package/src/abi.js

@@ -0,0 +1,55 @@
+export const ROUTER_ABI = [
+  'function pay(address to, bytes32 memoHash) payable',
+  'function splitPay(address[] to, uint256[] amounts, bytes32 memoHash) payable',
+  'function createEscrow(address payee, uint64 timeoutSeconds) payable returns (uint256)',
+  'function releaseEscrow(uint256 id)',
+  'function refundEscrow(uint256 id)',
+  'function getEscrow(uint256 id) view returns (tuple(address payer,address payee,uint256 amount,uint64 createdAt,uint64 timeoutSeconds,bool released,bool refunded))',
+  'event PaymentSent(address indexed from, address indexed to, uint256 amount, bytes32 memoHash)',
+];
+
+const _IDENTITY = 'tuple(address owner,string name,string version,string serviceEndpoint,bytes32 capabilityHash,uint256 registeredAt,bool active)';
+const _RECORD = 'tuple(address owner,string name,string version,string serviceEndpoint,bytes32 capabilityHash,uint256 registeredAt,bool active,uint32 reputation,bytes32 dilithiumPubKeyHash,uint32 trustScore,uint8 quantumLayerMask)';
+
+export const REGISTRY_ABI = [
+  // ERC-8004 required
+  `function registerAgent(${_IDENTITY} identity) returns (bytes32 agentId)`,
+  `function getAgent(bytes32 agentId) view returns (${_IDENTITY})`,
+  'function validateAgent(bytes32 agentId) view returns (bool)',
+  'function deactivateAgent(bytes32 agentId)',
+  'event AgentRegistered(bytes32 indexed agentId, address indexed owner, string name)',
+  'event AgentValidated(bytes32 indexed agentId)',
+  'event AgentDeactivated(bytes32 indexed agentId)',
+  // Qorbitpay extensions
+  `function getAgentRecord(bytes32 agentId) view returns (${_RECORD})`,
+  `function getAgentByOwner(address owner) view returns (bytes32 agentId, ${_RECORD} record)`,
+  'function updateEndpoint(bytes32 agentId, string serviceEndpoint)',
+  'function setDilithiumPubKey(bytes32 agentId, bytes32 pubKeyHash)',
+  'function isRegistered(address agentOwner) view returns (bool)',
+  'function ownerToAgentId(address) view returns (bytes32)',
+  'function agentCount() view returns (uint256)',
+  `function listAgents(uint256 offset, uint256 limit) view returns (${_RECORD}[] page, bytes32[] ids)`,
+];
+
+export const BILLING_ABI = [
+  'function createSubscription(address agent, uint256 amountPerPeriod, uint256 periodSeconds) payable returns (bytes32)',
+  'function cancelSubscription(bytes32 subId)',
+  'function processPayment(bytes32 subId)',
+  'function topUp(bytes32 subId) payable',
+  'function getSubscription(bytes32 subId) view returns (tuple(address subscriber,address agent,uint256 amountPerPeriod,uint256 periodSeconds,uint256 lastPaidAt,uint256 balance,bool active))',
+  'function nextPaymentDue(bytes32 subId) view returns (uint256)',
+  'function isDue(bytes32 subId) view returns (bool)',
+  'event SubscriptionCreated(bytes32 indexed subId, address indexed subscriber, address indexed agent, uint256 amountPerPeriod, uint256 periodSeconds)',
+  'event PaymentProcessed(bytes32 indexed subId, address indexed agent, uint256 amount)',
+];
+
+export const TREASURY_ABI = [
+  'function deposit() payable',
+  'function allocateBudget(address workerAgent, uint256 dailyCap, uint256 categoryMask, uint256 expiresAt)',
+  'function spend(address treasury, uint256 amount, uint256 category)',
+  'function revokeBudget(address workerAgent)',
+  'function getBudget(address treasury, address workerAgent) view returns (uint256 remaining, uint256 dailyCap, uint256 expiresAt, uint256 categoryMask, bool active)',
+  'function treasuryBalances(address) view returns (uint256)',
+  'event BudgetAllocated(address indexed treasury, address indexed worker, uint256 dailyCap, uint256 categoryMask, uint256 expiresAt)',
+  'event SpendExecuted(address indexed treasury, address indexed worker, uint256 amount, uint256 category)',
+];

package/src/config.js

@@ -0,0 +1,18 @@
+// Defaults for Arc testnet - see contracts/deployments/arc-testnet.json in the Qorbitpay repo.
+export const DEFAULT_NETWORK = {
+  rpcUrl: 'https://rpc.testnet.arc.network',
+  chainId: 5042002,
+  explorer: 'https://testnet.arcscan.app',
+  routerAddress: '0xCEe1f311261Ffe460ef5060F94183320e74fD703',
+  registryAddress: '0x3fbCdaD38f40d932A5574562BB72B9115c265093',
+  verifierAddress: '0xca8FbCFb990A77B130939Ec5E0B98e4324fE0c79',
+  billingAddress: '0xdF87E0c0cfcA0AEa1e899073c36F29Fd865B5e97',
+  treasuryAddress: '0x7168493186654AD84Ef2dEfb78C773eeCB1BaFC8',
+};
+
+export const CATEGORY = {
+  data: 0x01,
+  compute: 0x02,
+  storage: 0x04,
+  all: 0x07,
+};

package/src/index.js

@@ -0,0 +1,314 @@
+import { ethers } from 'ethers';
+import { ROUTER_ABI, REGISTRY_ABI, BILLING_ABI, TREASURY_ABI } from './abi.js';
+import { DEFAULT_NETWORK, CATEGORY } from './config.js';
+
+/// Qorbitpay SDK - a thin client for AI agents to send/receive payments directly on Arc,
+/// using the agent's own funded wallet (self-sovereign), rather than going through
+/// Qorbitpay's custodial backend relayer. The relayer's extra protections (QRNG-anchored
+/// nonces, VQC fraud screening, QAOA routing, Dilithium dual-signing/attestation) are
+/// features of the hosted POST /api/pay endpoint, not requirements of the on-chain
+/// protocol itself - calling the contracts directly here is a fully valid, lighter-weight
+/// way to use Qorbitpay. checkFraud()/findRoute() below call the hosted quantum services
+/// over HTTP for agents that want those signals without running Qiskit themselves.
+class Qorbitpay {
+  constructor({
+    privateKey,
+    rpcUrl = DEFAULT_NETWORK.rpcUrl,
+    chainId = DEFAULT_NETWORK.chainId,
+    routerAddress = DEFAULT_NETWORK.routerAddress,
+    registryAddress = DEFAULT_NETWORK.registryAddress,
+    billingAddress = DEFAULT_NETWORK.billingAddress,
+    treasuryAddress = DEFAULT_NETWORK.treasuryAddress,
+    apiUrl = null,
+  } = {}) {
+    if (!privateKey) throw new Error('Qorbitpay SDK requires a privateKey');
+
+    this.provider = new ethers.JsonRpcProvider(rpcUrl, { chainId, name: 'arc-testnet' });
+    this.wallet = new ethers.Wallet(privateKey, this.provider);
+    this.address = this.wallet.address;
+    this.apiUrl = apiUrl;
+    this.explorer = DEFAULT_NETWORK.explorer;
+
+    this.router = new ethers.Contract(routerAddress, ROUTER_ABI, this.wallet);
+    this.registry = new ethers.Contract(registryAddress, REGISTRY_ABI, this.wallet);
+    this.billing = new ethers.Contract(billingAddress, BILLING_ABI, this.wallet);
+    this.treasury = new ethers.Contract(treasuryAddress, TREASURY_ABI, this.wallet);
+
+    // ERC-8004 agentId, populated after register() or set manually.
+    this.agentId = null;
+
+    // Guards against nonce races if an agent fires multiple calls without awaiting each one.
+    this._sendQueue = Promise.resolve();
+  }
+
+  _withNonceLock(fn) {
+    const run = this._sendQueue.then(async () => {
+      const nonce = await this.provider.getTransactionCount(this.address, 'pending');
+      return fn(nonce);
+    });
+    this._sendQueue = run.then(() => {}, () => {});
+    return run;
+  }
+
+  /// Sends a native-token (USDC) payment to `to` via QorbitpayRouter.pay(). `memo` is
+  /// hashed (keccak256) on-chain as an opaque reference - pass the same memo string
+  /// elsewhere if you need to look the payment back up.
+  async pay({ to, amount, memo } = {}) {
+    if (!to || !ethers.isAddress(to)) throw new Error('pay() requires a valid `to` address');
+    if (!amount || Number(amount) <= 0) throw new Error('pay() requires a positive `amount`');
+
+    const memoHash = memo ? ethers.keccak256(ethers.toUtf8Bytes(memo)) : ethers.ZeroHash;
+    const value = ethers.parseEther(String(amount));
+
+    const tx = await this._withNonceLock((nonce) => this.router.pay(to, memoHash, { value, nonce }));
+    const receipt = await tx.wait();
+
+    return {
+      txHash: tx.hash,
+      from: this.address,
+      to,
+      amount: String(amount),
+      memo: memo || null,
+      status: receipt.status === 1 ? 'confirmed' : 'failed',
+      blockNumber: receipt.blockNumber,
+      explorerUrl: `${this.explorer}/tx/${tx.hash}`,
+    };
+  }
+
+  /// Subscribes to incoming payments (PaymentSent events where `to` is this agent's
+  /// address). Returns an unsubscribe function.
+  receive({ onPayment } = {}) {
+    if (typeof onPayment !== 'function') throw new Error('receive() requires an onPayment callback');
+
+    const filter = this.router.filters.PaymentSent(null, this.address);
+    // Subscribing with a TopicFilter object (rather than the bare event name string)
+    // means ethers does NOT expand decoded args into separate listener parameters - it
+    // passes a single ContractEventPayload. Assuming the (from, to, amount, memoHash,
+    // event) signature here silently threw inside the listener (event was undefined) and
+    // ethers swallowed it, which looked exactly like a polling/timing bug until logging
+    // the raw listener arguments showed only one object was ever passed.
+    const listener = (payload) => {
+      const [from, to, amount, memoHash] = payload.args;
+      onPayment({
+        from,
+        to,
+        amount: ethers.formatEther(amount),
+        memoHash,
+        txHash: payload.log.transactionHash,
+        blockNumber: payload.log.blockNumber,
+        explorerUrl: `${this.explorer}/tx/${payload.log.transactionHash}`,
+      });
+    };
+
+    this.router.on(filter, listener);
+    return () => this.router.off(filter, listener);
+  }
+
+  /// Registers this agent in QorbitpayRegistry using an ERC-8004 AgentIdentity struct
+  /// (self-sovereign — owner is this wallet). Returns the bytes32 agentId and stores it
+  /// on this instance for automatic inclusion as X-Agent-Id in all subsequent API calls.
+  /// For custodial registration on an agent's behalf, see the backend's POST /api/receive.
+  async register({ name, serviceEndpoint, version = '1.0.0', capabilityHash } = {}) {
+    if (!name) throw new Error('register() requires a name');
+    if (!serviceEndpoint) throw new Error('register() requires a serviceEndpoint');
+
+    const identity = {
+      owner: this.address,
+      name,
+      version,
+      serviceEndpoint,
+      capabilityHash: capabilityHash || ethers.ZeroHash,
+      registeredAt: 0n,
+      active: true,
+    };
+
+    const tx = await this._withNonceLock((nonce) =>
+      this.registry.registerAgent(identity, { nonce })
+    );
+    const receipt = await tx.wait();
+
+    let agentId = null;
+    for (const log of receipt.logs) {
+      try {
+        const parsed = this.registry.interface.parseLog({ topics: log.topics, data: log.data });
+        if (parsed?.name === 'AgentRegistered') { agentId = parsed.args.agentId; break; }
+      } catch { /* ignore */ }
+    }
+
+    this.agentId = agentId;
+    return { txHash: tx.hash, agentId, status: receipt.status === 1 ? 'confirmed' : 'failed' };
+  }
+
+  _formatAgentRecord(agentId, record) {
+    return {
+      agentId,
+      erc8004: true,
+      owner: record.owner,
+      name: record.name,
+      version: record.version,
+      serviceEndpoint: record.serviceEndpoint,
+      capabilityHash: record.capabilityHash,
+      registeredAt: Number(record.registeredAt),
+      active: record.active,
+      reputation: Number(record.reputation),
+      dilithiumPubKeyHash: record.dilithiumPubKeyHash,
+      trustScore: Number(record.trustScore),
+      quantumLayerMask: Number(record.quantumLayerMask),
+    };
+  }
+
+  async getAgent(agentIdOrAddress = this.agentId || this.address) {
+    // Accept either a bytes32 agentId (66-char hex) or an owner address (42-char).
+    if (agentIdOrAddress && agentIdOrAddress.length > 42) {
+      const record = await this.registry.getAgentRecord(agentIdOrAddress);
+      return this._formatAgentRecord(agentIdOrAddress, record);
+    }
+    const [agentId, record] = await this.registry.getAgentByOwner(agentIdOrAddress);
+    return this._formatAgentRecord(agentId, record);
+  }
+
+  async getReputation(agentIdOrAddress = this.agentId || this.address) {
+    return (await this.getAgent(agentIdOrAddress)).reputation;
+  }
+
+  async getBalance() {
+    const balance = await this.provider.getBalance(this.address);
+    return ethers.formatEther(balance);
+  }
+
+  async _apiPost(path, body) {
+    if (!this.apiUrl) {
+      throw new Error(`${path} requires apiUrl to be set in the Qorbitpay constructor`);
+    }
+    const headers = { 'Content-Type': 'application/json' };
+    if (this.agentId) headers['X-Agent-Id'] = this.agentId;
+    const res = await fetch(`${this.apiUrl}${path}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || `${path} failed with status ${res.status}`);
+    return data;
+  }
+
+  /// VQC fraud score via the hosted quantum services (POST /api/fraud).
+  checkFraud({ amount_zscore, agent_age_days, tx_frequency, dispute_rate } = {}) {
+    return this._apiPost('/api/fraud', { amount_zscore, agent_age_days, tx_frequency, dispute_rate });
+  }
+
+  /// QAOA-optimal provider selection via the hosted quantum services (POST /api/route).
+  findRoute(providers) {
+    return this._apiPost('/api/route', { providers });
+  }
+
+  /// Create a recurring subscription to pay `to` agent `amount` USDC every `period`.
+  /// `period` can be seconds (number) or a shorthand string: '7d', '24h', '1w', etc.
+  /// `initialBalance` (optional) pre-funds the subscription; defaults to one period's amount.
+  async subscribe({ to, amount, period, initialBalance } = {}) {
+    if (!to || !ethers.isAddress(to)) throw new Error('subscribe() requires a valid `to` address');
+    if (!amount || Number(amount) <= 0) throw new Error('subscribe() requires a positive `amount`');
+    if (!period) throw new Error('subscribe() requires a `period` (e.g. "7d", 604800)');
+
+    const periodSeconds = BigInt(_parsePeriod(period));
+    const amountWei = ethers.parseEther(String(amount));
+    const balanceWei = initialBalance ? ethers.parseEther(String(initialBalance)) : amountWei;
+
+    const tx = await this._withNonceLock((nonce) =>
+      this.billing.createSubscription(to, amountWei, periodSeconds, { value: balanceWei, nonce })
+    );
+    const receipt = await tx.wait();
+
+    let subId = null;
+    for (const log of receipt.logs) {
+      try {
+        const parsed = this.billing.interface.parseLog({ topics: log.topics, data: log.data });
+        if (parsed?.name === 'SubscriptionCreated') {
+          subId = parsed.args.subId;
+          break;
+        }
+      } catch { /* ignore */ }
+    }
+
+    return {
+      subId,
+      to,
+      amount: String(amount),
+      periodSeconds: Number(periodSeconds),
+      initialBalance: ethers.formatEther(balanceWei),
+      txHash: tx.hash,
+      status: receipt.status === 1 ? 'confirmed' : 'failed',
+      explorerUrl: `${this.explorer}/tx/${tx.hash}`,
+    };
+  }
+
+  /// Cancel a subscription (subscriber only). Refunds remaining balance.
+  async cancelSubscription(subId) {
+    if (!subId) throw new Error('cancelSubscription() requires a subId');
+    const tx = await this._withNonceLock((nonce) => this.billing.cancelSubscription(subId, { nonce }));
+    const receipt = await tx.wait();
+    return { txHash: tx.hash, status: receipt.status === 1 ? 'confirmed' : 'failed' };
+  }
+
+  /// Spend from a treasury budget. `from` is the treasury address, `category` is
+  /// 'data' | 'compute' | 'storage' or a numeric bitmask.
+  async spend({ from, amount, category = 'data' } = {}) {
+    if (!from || !ethers.isAddress(from)) throw new Error('spend() requires a valid `from` (treasury) address');
+    if (!amount || Number(amount) <= 0) throw new Error('spend() requires a positive `amount`');
+
+    const cat = typeof category === 'string'
+      ? (CATEGORY[category.toLowerCase()] ?? (() => { throw new Error(`unknown category: ${category}`); })())
+      : Number(category);
+    const amountWei = ethers.parseEther(String(amount));
+
+    const tx = await this._withNonceLock((nonce) =>
+      this.treasury.spend(from, amountWei, BigInt(cat), { nonce })
+    );
+    const receipt = await tx.wait();
+
+    return {
+      from,
+      to: this.address,
+      amount: String(amount),
+      category,
+      txHash: tx.hash,
+      status: receipt.status === 1 ? 'confirmed' : 'failed',
+      explorerUrl: `${this.explorer}/tx/${tx.hash}`,
+    };
+  }
+
+  /// Deposit funds into the treasury under this agent's address.
+  async depositToTreasury(amount) {
+    if (!amount || Number(amount) <= 0) throw new Error('depositToTreasury() requires a positive amount');
+    const value = ethers.parseEther(String(amount));
+    const tx = await this._withNonceLock((nonce) => this.treasury.deposit({ value, nonce }));
+    const receipt = await tx.wait();
+    return { txHash: tx.hash, status: receipt.status === 1 ? 'confirmed' : 'failed' };
+  }
+
+  /// Allocate a spending budget to a worker agent.
+  async allocateBudget({ worker, dailyCap, categoryMask = CATEGORY.all, expiresAt } = {}) {
+    if (!worker || !ethers.isAddress(worker)) throw new Error('allocateBudget() requires a valid `worker` address');
+    if (!dailyCap || Number(dailyCap) <= 0) throw new Error('allocateBudget() requires a positive `dailyCap`');
+    if (!expiresAt) throw new Error('allocateBudget() requires an `expiresAt` unix timestamp');
+
+    const tx = await this._withNonceLock((nonce) =>
+      this.treasury.allocateBudget(worker, ethers.parseEther(String(dailyCap)), BigInt(categoryMask), BigInt(expiresAt), { nonce })
+    );
+    const receipt = await tx.wait();
+    return { txHash: tx.hash, status: receipt.status === 1 ? 'confirmed' : 'failed' };
+  }
+}
+
+function _parsePeriod(period) {
+  if (typeof period === 'number') return period;
+  const str = String(period);
+  if (/^\d+$/.test(str)) return Number(str);
+  const match = str.match(/^(\d+(?:\.\d+)?)(s|m|h|d|w)$/);
+  if (!match) throw new Error(`invalid period: ${period} (use e.g. 7d, 24h, 3600)`);
+  const n = Number(match[1]);
+  const units = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
+  return Math.round(n * units[match[2]]);
+}
+
+export { Qorbitpay, CATEGORY };