@totemsdk/chain-provider 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+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

@@ -16,13 +16,14 @@ npm install @totemsdk/chain-provider
 
 ```typescript
 interface ChainStateProvider {
-  getCoins(query: CoinQuery): Promise<Coin[]>;
-  getCoin(id: string): Promise<Coin | null>;
-  getMMRProof(coinId: string): Promise<MMRProof>;
-  getChainTip(): Promise<ChainTip>;
-  getToken(id: string): Promise<Token | null>;
-  searchTokens(query: string): Promise<Token[]>;
-  broadcastTxPoW(hex: string): Promise<BroadcastResult>;
+  getCoins(query: CoinsQuery): Promise<Coin[]>;
+  getCoin(coinId: string): Promise<Coin | null>;
+  getProof(coinId: string): Promise<MMRProof>;
+  getTip(): Promise<ChainTip>;
+  getToken(tokenId: string): Promise<TokenInfo>;
+  searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]>;
+  getTokensByCreator(address: string): Promise<TokenInfo[]>;
+  broadcastTxPoW(txpowHex: string): Promise<BroadcastResult>;
 }
 ```
 
@@ -32,7 +33,7 @@ interface ChainStateProvider {
 |-------|------------|
 | `HostedProvider` | Axia / MEG hosted API (requires project credentials) |
 | `PureMinimaRpcProvider` | A local or self-hosted PureMinima node directly |
-| `LookupNodeProvider` | A personal lookup node over Hyperswarm DHT |
+| `LookupClientProvider` | A personal lookup node over Hyperswarm DHT (via `@totemsdk/lookup-client`) |
 | `CompositeProvider` | Fans out across multiple providers with fallback logic |
 
 Five other packages (`omnia`, `statechain`, `lookup-node`, `lookup-client`, `chain-provider` itself) accept `ChainStateProvider` — this is the pivot point between the upper SDK and chain data.
@@ -50,7 +51,7 @@ const provider = new HostedProvider({
   projectSecret: process.env.AXIA_SECRET,
 });
 
-const tip  = await provider.getChainTip();
+const tip   = await provider.getTip();
 const coins = await provider.getCoins({ address: 'Mx...' });
 ```
 
@@ -64,31 +65,72 @@ const provider = new PureMinimaRpcProvider({
 });
 ```
 
+### Personal lookup node (sovereign, zero-Axia-dependency)
+
+Connect directly to your own lookup node over Hyperswarm DHT. No hosted infrastructure required.
+
+```typescript
+import { LookupClientProvider } from '@totemsdk/chain-provider';
+import { connectLookupNode } from '@totemsdk/lookup-client';
+
+// Connect to your personal lookup node
+const client = await connectLookupNode({ hyperswarmTopic: 'deadbeef...' });
+
+const provider = new LookupClientProvider(client);
+
+const tip   = await provider.getTip();
+const coins = await provider.getCoins({ address: 'Mx...' });
+
+// Clean up when done
+client.disconnect();
+```
+
+`@totemsdk/lookup-client` is a peer dependency — install it separately:
+
+```bash
+npm install @totemsdk/lookup-client
+```
+
 ### Composite with fallback
 
+Fan out across providers: try sovereign first, fall back to hosted on any error.
+
 ```typescript
-import { CompositeProvider, HostedProvider, PureMinimaRpcProvider } from '@totemsdk/chain-provider';
+import { CompositeProvider, HostedProvider, LookupClientProvider } from '@totemsdk/chain-provider';
+import { connectLookupNode } from '@totemsdk/lookup-client';
 
-const provider = new CompositeProvider([
-  new PureMinimaRpcProvider({ nodeUrl: 'http://localhost:9005' }),
-  new HostedProvider({ baseUrl: 'https://api.axia.to', projectId: '...' }),
-]);
-// Queries hit the first provider; fallback to the second on error
+const client  = await connectLookupNode({ hyperswarmTopic: 'deadbeef...' });
+const hosted  = new HostedProvider({ baseUrl: 'https://api.axia.to', projectId: '...' });
+
+const provider = new CompositeProvider(
+  new LookupClientProvider(client), // primary — sovereign, no Axia dependency
+  hosted,                           // fallback — hosted, always available
+);
+
+// Queries hit the lookup node first; fall back to hosted on error
+const tip = await provider.getTip();
 ```
 
-### Personal lookup node
+## LookupClientLike interface
+
+`LookupClientProvider` accepts any object that satisfies the `LookupClientLike` structural interface exported from this package. This allows testing with a mock without importing `@totemsdk/lookup-client`:
 
 ```typescript
-import { LookupNodeProvider } from '@totemsdk/chain-provider';
+import { LookupClientProvider } from '@totemsdk/chain-provider';
+import type { LookupClientLike } from '@totemsdk/chain-provider';
 
-const provider = new LookupNodeProvider({
-  publicKey: '...your-lookup-node-pubkey...',
-});
+const mockClient: LookupClientLike = {
+  getTip: async () => ({ block: 100, hash: '0x...' }),
+  getCoins: async () => [],
+  // ... etc
+};
+
+const provider = new LookupClientProvider(mockClient);
 ```
 
 ## See also
 
-- [`@totemsdk/pureminima-rpc`](../pureminima-rpc) — the RPC client used by `PureMinimaRpcProvider`
-- [`@totemsdk/lookup-client`](../lookup-client) — `LookupClientProvider` implementation
-- [`@totemsdk/node`](../node) — Node.js `MinimaProvider`
-- [`@totemsdk/omnia`](../omnia) — uses `ChainStateProvider` for coin queries
+- [`@totemsdk/pureminima-rpc`](https://www.npmjs.com/package/@totemsdk/pureminima-rpc) — the RPC client used by `PureMinimaRpcProvider`
+- [`@totemsdk/lookup-client`](https://www.npmjs.com/package/@totemsdk/lookup-client) — connect to a personal lookup node over Hyperswarm DHT
+- [`@totemsdk/node`](https://www.npmjs.com/package/@totemsdk/node) — Node.js `MinimaProvider`
+- [`@totemsdk/omnia`](https://www.npmjs.com/package/@totemsdk/omnia) — uses `ChainStateProvider` for coin queries

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export type { ChainStateProvider, CoinsQuery, Coin, MMRProof, ChainTip, TokenInf
 export { HostedProvider } from './providers/hosted.js';
 export type { HostedProviderConfig } from './providers/hosted.js';
 export { PureMinimaRpcProvider } from './providers/pureminima.js';
-export { LookupNodeProvider, LookupNodeNotImplementedError } from './providers/lookup.js';
+export { LookupClientProvider } from './providers/lookup-client.js';
+export type { LookupClientLike } from './providers/lookup-client.js';
 export { CompositeProvider } from './providers/composite.js';

package/dist/index.js

@@ -1,4 +1,11 @@
-export { HostedProvider } from './providers/hosted.js';
-export { PureMinimaRpcProvider } from './providers/pureminima.js';
-export { LookupNodeProvider, LookupNodeNotImplementedError } from './providers/lookup.js';
-export { CompositeProvider } from './providers/composite.js';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeProvider = exports.LookupClientProvider = exports.PureMinimaRpcProvider = exports.HostedProvider = void 0;
+var hosted_js_1 = require("./providers/hosted.js");
+Object.defineProperty(exports, "HostedProvider", { enumerable: true, get: function () { return hosted_js_1.HostedProvider; } });
+var pureminima_js_1 = require("./providers/pureminima.js");
+Object.defineProperty(exports, "PureMinimaRpcProvider", { enumerable: true, get: function () { return pureminima_js_1.PureMinimaRpcProvider; } });
+var lookup_client_js_1 = require("./providers/lookup-client.js");
+Object.defineProperty(exports, "LookupClientProvider", { enumerable: true, get: function () { return lookup_client_js_1.LookupClientProvider; } });
+var composite_js_1 = require("./providers/composite.js");
+Object.defineProperty(exports, "CompositeProvider", { enumerable: true, get: function () { return composite_js_1.CompositeProvider; } });

package/dist/providers/composite.js

@@ -1,7 +1,10 @@
+"use strict";
 /**
  * CompositeProvider — tries primary provider, falls back to secondary on any error.
  */
-export class CompositeProvider {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeProvider = void 0;
+class CompositeProvider {
     constructor(primary, fallback, onFallback) {
         this.primary = primary;
         this.fallback = fallback;
@@ -48,3 +51,4 @@ export class CompositeProvider {
         return this.withArg('broadcastTxPoW', txpowHex);
     }
 }
+exports.CompositeProvider = CompositeProvider;

package/dist/providers/hosted.d.ts

@@ -1,6 +1,13 @@
 /**
- * HostedProvider — wraps existing Axia REST API endpoints.
- * Uses fetch only; no Node.js-specific dependencies.
+ * HostedProvider — wraps Axia REST + RPC API endpoints.
+ *
+ * Endpoint map (all require x-api-key header):
+ *   GET  /v1/wallet/utxos/:address  — coin list  (totem-shared key)
+ *   POST /v1/wallet/rpc             — Minima RPC commands (totem-shared key)
+ *   POST /api/meg/postminedtxn      — broadcast mined TxPoW (no auth required)
+ *
+ * For dApp developers using custom project API keys the `/v1/wallet/*` routes
+ * require x-api-key: 'totem-shared'. Use the apiKey config option accordingly.
  */
 import type { ChainStateProvider, CoinsQuery, Coin, MMRProof, ChainTip, TokenInfo, TokenSearchQuery, BroadcastResult } from '../types.js';
 export interface HostedProviderConfig {
@@ -14,12 +21,38 @@ export declare class HostedProvider implements ChainStateProvider {
     private readonly timeoutMs;
     constructor(config: HostedProviderConfig);
     private fetchJson;
+    /**
+     * Send a Minima command to POST /v1/wallet/rpc.
+     * Returns the `response` field of the Minima envelope.
+     */
+    private rpc;
+    /**
+     * Get coins (UTXOs) for an address.
+     * Maps GET /v1/wallet/utxos/:address → Coin[].
+     */
     getCoins(query: CoinsQuery): Promise<Coin[]>;
     getCoin(coinId: string): Promise<Coin | null>;
+    /**
+     * Get MMR proof for a coin via Minima `coinproof` RPC command.
+     */
     getProof(coinId: string): Promise<MMRProof>;
+    /**
+     * Get chain tip via Minima `status` RPC — parses response.chain.
+     */
     getTip(): Promise<ChainTip>;
+    /**
+     * Get token info via Minima `tokens tokenid:X` RPC command.
+     */
     getToken(tokenId: string): Promise<TokenInfo>;
+    /**
+     * Search tokens via Minima `tokens` RPC command, then filter client-side.
+     */
     searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]>;
     getTokensByCreator(address: string): Promise<TokenInfo[]>;
+    /**
+     * Broadcast a mined TxPoW hex.
+     * Uses POST /api/meg/postminedtxn (the correct Axia MEG broadcast bridge).
+     */
     broadcastTxPoW(txpowHex: string): Promise<BroadcastResult>;
+    private _mapToken;
 }

package/dist/providers/hosted.js

@@ -1,8 +1,18 @@
+"use strict";
 /**
- * HostedProvider — wraps existing Axia REST API endpoints.
- * Uses fetch only; no Node.js-specific dependencies.
+ * HostedProvider — wraps Axia REST + RPC API endpoints.
+ *
+ * Endpoint map (all require x-api-key header):
+ *   GET  /v1/wallet/utxos/:address  — coin list  (totem-shared key)
+ *   POST /v1/wallet/rpc             — Minima RPC commands (totem-shared key)
+ *   POST /api/meg/postminedtxn      — broadcast mined TxPoW (no auth required)
+ *
+ * For dApp developers using custom project API keys the `/v1/wallet/*` routes
+ * require x-api-key: 'totem-shared'. Use the apiKey config option accordingly.
  */
-export class HostedProvider {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostedProvider = void 0;
+class HostedProvider {
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/$/, '');
         this.apiKey = config.apiKey;
@@ -30,75 +40,185 @@ export class HostedProvider {
             clearTimeout(timer);
         }
     }
+    /**
+     * Send a Minima command to POST /v1/wallet/rpc.
+     * Returns the `response` field of the Minima envelope.
+     */
+    async rpc(command) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}/v1/wallet/rpc`, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'text/plain',
+                    'x-api-key': this.apiKey,
+                },
+                body: command,
+            });
+            if (!res.ok)
+                throw new Error(`HostedProvider RPC "${command}" HTTP ${res.status}`);
+            const json = await res.json();
+            if (json.status === false)
+                throw new Error(`RPC "${command}" failed: ${json.error ?? 'unknown'}`);
+            return json.response;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Get coins (UTXOs) for an address.
+     * Maps GET /v1/wallet/utxos/:address → Coin[].
+     */
     async getCoins(query) {
-        const params = new URLSearchParams();
-        if (query.address)
-            params.set('address', query.address);
-        if (query.tokenId)
-            params.set('tokenid', query.tokenId);
-        if (query.sendable !== undefined)
-            params.set('sendable', String(query.sendable));
-        if (query.relevant !== undefined)
-            params.set('relevant', String(query.relevant));
-        if (query.coinId)
-            params.set('coinid', query.coinId);
-        if (query.megammr !== undefined)
-            params.set('megammr', String(query.megammr));
-        const qs = params.toString();
-        const result = await this.fetchJson(`/v1/wallet/coins${qs ? `?${qs}` : ''}`);
-        return Array.isArray(result) ? result : (result.coins ?? []);
+        if (!query.address && !query.coinId)
+            return [];
+        if (query.coinId) {
+            const coin = await this.getCoin(query.coinId);
+            return coin ? [coin] : [];
+        }
+        const data = await this.fetchJson(`/v1/wallet/utxos/${encodeURIComponent(query.address)}`);
+        const raw = data.utxos ?? [];
+        return raw
+            .filter((u) => {
+            if (query.tokenId && u.tokenid !== query.tokenId)
+                return false;
+            if (query.sendable !== undefined && !!u.spent !== !query.sendable)
+                return false;
+            return true;
+        })
+            .map((u) => ({
+            coinid: u.coinid ?? u.id ?? '',
+            amount: String(u.amount ?? '0'),
+            address: u.address ?? query.address ?? '',
+            miniaddress: u.miniaddress,
+            tokenid: u.tokenid ?? '0x00',
+            token: u.token,
+            storestate: u.storestate,
+            state: u.state,
+            spent: !!u.spent,
+            mmrentry: u.mmrentry,
+            created: u.created,
+        }));
     }
     async getCoin(coinId) {
         try {
-            const coins = await this.getCoins({ coinId });
-            return coins[0] ?? null;
+            const coins = await this.rpc(`coins coinid:${coinId}`);
+            const u = Array.isArray(coins) ? coins[0] : null;
+            if (!u)
+                return null;
+            return {
+                coinid: u.coinid ?? coinId,
+                amount: String(u.amount ?? '0'),
+                address: u.address ?? '',
+                miniaddress: u.miniaddress,
+                tokenid: u.tokenid ?? '0x00',
+                token: u.token,
+                storestate: u.storestate,
+                state: u.state,
+                spent: !!u.spent,
+                mmrentry: u.mmrentry,
+                created: u.created,
+            };
         }
         catch {
             return null;
         }
     }
+    /**
+     * Get MMR proof for a coin via Minima `coinproof` RPC command.
+     */
     async getProof(coinId) {
-        return this.fetchJson(`/v1/wallet/proofs/${encodeURIComponent(coinId)}`);
+        const data = await this.rpc(`coinproof coinid:${coinId}`);
+        return { coinid: coinId, data };
     }
+    /**
+     * Get chain tip via Minima `status` RPC — parses response.chain.
+     */
     async getTip() {
-        const result = await this.fetchJson('/v1/status/tip');
-        if ('block' in result)
-            return result;
-        const r = result;
-        return (r.chain ?? r.tip);
+        const data = await this.rpc('status');
+        const chain = data?.chain;
+        return {
+            block: chain?.block ?? 0,
+            hash: chain?.hash ?? '',
+            time: chain?.time,
+        };
     }
+    /**
+     * Get token info via Minima `tokens tokenid:X` RPC command.
+     */
     async getToken(tokenId) {
-        return this.fetchJson(`/v1/tokens/${encodeURIComponent(tokenId)}`);
+        const data = await this.rpc(`tokens tokenid:${tokenId}`);
+        const t = Array.isArray(data) ? data[0] : data;
+        if (!t)
+            throw new Error(`Token not found: ${tokenId}`);
+        return this._mapToken(t);
     }
+    /**
+     * Search tokens via Minima `tokens` RPC command, then filter client-side.
+     */
     async searchTokens(query) {
-        const params = new URLSearchParams();
-        if (query.name)
-            params.set('name', query.name);
-        if (query.category?.length)
-            params.set('category', query.category.join(','));
-        if (query.creatorAddress)
-            params.set('creator', query.creatorAddress);
-        if (query.limit !== undefined)
-            params.set('limit', String(query.limit));
-        if (query.offset !== undefined)
-            params.set('offset', String(query.offset));
-        const qs = params.toString();
-        const result = await this.fetchJson(`/v1/tokens${qs ? `?${qs}` : ''}`);
-        return Array.isArray(result) ? result : (result.tokens ?? []);
+        const data = await this.rpc('tokens');
+        const all = Array.isArray(data) ? data : [];
+        return all
+            .filter((t) => {
+            if (t.tokenid === '0x00')
+                return false; // skip native Minima
+            if (query.name) {
+                const n = typeof t.name === 'object' ? (t.name?.name ?? '') : String(t.name ?? '');
+                if (!n.toLowerCase().includes(query.name.toLowerCase()))
+                    return false;
+            }
+            return true;
+        })
+            .slice(query.offset ?? 0, query.limit ? (query.offset ?? 0) + query.limit : undefined)
+            .map(this._mapToken);
     }
     async getTokensByCreator(address) {
         return this.searchTokens({ creatorAddress: address });
     }
+    /**
+     * Broadcast a mined TxPoW hex.
+     * Uses POST /api/meg/postminedtxn (the correct Axia MEG broadcast bridge).
+     */
     async broadcastTxPoW(txpowHex) {
         try {
-            const result = await this.fetchJson('/v1/txpow/broadcast', {
-                method: 'POST',
-                body: JSON.stringify({ txpow: txpowHex }),
-            });
-            return { success: true, txpowid: result.txpowid, message: result.message };
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            let result;
+            try {
+                const res = await fetch(`${this.baseUrl}/api/meg/postminedtxn`, {
+                    method: 'POST',
+                    signal: controller.signal,
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ data: txpowHex }),
+                });
+                result = await res.json();
+                if (!res.ok)
+                    return { success: false, message: `HTTP ${res.status}: ${result?.error ?? ''}` };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            return { success: true, txpowid: result?.txpowid, message: result?.message };
         }
         catch (e) {
             return { success: false, message: String(e) };
         }
     }
+    _mapToken(t) {
+        return {
+            tokenid: t.tokenid ?? '',
+            name: typeof t.name === 'object' ? t.name : { name: String(t.name ?? '') },
+            total: t.total,
+            confirmed: t.confirmed,
+            sendable: t.sendable,
+            coins: t.coins,
+            script: t.script,
+            description: t.description,
+        };
+    }
 }
+exports.HostedProvider = HostedProvider;

package/dist/providers/lookup-client.d.ts

@@ -0,0 +1,62 @@
+/**
+ * LookupClientProvider — ChainStateProvider backed by a @totemsdk/lookup-client instance.
+ *
+ * Accepts any object that satisfies LookupClientLike (structural duck-typing),
+ * so @totemsdk/lookup-client remains a peer dependency: chain-provider does not
+ * bundle or import it at runtime. The caller is responsible for constructing the
+ * LookupClient and passing it in.
+ *
+ * @example
+ * ```ts
+ * import { connectLookupNode, LookupClientProvider } from '@totemsdk/lookup-client';
+ *
+ * const client = await connectLookupNode({ hyperswarmTopic: 'deadbeef...' });
+ * const provider = new LookupClientProvider(client);
+ *
+ * const tip   = await provider.getTip();
+ * const coins = await provider.getCoins({ address: 'Mx...' });
+ * ```
+ *
+ * Use inside a CompositeProvider for sovereign-first / hosted-fallback:
+ *
+ * ```ts
+ * import { CompositeProvider, HostedProvider, LookupClientProvider } from '@totemsdk/chain-provider';
+ * import { connectLookupNode } from '@totemsdk/lookup-client';
+ *
+ * const client   = await connectLookupNode({ hyperswarmTopic: 'abc...' });
+ * const fallback = new HostedProvider({ baseUrl: 'https://api.axia.to', projectId: '...' });
+ *
+ * const provider = new CompositeProvider(
+ *   new LookupClientProvider(client),
+ *   fallback,
+ * );
+ * ```
+ */
+import type { BroadcastResult, ChainStateProvider, ChainTip, Coin, CoinsQuery, MMRProof, TokenInfo, TokenSearchQuery } from '../types.js';
+/**
+ * Structural interface describing the subset of LookupClient methods that
+ * LookupClientProvider requires. Any object satisfying this interface can be
+ * passed in — most commonly a `LookupClient` from @totemsdk/lookup-client.
+ */
+export interface LookupClientLike {
+    getCoins(query: CoinsQuery): Promise<Coin[]>;
+    getCoin(coinId: string): Promise<Coin | null>;
+    getProof(coinId: string): Promise<MMRProof>;
+    getTip(): Promise<ChainTip>;
+    getToken(tokenId: string): Promise<TokenInfo>;
+    searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]>;
+    getTokensByCreator(address: string): Promise<TokenInfo[]>;
+    broadcastTxPoW(txpowHex: string): Promise<BroadcastResult>;
+}
+export declare class LookupClientProvider implements ChainStateProvider {
+    private readonly _client;
+    constructor(_client: LookupClientLike);
+    getCoins(query: CoinsQuery): Promise<Coin[]>;
+    getCoin(coinId: string): Promise<Coin | null>;
+    getProof(coinId: string): Promise<MMRProof>;
+    getTip(): Promise<ChainTip>;
+    getToken(tokenId: string): Promise<TokenInfo>;
+    searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]>;
+    getTokensByCreator(address: string): Promise<TokenInfo[]>;
+    broadcastTxPoW(txpowHex: string): Promise<BroadcastResult>;
+}

package/dist/providers/lookup-client.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * LookupClientProvider — ChainStateProvider backed by a @totemsdk/lookup-client instance.
+ *
+ * Accepts any object that satisfies LookupClientLike (structural duck-typing),
+ * so @totemsdk/lookup-client remains a peer dependency: chain-provider does not
+ * bundle or import it at runtime. The caller is responsible for constructing the
+ * LookupClient and passing it in.
+ *
+ * @example
+ * ```ts
+ * import { connectLookupNode, LookupClientProvider } from '@totemsdk/lookup-client';
+ *
+ * const client = await connectLookupNode({ hyperswarmTopic: 'deadbeef...' });
+ * const provider = new LookupClientProvider(client);
+ *
+ * const tip   = await provider.getTip();
+ * const coins = await provider.getCoins({ address: 'Mx...' });
+ * ```
+ *
+ * Use inside a CompositeProvider for sovereign-first / hosted-fallback:
+ *
+ * ```ts
+ * import { CompositeProvider, HostedProvider, LookupClientProvider } from '@totemsdk/chain-provider';
+ * import { connectLookupNode } from '@totemsdk/lookup-client';
+ *
+ * const client   = await connectLookupNode({ hyperswarmTopic: 'abc...' });
+ * const fallback = new HostedProvider({ baseUrl: 'https://api.axia.to', projectId: '...' });
+ *
+ * const provider = new CompositeProvider(
+ *   new LookupClientProvider(client),
+ *   fallback,
+ * );
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LookupClientProvider = void 0;
+class LookupClientProvider {
+    constructor(_client) {
+        this._client = _client;
+    }
+    getCoins(query) {
+        return this._client.getCoins(query);
+    }
+    getCoin(coinId) {
+        return this._client.getCoin(coinId);
+    }
+    getProof(coinId) {
+        return this._client.getProof(coinId);
+    }
+    getTip() {
+        return this._client.getTip();
+    }
+    getToken(tokenId) {
+        return this._client.getToken(tokenId);
+    }
+    searchTokens(query) {
+        return this._client.searchTokens(query);
+    }
+    getTokensByCreator(address) {
+        return this._client.getTokensByCreator(address);
+    }
+    broadcastTxPoW(txpowHex) {
+        return this._client.broadcastTxPoW(txpowHex);
+    }
+}
+exports.LookupClientProvider = LookupClientProvider;

package/dist/providers/lookup.js

@@ -1,10 +1,13 @@
+"use strict";
 /**
  * LookupNodeProvider — stub.
  *
  * Full implementation lives in @totemsdk/lookup-client which replaces this
  * stub once the lookup node package is available.
  */
-export class LookupNodeNotImplementedError extends Error {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LookupNodeProvider = exports.LookupNodeNotImplementedError = void 0;
+class LookupNodeNotImplementedError extends Error {
     constructor() {
         super('LookupNodeProvider is not yet implemented. ' +
             'Install @totemsdk/lookup-client and use LookupClientProvider instead. ' +
@@ -12,7 +15,8 @@ export class LookupNodeNotImplementedError extends Error {
         this.name = 'LookupNodeNotImplementedError';
     }
 }
-export class LookupNodeProvider {
+exports.LookupNodeNotImplementedError = LookupNodeNotImplementedError;
+class LookupNodeProvider {
     getCoins(_query) {
         throw new LookupNodeNotImplementedError();
     }
@@ -38,3 +42,4 @@ export class LookupNodeProvider {
         throw new LookupNodeNotImplementedError();
     }
 }
+exports.LookupNodeProvider = LookupNodeProvider;

package/dist/providers/pureminima.js

@@ -1,7 +1,10 @@
+"use strict";
 /**
  * PureMinimaRpcProvider — thin wrapper over @totemsdk/pureminima-rpc.
  */
-export class PureMinimaRpcProvider {
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PureMinimaRpcProvider = void 0;
+class PureMinimaRpcProvider {
     constructor(client) {
         this.client = client;
     }
@@ -78,3 +81,4 @@ export class PureMinimaRpcProvider {
         }
     }
 }
+exports.PureMinimaRpcProvider = PureMinimaRpcProvider;

package/dist/types.js

@@ -1,4 +1,5 @@
+"use strict";
 /**
  * @totemsdk/chain-provider — shared types and ChainStateProvider interface
  */
-export {};
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@totemsdk/chain-provider",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Unified ChainStateProvider interface for Totem SDK — Hosted, PureMinima, Composite",
-  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
       "import": "./dist/index.js"
     }
   },
   "files": [
     "dist",
-    "src"
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
-    "@totemsdk/core": "1.0.9",
-    "@totemsdk/pureminima-rpc": "0.1.2"
+    "@totemsdk/core": "1.1.0",
+    "@totemsdk/pureminima-rpc": "0.1.3"
   },
   "devDependencies": {
-    "@noble/hashes": "^1.3.0",
+    "@noble/hashes": "^2.2.0",
     "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
     "jest": "^29.0.0",
@@ -34,6 +35,31 @@
     "access": "public"
   },
   "license": "MIT",
+  "author": "Totem SDK",
+  "homepage": "https://totemsdk.com",
+  "bugs": {
+    "url": "https://github.com/MrGheek/axia-totem/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrGheek/axia-totem.git",
+    "directory": "packages/totem-sdk/packages/chain-provider"
+  },
+  "keywords": [
+    "totem",
+    "totemsdk",
+    "minima",
+    "blockchain",
+    "quantum-resistant",
+    "wots",
+    "kissvm",
+    "utxo",
+    "chain-provider",
+    "rpc",
+    "provider",
+    "chain-data",
+    "strategy-pattern"
+  ],
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",

package/src/__tests__/chain-provider.test.ts

@@ -1,116 +0,0 @@
-import { HostedProvider } from '../providers/hosted';
-import { CompositeProvider } from '../providers/composite';
-import { LookupNodeProvider, LookupNodeNotImplementedError } from '../providers/lookup';
-import type { ChainStateProvider, ChainTip } from '../types';
-
-function mockFetchJson(data: unknown, ok = true, status = 200) {
-  global.fetch = jest.fn().mockResolvedValue({
-    ok,
-    status,
-    json: () => Promise.resolve(data),
-  }) as unknown as typeof fetch;
-}
-
-afterEach(() => jest.restoreAllMocks());
-
-describe('HostedProvider', () => {
-  const provider = new HostedProvider({ baseUrl: 'https://api.axia.to', apiKey: 'test-key' });
-
-  it('getCoins passes query params', async () => {
-    mockFetchJson([]);
-    await provider.getCoins({ address: 'Mx123', sendable: true });
-    const url = (global.fetch as jest.Mock).mock.calls[0][0] as string;
-    expect(url).toContain('address=Mx123');
-    expect(url).toContain('sendable=true');
-  });
-
-  it('getCoins unwraps { coins: [] } response shape', async () => {
-    mockFetchJson({ coins: [{ coinid: '0xABC' }] });
-    const coins = await provider.getCoins({});
-    expect(coins[0].coinid).toBe('0xABC');
-  });
-
-  it('getTip handles flat ChainTip response', async () => {
-    mockFetchJson({ block: 100, hash: '0xHASH', time: '2024-01-01' });
-    const tip = await provider.getTip();
-    expect(tip.block).toBe(100);
-  });
-
-  it('getTip unwraps nested chain.block response', async () => {
-    mockFetchJson({ chain: { block: 200, hash: '0xHASH2' } });
-    const tip = await provider.getTip();
-    expect(tip.block).toBe(200);
-  });
-
-  it('broadcastTxPoW returns success:true on ok response', async () => {
-    mockFetchJson({ txpowid: '0xTXID' });
-    const result = await provider.broadcastTxPoW('0xDEAD');
-    expect(result.success).toBe(true);
-    expect(result.txpowid).toBe('0xTXID');
-  });
-
-  it('broadcastTxPoW returns success:false on fetch error', async () => {
-    global.fetch = jest.fn().mockRejectedValue(new Error('network down')) as unknown as typeof fetch;
-    const result = await provider.broadcastTxPoW('0xDEAD');
-    expect(result.success).toBe(false);
-  });
-
-  it('attaches x-api-key header', async () => {
-    mockFetchJson({ block: 1, hash: '0x' });
-    await provider.getTip();
-    const headers = (global.fetch as jest.Mock).mock.calls[0][1].headers as Record<string, string>;
-    expect(headers['x-api-key']).toBe('test-key');
-  });
-});
-
-describe('CompositeProvider', () => {
-  function makeProvider(tip: ChainTip, shouldFail = false): ChainStateProvider {
-    return {
-      getCoins: jest.fn().mockResolvedValue([]),
-      getCoin: jest.fn().mockResolvedValue(null),
-      getProof: jest.fn().mockResolvedValue({}),
-      getTip: shouldFail
-        ? jest.fn().mockRejectedValue(new Error('primary down'))
-        : jest.fn().mockResolvedValue(tip),
-      getToken: jest.fn().mockResolvedValue({}),
-      searchTokens: jest.fn().mockResolvedValue([]),
-      getTokensByCreator: jest.fn().mockResolvedValue([]),
-      broadcastTxPoW: jest.fn().mockResolvedValue({ success: true }),
-    };
-  }
-
-  it('uses primary when it succeeds', async () => {
-    const primary = makeProvider({ block: 10, hash: '0xA' });
-    const fallback = makeProvider({ block: 5, hash: '0xB' });
-    const composite = new CompositeProvider(primary, fallback);
-    const tip = await composite.getTip();
-    expect(tip.block).toBe(10);
-    expect(fallback.getTip).not.toHaveBeenCalled();
-  });
-
-  it('falls back to secondary when primary fails', async () => {
-    const primary = makeProvider({ block: 10, hash: '0xA' }, true);
-    const fallback = makeProvider({ block: 5, hash: '0xB' });
-    const composite = new CompositeProvider(primary, fallback);
-    const tip = await composite.getTip();
-    expect(tip.block).toBe(5);
-  });
-
-  it('calls onFallback callback when falling back', async () => {
-    const onFallback = jest.fn();
-    const primary = makeProvider({ block: 10, hash: '0xA' }, true);
-    const fallback = makeProvider({ block: 5, hash: '0xB' });
-    const composite = new CompositeProvider(primary, fallback, onFallback);
-    await composite.getTip();
-    expect(onFallback).toHaveBeenCalledWith('getTip', expect.any(Error));
-  });
-});
-
-describe('LookupNodeProvider', () => {
-  it('throws LookupNodeNotImplementedError on all methods', () => {
-    const p = new LookupNodeProvider();
-    expect(() => p.getTip()).toThrow(LookupNodeNotImplementedError);
-    expect(() => p.getCoins({})).toThrow(LookupNodeNotImplementedError);
-    expect(() => p.broadcastTxPoW('0x')).toThrow(LookupNodeNotImplementedError);
-  });
-});

package/src/index.ts

@@ -1,19 +0,0 @@
-export type {
-  ChainStateProvider,
-  CoinsQuery,
-  Coin,
-  MMRProof,
-  ChainTip,
-  TokenInfo,
-  TokenSearchQuery,
-  BroadcastResult,
-} from './types.js';
-
-export { HostedProvider } from './providers/hosted.js';
-export type { HostedProviderConfig } from './providers/hosted.js';
-
-export { PureMinimaRpcProvider } from './providers/pureminima.js';
-
-export { LookupNodeProvider, LookupNodeNotImplementedError } from './providers/lookup.js';
-
-export { CompositeProvider } from './providers/composite.js';

package/src/providers/composite.ts

@@ -1,72 +0,0 @@
-/**
- * CompositeProvider — tries primary provider, falls back to secondary on any error.
- */
-
-import type {
-  ChainStateProvider,
-  CoinsQuery,
-  Coin,
-  MMRProof,
-  ChainTip,
-  TokenInfo,
-  TokenSearchQuery,
-  BroadcastResult,
-} from '../types.js';
-
-export class CompositeProvider implements ChainStateProvider {
-  constructor(
-    private readonly primary: ChainStateProvider,
-    private readonly fallback: ChainStateProvider,
-    private readonly onFallback?: (method: string, error: unknown) => void,
-  ) {}
-
-  private withArg<T>(method: string, arg: unknown): Promise<T> {
-    const p = this.primary as unknown as Record<string, (a: unknown) => Promise<T>>;
-    const f = this.fallback as unknown as Record<string, (a: unknown) => Promise<T>>;
-    return p[method](arg).catch((err: unknown) => {
-      this.onFallback?.(method, err);
-      return f[method](arg);
-    });
-  }
-
-  private withNoArg<T>(method: string): Promise<T> {
-    const p = this.primary as unknown as Record<string, () => Promise<T>>;
-    const f = this.fallback as unknown as Record<string, () => Promise<T>>;
-    return p[method]().catch((err: unknown) => {
-      this.onFallback?.(method, err);
-      return f[method]();
-    });
-  }
-
-  getCoins(query: CoinsQuery): Promise<Coin[]> {
-    return this.withArg('getCoins', query);
-  }
-
-  getCoin(coinId: string): Promise<Coin | null> {
-    return this.withArg('getCoin', coinId);
-  }
-
-  getProof(coinId: string): Promise<MMRProof> {
-    return this.withArg('getProof', coinId);
-  }
-
-  getTip(): Promise<ChainTip> {
-    return this.withNoArg('getTip');
-  }
-
-  getToken(tokenId: string): Promise<TokenInfo> {
-    return this.withArg('getToken', tokenId);
-  }
-
-  searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]> {
-    return this.withArg('searchTokens', query);
-  }
-
-  getTokensByCreator(address: string): Promise<TokenInfo[]> {
-    return this.withArg('getTokensByCreator', address);
-  }
-
-  broadcastTxPoW(txpowHex: string): Promise<BroadcastResult> {
-    return this.withArg('broadcastTxPoW', txpowHex);
-  }
-}

package/src/providers/hosted.ts

@@ -1,129 +0,0 @@
-/**
- * HostedProvider — wraps existing Axia REST API endpoints.
- * Uses fetch only; no Node.js-specific dependencies.
- */
-
-import type {
-  ChainStateProvider,
-  CoinsQuery,
-  Coin,
-  MMRProof,
-  ChainTip,
-  TokenInfo,
-  TokenSearchQuery,
-  BroadcastResult,
-} from '../types.js';
-
-export interface HostedProviderConfig {
-  baseUrl: string;
-  apiKey: string;
-  timeoutMs?: number;
-}
-
-export class HostedProvider implements ChainStateProvider {
-  private readonly baseUrl: string;
-  private readonly apiKey: string;
-  private readonly timeoutMs: number;
-
-  constructor(config: HostedProviderConfig) {
-    this.baseUrl = config.baseUrl.replace(/\/$/, '');
-    this.apiKey = config.apiKey;
-    this.timeoutMs = config.timeoutMs ?? 30_000;
-  }
-
-  private async fetchJson<T>(path: string, init?: RequestInit): Promise<T> {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-    try {
-      const res = await fetch(`${this.baseUrl}${path}`, {
-        ...init,
-        signal: controller.signal,
-        headers: {
-          'x-api-key': this.apiKey,
-          'Content-Type': 'application/json',
-          ...((init?.headers as Record<string, string>) ?? {}),
-        },
-      });
-      if (!res.ok) {
-        throw new Error(`HostedProvider HTTP ${res.status} for ${path}`);
-      }
-      return res.json() as Promise<T>;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  async getCoins(query: CoinsQuery): Promise<Coin[]> {
-    const params = new URLSearchParams();
-    if (query.address) params.set('address', query.address);
-    if (query.tokenId) params.set('tokenid', query.tokenId);
-    if (query.sendable !== undefined) params.set('sendable', String(query.sendable));
-    if (query.relevant !== undefined) params.set('relevant', String(query.relevant));
-    if (query.coinId) params.set('coinid', query.coinId);
-    if (query.megammr !== undefined) params.set('megammr', String(query.megammr));
-    const qs = params.toString();
-    const result = await this.fetchJson<{ coins?: Coin[] } | Coin[]>(
-      `/v1/wallet/coins${qs ? `?${qs}` : ''}`,
-    );
-    return Array.isArray(result) ? result : (result.coins ?? []);
-  }
-
-  async getCoin(coinId: string): Promise<Coin | null> {
-    try {
-      const coins = await this.getCoins({ coinId });
-      return coins[0] ?? null;
-    } catch {
-      return null;
-    }
-  }
-
-  async getProof(coinId: string): Promise<MMRProof> {
-    return this.fetchJson<MMRProof>(`/v1/wallet/proofs/${encodeURIComponent(coinId)}`);
-  }
-
-  async getTip(): Promise<ChainTip> {
-    const result = await this.fetchJson<{ chain?: ChainTip; tip?: ChainTip } | ChainTip>(
-      '/v1/status/tip',
-    );
-    if ('block' in result) return result as ChainTip;
-    const r = result as { chain?: ChainTip; tip?: ChainTip };
-    return (r.chain ?? r.tip) as ChainTip;
-  }
-
-  async getToken(tokenId: string): Promise<TokenInfo> {
-    return this.fetchJson<TokenInfo>(`/v1/tokens/${encodeURIComponent(tokenId)}`);
-  }
-
-  async searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]> {
-    const params = new URLSearchParams();
-    if (query.name) params.set('name', query.name);
-    if (query.category?.length) params.set('category', query.category.join(','));
-    if (query.creatorAddress) params.set('creator', query.creatorAddress);
-    if (query.limit !== undefined) params.set('limit', String(query.limit));
-    if (query.offset !== undefined) params.set('offset', String(query.offset));
-    const qs = params.toString();
-    const result = await this.fetchJson<{ tokens?: TokenInfo[] } | TokenInfo[]>(
-      `/v1/tokens${qs ? `?${qs}` : ''}`,
-    );
-    return Array.isArray(result) ? result : (result.tokens ?? []);
-  }
-
-  async getTokensByCreator(address: string): Promise<TokenInfo[]> {
-    return this.searchTokens({ creatorAddress: address });
-  }
-
-  async broadcastTxPoW(txpowHex: string): Promise<BroadcastResult> {
-    try {
-      const result = await this.fetchJson<{ txpowid?: string; message?: string }>(
-        '/v1/txpow/broadcast',
-        {
-          method: 'POST',
-          body: JSON.stringify({ txpow: txpowHex }),
-        },
-      );
-      return { success: true, txpowid: result.txpowid, message: result.message };
-    } catch (e) {
-      return { success: false, message: String(e) };
-    }
-  }
-}

package/src/providers/lookup.ts

@@ -1,55 +0,0 @@
-/**
- * LookupNodeProvider — stub.
- *
- * Full implementation lives in @totemsdk/lookup-client which replaces this
- * stub once the lookup node package is available.
- */
-
-import type {
-  ChainStateProvider,
-  CoinsQuery,
-  Coin,
-  MMRProof,
-  ChainTip,
-  TokenInfo,
-  TokenSearchQuery,
-  BroadcastResult,
-} from '../types.js';
-
-export class LookupNodeNotImplementedError extends Error {
-  constructor() {
-    super(
-      'LookupNodeProvider is not yet implemented. ' +
-        'Install @totemsdk/lookup-client and use LookupClientProvider instead. ' +
-        'See https://github.com/Totem/totem-sdk for setup instructions.',
-    );
-    this.name = 'LookupNodeNotImplementedError';
-  }
-}
-
-export class LookupNodeProvider implements ChainStateProvider {
-  getCoins(_query: CoinsQuery): Promise<Coin[]> {
-    throw new LookupNodeNotImplementedError();
-  }
-  getCoin(_coinId: string): Promise<Coin | null> {
-    throw new LookupNodeNotImplementedError();
-  }
-  getProof(_coinId: string): Promise<MMRProof> {
-    throw new LookupNodeNotImplementedError();
-  }
-  getTip(): Promise<ChainTip> {
-    throw new LookupNodeNotImplementedError();
-  }
-  getToken(_tokenId: string): Promise<TokenInfo> {
-    throw new LookupNodeNotImplementedError();
-  }
-  searchTokens(_query: TokenSearchQuery): Promise<TokenInfo[]> {
-    throw new LookupNodeNotImplementedError();
-  }
-  getTokensByCreator(_address: string): Promise<TokenInfo[]> {
-    throw new LookupNodeNotImplementedError();
-  }
-  broadcastTxPoW(_txpowHex: string): Promise<BroadcastResult> {
-    throw new LookupNodeNotImplementedError();
-  }
-}

package/src/providers/pureminima.ts

@@ -1,95 +0,0 @@
-/**
- * PureMinimaRpcProvider — thin wrapper over @totemsdk/pureminima-rpc.
- */
-
-import type { PureMinimaClient } from '@totemsdk/pureminima-rpc';
-import type {
-  ChainStateProvider,
-  CoinsQuery,
-  Coin,
-  MMRProof,
-  ChainTip,
-  TokenInfo,
-  TokenSearchQuery,
-  BroadcastResult,
-} from '../types.js';
-
-export class PureMinimaRpcProvider implements ChainStateProvider {
-  constructor(private readonly client: PureMinimaClient) {}
-
-  async getCoins(query: CoinsQuery): Promise<Coin[]> {
-    const result = await this.client.coins({
-      address: query.address,
-      tokenid: query.tokenId,
-      sendable: query.sendable,
-      relevant: query.relevant,
-      coinid: query.coinId,
-      megammr: query.megammr,
-    });
-    return result as unknown as Coin[];
-  }
-
-  async getCoin(coinId: string): Promise<Coin | null> {
-    try {
-      const coins = await this.getCoins({ coinId });
-      return coins[0] ?? null;
-    } catch {
-      return null;
-    }
-  }
-
-  async getProof(coinId: string): Promise<MMRProof> {
-    return this.client.mmrProof(coinId) as unknown as MMRProof;
-  }
-
-  async getTip(): Promise<ChainTip> {
-    return this.client.getTip() as unknown as ChainTip;
-  }
-
-  async getToken(tokenId: string): Promise<TokenInfo> {
-    const tokens = await this.client.tokens(tokenId);
-    if (!tokens || tokens.length === 0) {
-      throw new Error(`Token not found: ${tokenId}`);
-    }
-    return tokens[0] as unknown as TokenInfo;
-  }
-
-  async searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]> {
-    const all = await this.client.tokens();
-    let results = all as unknown as TokenInfo[];
-    if (query.name) {
-      const needle = query.name.toLowerCase();
-      results = results.filter((t) => {
-        const nameStr = JSON.stringify(t.name ?? '').toLowerCase();
-        return nameStr.includes(needle);
-      });
-    }
-    if (query.creatorAddress) {
-      const addr = query.creatorAddress;
-      results = results.filter((t) => {
-        const desc = JSON.stringify(t.description ?? '');
-        return desc.includes(addr);
-      });
-    }
-    if (query.offset) results = results.slice(query.offset);
-    if (query.limit) results = results.slice(0, query.limit);
-    return results;
-  }
-
-  async getTokensByCreator(address: string): Promise<TokenInfo[]> {
-    return this.searchTokens({ creatorAddress: address });
-  }
-
-  async broadcastTxPoW(txpowHex: string): Promise<BroadcastResult> {
-    try {
-      const result = await this.client.txnMinePost(txpowHex);
-      return {
-        success: true,
-        txpowid: result?.txpowid,
-        message: 'broadcast via PureMinima txnminepost',
-      };
-    } catch (e) {
-      return { success: false, message: String(e) };
-    }
-  }
-}

package/src/types.ts

@@ -1,73 +0,0 @@
-/**
- * @totemsdk/chain-provider — shared types and ChainStateProvider interface
- */
-
-export interface CoinsQuery {
-  address?: string;
-  tokenId?: string;
-  sendable?: boolean;
-  relevant?: boolean;
-  coinId?: string;
-  megammr?: boolean;
-}
-
-export interface Coin {
-  coinid: string;
-  amount: string;
-  address: string;
-  miniaddress?: string;
-  tokenid: string;
-  token?: unknown;
-  storestate?: boolean;
-  state?: unknown[];
-  spent?: boolean;
-  mmrentry?: string;
-  created?: string;
-}
-
-export interface MMRProof {
-  coinid: string;
-  data: unknown;
-}
-
-export interface ChainTip {
-  block: number;
-  hash: string;
-  time?: string;
-}
-
-export interface TokenInfo {
-  tokenid: string;
-  name: Record<string, unknown>;
-  total?: string;
-  confirmed?: string;
-  sendable?: string;
-  coins?: number;
-  script?: string;
-  description?: unknown;
-}
-
-export interface TokenSearchQuery {
-  name?: string;
-  category?: string[];
-  creatorAddress?: string;
-  limit?: number;
-  offset?: number;
-}
-
-export interface BroadcastResult {
-  txpowid?: string;
-  success: boolean;
-  message?: string;
-}
-
-export interface ChainStateProvider {
-  getCoins(query: CoinsQuery): Promise<Coin[]>;
-  getCoin(coinId: string): Promise<Coin | null>;
-  getProof(coinId: string): Promise<MMRProof>;
-  getTip(): Promise<ChainTip>;
-  getToken(tokenId: string): Promise<TokenInfo>;
-  searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]>;
-  getTokensByCreator(address: string): Promise<TokenInfo[]>;
-  broadcastTxPoW(txpowHex: string): Promise<BroadcastResult>;
-}