@totemsdk/edge-adapters 0.2.0 → 0.3.0

package/dist/artifact-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * edge-adapters/artifact-cache.ts — RFC-007 Amendment A, phase A1.
+ *
+ * The first consumer of the Edge persistence injection point (`PersistencePorts`).
+ * A scoped, content-addressed artifact cache over the injected `storage` (KV
+ * retention index) and `artifacts` (byte store) surfaces.
+ *
+ * Typed structurally against `@totemsdk/storage` — this module must NOT import
+ * `@totemsdk/edge`, so it carries no Edge runtime dependency.
+ *
+ * Guarantees:
+ *   - `assertPersistence()` validates surfaces/capabilities at construction.
+ *   - Scope is collision-control only (namespaces); authorization stays above.
+ *   - Retrieval re-verifies digests via `ArtifactStore.get` (`corrupt` vs
+ *     `not-found` are never conflated).
+ *   - Retention/expiry entries survive restart when the injected storage is durable.
+ */
+import type { ArtifactBackendCapabilities, ArtifactRead, ArtifactRef, EffectivePersistence, PersistencePorts, PersistenceRequirement, StorageScope } from '@totemsdk/storage';
+/**
+ * Per-object cache policy. Deliberately does NOT reuse the `retention:
+ * 'fixed'|'managed'|'none'` vocabulary: that is a BACKEND capability, not a
+ * per-object request.
+ */
+export interface ArtifactCacheRetentionPolicy {
+    readonly ttlMs?: number;
+    readonly invalidateOnExpiry?: boolean;
+}
+export interface EdgeArtifactCache {
+    readonly capabilities: ArtifactBackendCapabilities;
+    /** Reported after assertPersistence(); callers must never assume durability. */
+    readonly effective: EffectivePersistence;
+    put(scope: StorageScope, bytes: Uint8Array, policy?: ArtifactCacheRetentionPolicy): Promise<ArtifactRef>;
+    get(scope: StorageScope, ref: ArtifactRef, policy?: ArtifactCacheRetentionPolicy): Promise<ArtifactRead>;
+    invalidate(scope: StorageScope, ref: ArtifactRef): Promise<void>;
+}
+export declare function createEdgeArtifactCache(ports: PersistencePorts, requirement?: PersistenceRequirement, policy?: ArtifactCacheRetentionPolicy): EdgeArtifactCache;

package/dist/artifact-cache.js

@@ -0,0 +1,79 @@
+/**
+ * edge-adapters/artifact-cache.ts — RFC-007 Amendment A, phase A1.
+ *
+ * The first consumer of the Edge persistence injection point (`PersistencePorts`).
+ * A scoped, content-addressed artifact cache over the injected `storage` (KV
+ * retention index) and `artifacts` (byte store) surfaces.
+ *
+ * Typed structurally against `@totemsdk/storage` — this module must NOT import
+ * `@totemsdk/edge`, so it carries no Edge runtime dependency.
+ *
+ * Guarantees:
+ *   - `assertPersistence()` validates surfaces/capabilities at construction.
+ *   - Scope is collision-control only (namespaces); authorization stays above.
+ *   - Retrieval re-verifies digests via `ArtifactStore.get` (`corrupt` vs
+ *     `not-found` are never conflated).
+ *   - Retention/expiry entries survive restart when the injected storage is durable.
+ */
+import { StorageError, artifactRefId, assertPersistence, createScopedStorage, } from '@totemsdk/storage';
+/** Scope-derived artifact namespace: separate scopes never alias the same blob. */
+function scopeNamespace(scope) {
+    const parts = [scope.principal, scope.adapter, scope.purpose, scope.domain]
+        .filter((p) => typeof p === 'string' && p.length > 0)
+        .map((p) => encodeURIComponent(p));
+    return `edge-cache:${parts.join('/')}`;
+}
+export function createEdgeArtifactCache(ports, requirement = { durable: false }, policy = {}) {
+    const label = 'edge-artifact-cache';
+    // The cache always needs both surfaces and a deletable artifact backend.
+    const effective = assertPersistence(ports, { ...requirement, needsArtifacts: true, needsArtifactDelete: true }, label);
+    const storage = ports.storage;
+    const artifacts = ports.artifacts;
+    if (!storage) {
+        throw new StorageError(`${label}: a storage index is required for retention/expiry`, 'unavailable');
+    }
+    if (!artifacts) {
+        throw new StorageError(`${label}: an artifact store is required`, 'unavailable');
+    }
+    const defaultTtlMs = policy.ttlMs;
+    const defaultInvalidateOnExpiry = policy.invalidateOnExpiry ?? false;
+    const now = () => Date.now();
+    const scoped = (scope) => createScopedStorage(storage, scope);
+    return {
+        capabilities: artifacts.capabilities,
+        effective,
+        async put(scope, bytes, putPolicy) {
+            const ttlMs = putPolicy?.ttlMs ?? defaultTtlMs;
+            const receipt = await artifacts.put(scopeNamespace(scope), bytes, {
+                ...(ttlMs !== undefined ? { retentionMs: ttlMs } : {}),
+            });
+            const entry = {
+                ref: receipt.ref,
+                size: receipt.size,
+                createdAt: now(),
+                ...(ttlMs !== undefined ? { expiresAt: now() + ttlMs } : {}),
+            };
+            await scoped(scope).set(artifactRefId(receipt.ref), entry);
+            return receipt.ref;
+        },
+        async get(scope, ref, getPolicy) {
+            const entry = await scoped(scope).get(artifactRefId(ref));
+            if (!entry) {
+                // Not known to this scope — never fall through to the raw backend.
+                return { status: 'not-found' };
+            }
+            if (entry.expiresAt !== undefined && now() > entry.expiresAt) {
+                const invalidate = getPolicy?.invalidateOnExpiry ?? defaultInvalidateOnExpiry;
+                if (invalidate)
+                    await this.invalidate(scope, ref);
+                return { status: 'not-found' };
+            }
+            // Digest re-verification + corrupt/not-found taxonomy live in ArtifactStore.
+            return artifacts.get(ref);
+        },
+        async invalidate(scope, ref) {
+            await artifacts.delete(ref);
+            await scoped(scope).remove(artifactRefId(ref));
+        },
+    };
+}

package/dist/cjs/artifact-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * edge-adapters/artifact-cache.ts — RFC-007 Amendment A, phase A1.
+ *
+ * The first consumer of the Edge persistence injection point (`PersistencePorts`).
+ * A scoped, content-addressed artifact cache over the injected `storage` (KV
+ * retention index) and `artifacts` (byte store) surfaces.
+ *
+ * Typed structurally against `@totemsdk/storage` — this module must NOT import
+ * `@totemsdk/edge`, so it carries no Edge runtime dependency.
+ *
+ * Guarantees:
+ *   - `assertPersistence()` validates surfaces/capabilities at construction.
+ *   - Scope is collision-control only (namespaces); authorization stays above.
+ *   - Retrieval re-verifies digests via `ArtifactStore.get` (`corrupt` vs
+ *     `not-found` are never conflated).
+ *   - Retention/expiry entries survive restart when the injected storage is durable.
+ */
+import type { ArtifactBackendCapabilities, ArtifactRead, ArtifactRef, EffectivePersistence, PersistencePorts, PersistenceRequirement, StorageScope } from '@totemsdk/storage';
+/**
+ * Per-object cache policy. Deliberately does NOT reuse the `retention:
+ * 'fixed'|'managed'|'none'` vocabulary: that is a BACKEND capability, not a
+ * per-object request.
+ */
+export interface ArtifactCacheRetentionPolicy {
+    readonly ttlMs?: number;
+    readonly invalidateOnExpiry?: boolean;
+}
+export interface EdgeArtifactCache {
+    readonly capabilities: ArtifactBackendCapabilities;
+    /** Reported after assertPersistence(); callers must never assume durability. */
+    readonly effective: EffectivePersistence;
+    put(scope: StorageScope, bytes: Uint8Array, policy?: ArtifactCacheRetentionPolicy): Promise<ArtifactRef>;
+    get(scope: StorageScope, ref: ArtifactRef, policy?: ArtifactCacheRetentionPolicy): Promise<ArtifactRead>;
+    invalidate(scope: StorageScope, ref: ArtifactRef): Promise<void>;
+}
+export declare function createEdgeArtifactCache(ports: PersistencePorts, requirement?: PersistenceRequirement, policy?: ArtifactCacheRetentionPolicy): EdgeArtifactCache;

package/dist/cjs/artifact-cache.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * edge-adapters/artifact-cache.ts — RFC-007 Amendment A, phase A1.
+ *
+ * The first consumer of the Edge persistence injection point (`PersistencePorts`).
+ * A scoped, content-addressed artifact cache over the injected `storage` (KV
+ * retention index) and `artifacts` (byte store) surfaces.
+ *
+ * Typed structurally against `@totemsdk/storage` — this module must NOT import
+ * `@totemsdk/edge`, so it carries no Edge runtime dependency.
+ *
+ * Guarantees:
+ *   - `assertPersistence()` validates surfaces/capabilities at construction.
+ *   - Scope is collision-control only (namespaces); authorization stays above.
+ *   - Retrieval re-verifies digests via `ArtifactStore.get` (`corrupt` vs
+ *     `not-found` are never conflated).
+ *   - Retention/expiry entries survive restart when the injected storage is durable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEdgeArtifactCache = createEdgeArtifactCache;
+const storage_1 = require("@totemsdk/storage");
+/** Scope-derived artifact namespace: separate scopes never alias the same blob. */
+function scopeNamespace(scope) {
+    const parts = [scope.principal, scope.adapter, scope.purpose, scope.domain]
+        .filter((p) => typeof p === 'string' && p.length > 0)
+        .map((p) => encodeURIComponent(p));
+    return `edge-cache:${parts.join('/')}`;
+}
+function createEdgeArtifactCache(ports, requirement = { durable: false }, policy = {}) {
+    const label = 'edge-artifact-cache';
+    // The cache always needs both surfaces and a deletable artifact backend.
+    const effective = (0, storage_1.assertPersistence)(ports, { ...requirement, needsArtifacts: true, needsArtifactDelete: true }, label);
+    const storage = ports.storage;
+    const artifacts = ports.artifacts;
+    if (!storage) {
+        throw new storage_1.StorageError(`${label}: a storage index is required for retention/expiry`, 'unavailable');
+    }
+    if (!artifacts) {
+        throw new storage_1.StorageError(`${label}: an artifact store is required`, 'unavailable');
+    }
+    const defaultTtlMs = policy.ttlMs;
+    const defaultInvalidateOnExpiry = policy.invalidateOnExpiry ?? false;
+    const now = () => Date.now();
+    const scoped = (scope) => (0, storage_1.createScopedStorage)(storage, scope);
+    return {
+        capabilities: artifacts.capabilities,
+        effective,
+        async put(scope, bytes, putPolicy) {
+            const ttlMs = putPolicy?.ttlMs ?? defaultTtlMs;
+            const receipt = await artifacts.put(scopeNamespace(scope), bytes, {
+                ...(ttlMs !== undefined ? { retentionMs: ttlMs } : {}),
+            });
+            const entry = {
+                ref: receipt.ref,
+                size: receipt.size,
+                createdAt: now(),
+                ...(ttlMs !== undefined ? { expiresAt: now() + ttlMs } : {}),
+            };
+            await scoped(scope).set((0, storage_1.artifactRefId)(receipt.ref), entry);
+            return receipt.ref;
+        },
+        async get(scope, ref, getPolicy) {
+            const entry = await scoped(scope).get((0, storage_1.artifactRefId)(ref));
+            if (!entry) {
+                // Not known to this scope — never fall through to the raw backend.
+                return { status: 'not-found' };
+            }
+            if (entry.expiresAt !== undefined && now() > entry.expiresAt) {
+                const invalidate = getPolicy?.invalidateOnExpiry ?? defaultInvalidateOnExpiry;
+                if (invalidate)
+                    await this.invalidate(scope, ref);
+                return { status: 'not-found' };
+            }
+            // Digest re-verification + corrupt/not-found taxonomy live in ArtifactStore.
+            return artifacts.get(ref);
+        },
+        async invalidate(scope, ref) {
+            await artifacts.delete(ref);
+            await scoped(scope).remove((0, storage_1.artifactRefId)(ref));
+        },
+    };
+}

package/dist/cjs/identity.d.ts

@@ -0,0 +1,19 @@
+import type { IdentityGraph } from '@totemsdk/identity';
+import type { EdgeIdentityPort } from '@totemsdk/edge';
+export interface IdentityPortConfig {
+    /**
+     * The identity graph this adapter can resolve. Callers holding multiple
+     * identities should create one adapter per graph.
+     */
+    graph: IdentityGraph;
+}
+/**
+ * Wraps an IdentityGraph (from @totemsdk/identity) as an EdgeIdentityPort.
+ *
+ * resolve: returns the resolved identity when identityId matches graph.document.id,
+ *          otherwise returns ok:false. For multi-identity setups, compose multiple
+ *          adapters or use a router above this layer.
+ * verify:  delegates to verifyIdentityClaim() for SignedIdentityClaim values.
+ *          Returns ok:false for unrecognised proof shapes.
+ */
+export declare function createIdentityPortAdapter(config: IdentityPortConfig): EdgeIdentityPort;

package/dist/cjs/identity.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIdentityPortAdapter = createIdentityPortAdapter;
+const identity_1 = require("@totemsdk/identity");
+/**
+ * Wraps an IdentityGraph (from @totemsdk/identity) as an EdgeIdentityPort.
+ *
+ * resolve: returns the resolved identity when identityId matches graph.document.id,
+ *          otherwise returns ok:false. For multi-identity setups, compose multiple
+ *          adapters or use a router above this layer.
+ * verify:  delegates to verifyIdentityClaim() for SignedIdentityClaim values.
+ *          Returns ok:false for unrecognised proof shapes.
+ */
+function createIdentityPortAdapter(config) {
+    const { graph } = config;
+    return {
+        async resolve(identityId) {
+            try {
+                if (graph.document.id !== identityId) {
+                    return {
+                        ok: false,
+                        error: `Identity "${identityId}" not found in this adapter's graph`,
+                        errorCode: 'IDENTITY_NOT_FOUND',
+                    };
+                }
+                const result = (0, identity_1.resolveIdentityGraph)(graph);
+                if (!result.resolved) {
+                    return {
+                        ok: false,
+                        error: result.errors?.join('; ') ?? 'Identity could not be resolved',
+                        errorCode: 'IDENTITY_UNRESOLVABLE',
+                    };
+                }
+                return { ok: true, data: { identity: result.resolved } };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        async verify(proof) {
+            try {
+                const claim = proof;
+                if (!claim?.proof?.address) {
+                    return {
+                        ok: false,
+                        error: 'Proof is not a recognisable SignedIdentityClaim',
+                        errorCode: 'UNSUPPORTED_PROOF_TYPE',
+                    };
+                }
+                const result = (0, identity_1.verifyIdentityClaim)(claim);
+                return {
+                    ok: true,
+                    data: { valid: result.valid, address: result.valid ? claim.proof.address : undefined },
+                };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    };
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,25 @@
+export { createLiquidityPortAdapter } from './liquidity.js';
+export type { LiquidityPortConfig } from './liquidity.js';
+export { createProofPortAdapter } from './proof.js';
+export type { ProofPortConfig } from './proof.js';
+export { createLookupPortAdapter } from './lookup.js';
+export { createPurchaseLookupAdapter, type PurchaseLookupAdapterConfig } from './purchase-lookup.js';
+export { createPurchaseAuthorityAdapter, type PurchaseAuthorityAdapterConfig } from './purchase-authority.js';
+export { createPurchasePaymentAdapter, type PurchasePaymentAdapterConfig, type PurchasePaymentStore, type PurchasePaymentClaimRecord, } from './purchase-payment.js';
+export { createStreamNegotiationTransport, createPubSubNegotiationTransport, type StreamNegotiationTransportConfig, type PubSubNegotiationTransportConfig, } from './negotiation-transport.js';
+export { createLocationPortAdapter } from './location.js';
+export type { LocationPortConfig } from './location.js';
+export { createPolicyPortAdapter } from './policy.js';
+export { createIdentityPortAdapter } from './identity.js';
+export type { IdentityPortConfig } from './identity.js';
+export { createManifestPortAdapter } from './manifest.js';
+export { createMinimaL1PaymentPort } from './payment-l1.js';
+export type { MinimaL1PaymentPortConfig } from './payment-l1.js';
+export { createOmniaL2PaymentPort } from './payment-l2.js';
+export type { OmniaL2PaymentPortConfig } from './payment-l2.js';
+export { createOmniaHostPort } from './omnia.js';
+export type { OmniaHostPortConfig } from './omnia.js';
+export { createStreamPortAdapter } from './stream.js';
+export { createPubSubPortAdapter } from './pubsub.js';
+export { SQLiteCommerceStore, createSQLiteCommerceStore, type CommerceStore, type SQLiteCommerceStoreConfig, } from './sqlite-commerce-store.js';
+export { createEdgeArtifactCache, type EdgeArtifactCache, type ArtifactCacheRetentionPolicy, } from './artifact-cache.js';

package/dist/cjs/index.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEdgeArtifactCache = exports.createSQLiteCommerceStore = exports.SQLiteCommerceStore = exports.createPubSubPortAdapter = exports.createStreamPortAdapter = exports.createOmniaHostPort = exports.createOmniaL2PaymentPort = exports.createMinimaL1PaymentPort = exports.createManifestPortAdapter = exports.createIdentityPortAdapter = exports.createPolicyPortAdapter = exports.createLocationPortAdapter = exports.createPubSubNegotiationTransport = exports.createStreamNegotiationTransport = exports.createPurchasePaymentAdapter = exports.createPurchaseAuthorityAdapter = exports.createPurchaseLookupAdapter = exports.createLookupPortAdapter = exports.createProofPortAdapter = exports.createLiquidityPortAdapter = void 0;
+var liquidity_js_1 = require("./liquidity.js");
+Object.defineProperty(exports, "createLiquidityPortAdapter", { enumerable: true, get: function () { return liquidity_js_1.createLiquidityPortAdapter; } });
+var proof_js_1 = require("./proof.js");
+Object.defineProperty(exports, "createProofPortAdapter", { enumerable: true, get: function () { return proof_js_1.createProofPortAdapter; } });
+var lookup_js_1 = require("./lookup.js");
+Object.defineProperty(exports, "createLookupPortAdapter", { enumerable: true, get: function () { return lookup_js_1.createLookupPortAdapter; } });
+var purchase_lookup_js_1 = require("./purchase-lookup.js");
+Object.defineProperty(exports, "createPurchaseLookupAdapter", { enumerable: true, get: function () { return purchase_lookup_js_1.createPurchaseLookupAdapter; } });
+var purchase_authority_js_1 = require("./purchase-authority.js");
+Object.defineProperty(exports, "createPurchaseAuthorityAdapter", { enumerable: true, get: function () { return purchase_authority_js_1.createPurchaseAuthorityAdapter; } });
+var purchase_payment_js_1 = require("./purchase-payment.js");
+Object.defineProperty(exports, "createPurchasePaymentAdapter", { enumerable: true, get: function () { return purchase_payment_js_1.createPurchasePaymentAdapter; } });
+var negotiation_transport_js_1 = require("./negotiation-transport.js");
+Object.defineProperty(exports, "createStreamNegotiationTransport", { enumerable: true, get: function () { return negotiation_transport_js_1.createStreamNegotiationTransport; } });
+Object.defineProperty(exports, "createPubSubNegotiationTransport", { enumerable: true, get: function () { return negotiation_transport_js_1.createPubSubNegotiationTransport; } });
+var location_js_1 = require("./location.js");
+Object.defineProperty(exports, "createLocationPortAdapter", { enumerable: true, get: function () { return location_js_1.createLocationPortAdapter; } });
+var policy_js_1 = require("./policy.js");
+Object.defineProperty(exports, "createPolicyPortAdapter", { enumerable: true, get: function () { return policy_js_1.createPolicyPortAdapter; } });
+var identity_js_1 = require("./identity.js");
+Object.defineProperty(exports, "createIdentityPortAdapter", { enumerable: true, get: function () { return identity_js_1.createIdentityPortAdapter; } });
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "createManifestPortAdapter", { enumerable: true, get: function () { return manifest_js_1.createManifestPortAdapter; } });
+var payment_l1_js_1 = require("./payment-l1.js");
+Object.defineProperty(exports, "createMinimaL1PaymentPort", { enumerable: true, get: function () { return payment_l1_js_1.createMinimaL1PaymentPort; } });
+var payment_l2_js_1 = require("./payment-l2.js");
+Object.defineProperty(exports, "createOmniaL2PaymentPort", { enumerable: true, get: function () { return payment_l2_js_1.createOmniaL2PaymentPort; } });
+var omnia_js_1 = require("./omnia.js");
+Object.defineProperty(exports, "createOmniaHostPort", { enumerable: true, get: function () { return omnia_js_1.createOmniaHostPort; } });
+var stream_js_1 = require("./stream.js");
+Object.defineProperty(exports, "createStreamPortAdapter", { enumerable: true, get: function () { return stream_js_1.createStreamPortAdapter; } });
+var pubsub_js_1 = require("./pubsub.js");
+Object.defineProperty(exports, "createPubSubPortAdapter", { enumerable: true, get: function () { return pubsub_js_1.createPubSubPortAdapter; } });
+var sqlite_commerce_store_js_1 = require("./sqlite-commerce-store.js");
+Object.defineProperty(exports, "SQLiteCommerceStore", { enumerable: true, get: function () { return sqlite_commerce_store_js_1.SQLiteCommerceStore; } });
+Object.defineProperty(exports, "createSQLiteCommerceStore", { enumerable: true, get: function () { return sqlite_commerce_store_js_1.createSQLiteCommerceStore; } });
+var artifact_cache_js_1 = require("./artifact-cache.js");
+Object.defineProperty(exports, "createEdgeArtifactCache", { enumerable: true, get: function () { return artifact_cache_js_1.createEdgeArtifactCache; } });

package/dist/cjs/liquidity.d.ts

@@ -0,0 +1,15 @@
+import type { ChainStateProvider } from '@totemsdk/chain-provider';
+import type { EdgeLiquidityPort } from '@totemsdk/edge';
+export interface LiquidityPortConfig {
+    provider: ChainStateProvider;
+    /** Token to sum when getBalance is called without an explicit tokenId. Defaults to '0x00' (native Minima). */
+    defaultTokenId?: string;
+}
+/**
+ * Wraps a ChainStateProvider (chain-provider, minima-rpc, lookup-client) as
+ * an EdgeLiquidityPort.
+ *
+ * getBalance sums sendable coins for the given address and tokenId.
+ * getUtxos returns all coins as raw UTXOs (typed as unknown[] per the port contract).
+ */
+export declare function createLiquidityPortAdapter(config: LiquidityPortConfig): EdgeLiquidityPort;

package/dist/cjs/liquidity.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLiquidityPortAdapter = createLiquidityPortAdapter;
+const _SCALE = 100000000n;
+function _toScaled(s) {
+    const [i, f = ''] = s.split('.');
+    return BigInt(i || '0') * _SCALE + BigInt(f.padEnd(8, '0').slice(0, 8));
+}
+function _fromScaled(n) {
+    if (n === 0n)
+        return '0';
+    const frac = (n % _SCALE).toString().padStart(8, '0').replace(/0+$/, '');
+    return frac ? `${n / _SCALE}.${frac}` : `${n / _SCALE}`;
+}
+/**
+ * Wraps a ChainStateProvider (chain-provider, minima-rpc, lookup-client) as
+ * an EdgeLiquidityPort.
+ *
+ * getBalance sums sendable coins for the given address and tokenId.
+ * getUtxos returns all coins as raw UTXOs (typed as unknown[] per the port contract).
+ */
+function createLiquidityPortAdapter(config) {
+    const { provider, defaultTokenId = '0x00' } = config;
+    return {
+        async getBalance(address) {
+            try {
+                const coins = await provider.getCoins({ address, tokenId: defaultTokenId, sendable: true });
+                const balance = _fromScaled(coins.reduce((sum, c) => sum + _toScaled(c.amount), 0n));
+                return { ok: true, data: { balance, tokenId: defaultTokenId } };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        async getUtxos(address) {
+            try {
+                const coins = await provider.getCoins({ address });
+                return { ok: true, data: { utxos: coins } };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    };
+}

package/dist/cjs/location.d.ts

@@ -0,0 +1,48 @@
+import type { EdgeLocationPort } from '@totemsdk/edge';
+export interface LocationPortConfig {
+    /**
+     * Default issuer stamped onto created location proofs. When unset, the
+     * claim's subjectId is used.
+     */
+    issuer?: string;
+    /**
+     * 32-byte WOTS seed. Required for signing; without it only unsigned
+     * location proofs are returned, which MUST NOT be presented as completed
+     * proofs.
+     */
+    seed?: Uint8Array;
+    /**
+     * TreeKey index for direct signing (used when no leaseProvider is given).
+     * Ignored when leaseProvider is set.
+     */
+    keyIndex?: number;
+    /**
+     * WOTS lease provider for coordinated key-index reservation.
+     * When set, keyIndex is ignored and the index is reserved via the provider.
+     */
+    leaseProvider?: {
+        reserveKeyUse(params: {
+            treeId: string;
+            ttlMs?: number;
+            payloadHash?: string;
+        }): Promise<{
+            reservationId: string;
+            indices: {
+                addressIndex: number;
+                l1: number;
+                l2: number;
+            };
+        }>;
+        commitKeyUse(reservationId: string, txId: string): Promise<void>;
+        burnReservation(reservationId: string, reason: string): Promise<void>;
+    };
+    leaseTreeId?: string;
+}
+/**
+ * Wraps @totemsdk/location-proof as an EdgeLocationPort.
+ *
+ * createClaim/createTrail build content-derived Totem-location claims/trails.
+ * createProof returns a SignedProof when config.seed is set; otherwise it
+ * returns an UnsignedProof that MUST NOT be presented as a completed proof.
+ */
+export declare function createLocationPortAdapter(config?: LocationPortConfig): EdgeLocationPort;