@totemsdk/chain-provider 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/index.js

@@ -0,0 +1,4 @@
+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';

package/dist/providers/composite.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare class CompositeProvider implements ChainStateProvider {
+    private readonly primary;
+    private readonly fallback;
+    private readonly onFallback?;
+    constructor(primary: ChainStateProvider, fallback: ChainStateProvider, onFallback?: ((method: string, error: unknown) => void) | undefined);
+    private withArg;
+    private withNoArg;
+    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/composite.js

@@ -0,0 +1,50 @@
+/**
+ * CompositeProvider — tries primary provider, falls back to secondary on any error.
+ */
+export class CompositeProvider {
+    constructor(primary, fallback, onFallback) {
+        this.primary = primary;
+        this.fallback = fallback;
+        this.onFallback = onFallback;
+    }
+    withArg(method, arg) {
+        const p = this.primary;
+        const f = this.fallback;
+        return p[method](arg).catch((err) => {
+            this.onFallback?.(method, err);
+            return f[method](arg);
+        });
+    }
+    withNoArg(method) {
+        const p = this.primary;
+        const f = this.fallback;
+        return p[method]().catch((err) => {
+            this.onFallback?.(method, err);
+            return f[method]();
+        });
+    }
+    getCoins(query) {
+        return this.withArg('getCoins', query);
+    }
+    getCoin(coinId) {
+        return this.withArg('getCoin', coinId);
+    }
+    getProof(coinId) {
+        return this.withArg('getProof', coinId);
+    }
+    getTip() {
+        return this.withNoArg('getTip');
+    }
+    getToken(tokenId) {
+        return this.withArg('getToken', tokenId);
+    }
+    searchTokens(query) {
+        return this.withArg('searchTokens', query);
+    }
+    getTokensByCreator(address) {
+        return this.withArg('getTokensByCreator', address);
+    }
+    broadcastTxPoW(txpowHex) {
+        return this.withArg('broadcastTxPoW', txpowHex);
+    }
+}

package/dist/providers/hosted.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare class HostedProvider implements ChainStateProvider {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    constructor(config: HostedProviderConfig);
+    private fetchJson;
+    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/hosted.js

@@ -0,0 +1,104 @@
+/**
+ * HostedProvider — wraps existing Axia REST API endpoints.
+ * Uses fetch only; no Node.js-specific dependencies.
+ */
+export class HostedProvider {
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.timeoutMs = config.timeoutMs ?? 30000;
+    }
+    async fetchJson(path, init) {
+        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 ?? {}),
+                },
+            });
+            if (!res.ok) {
+                throw new Error(`HostedProvider HTTP ${res.status} for ${path}`);
+            }
+            return res.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    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 ?? []);
+    }
+    async getCoin(coinId) {
+        try {
+            const coins = await this.getCoins({ coinId });
+            return coins[0] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getProof(coinId) {
+        return this.fetchJson(`/v1/wallet/proofs/${encodeURIComponent(coinId)}`);
+    }
+    async getTip() {
+        const result = await this.fetchJson('/v1/status/tip');
+        if ('block' in result)
+            return result;
+        const r = result;
+        return (r.chain ?? r.tip);
+    }
+    async getToken(tokenId) {
+        return this.fetchJson(`/v1/tokens/${encodeURIComponent(tokenId)}`);
+    }
+    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 ?? []);
+    }
+    async getTokensByCreator(address) {
+        return this.searchTokens({ creatorAddress: address });
+    }
+    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 };
+        }
+        catch (e) {
+            return { success: false, message: String(e) };
+        }
+    }
+}

package/dist/providers/lookup.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare class LookupNodeNotImplementedError extends Error {
+    constructor();
+}
+export declare class LookupNodeProvider implements 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>;
+}

package/dist/providers/lookup.js

@@ -0,0 +1,40 @@
+/**
+ * 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 {
+    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 {
+    getCoins(_query) {
+        throw new LookupNodeNotImplementedError();
+    }
+    getCoin(_coinId) {
+        throw new LookupNodeNotImplementedError();
+    }
+    getProof(_coinId) {
+        throw new LookupNodeNotImplementedError();
+    }
+    getTip() {
+        throw new LookupNodeNotImplementedError();
+    }
+    getToken(_tokenId) {
+        throw new LookupNodeNotImplementedError();
+    }
+    searchTokens(_query) {
+        throw new LookupNodeNotImplementedError();
+    }
+    getTokensByCreator(_address) {
+        throw new LookupNodeNotImplementedError();
+    }
+    broadcastTxPoW(_txpowHex) {
+        throw new LookupNodeNotImplementedError();
+    }
+}

package/dist/providers/pureminima.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare class PureMinimaRpcProvider implements ChainStateProvider {
+    private readonly client;
+    constructor(client: PureMinimaClient);
+    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/pureminima.js

@@ -0,0 +1,80 @@
+/**
+ * PureMinimaRpcProvider — thin wrapper over @totemsdk/pureminima-rpc.
+ */
+export class PureMinimaRpcProvider {
+    constructor(client) {
+        this.client = client;
+    }
+    async getCoins(query) {
+        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;
+    }
+    async getCoin(coinId) {
+        try {
+            const coins = await this.getCoins({ coinId });
+            return coins[0] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getProof(coinId) {
+        return this.client.mmrProof(coinId);
+    }
+    async getTip() {
+        return this.client.getTip();
+    }
+    async getToken(tokenId) {
+        const tokens = await this.client.tokens(tokenId);
+        if (!tokens || tokens.length === 0) {
+            throw new Error(`Token not found: ${tokenId}`);
+        }
+        return tokens[0];
+    }
+    async searchTokens(query) {
+        const all = await this.client.tokens();
+        let results = all;
+        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) {
+        return this.searchTokens({ creatorAddress: address });
+    }
+    async broadcastTxPoW(txpowHex) {
+        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/dist/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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>;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * @totemsdk/chain-provider — shared types and ChainStateProvider interface
+ */
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@totemsdk/chain-provider",
+  "version": "0.1.0",
+  "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",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@totemsdk/core": "workspace:*",
+    "@totemsdk/pureminima-rpc": "workspace:*"
+  },
+  "devDependencies": {
+    "@noble/hashes": "^1.3.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,116 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,72 @@
+/**
+ * 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

@@ -0,0 +1,129 @@
+/**
+ * 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

@@ -0,0 +1,55 @@
+/**
+ * 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

@@ -0,0 +1,95 @@
+/**
+ * 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

@@ -0,0 +1,73 @@
+/**
+ * @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>;
+}