@xyo-network/xl1-protocol-sdk 1.26.46 → 1.26.48

package/dist/neutral/index.mjs

@@ -790,6 +790,279 @@ async function validateTransactionsOpcodes(txs) {
   return txElevatedPayloads;
 }
 
+// src/capabilities/Backing.ts
+function backingsSatisfied(required, available) {
+  for (const need of required) {
+    const matched = available.some((a) => a.backing === need.backing && (a.mode === "write" || need.mode === "read"));
+    if (!matched) return false;
+  }
+  return true;
+}
+function unmetBackings(required, available) {
+  return required.filter((need) => {
+    return !available.some((a) => a.backing === need.backing && (a.mode === "write" || need.mode === "read"));
+  });
+}
+
+// src/capabilities/Capability.ts
+var CapabilityRegistry = class {
+  _entries = /* @__PURE__ */ new Map();
+  get(id) {
+    const cap = this._entries.get(id);
+    if (!cap) throw new Error(`Capability not found: ${id}`);
+    return cap;
+  }
+  register(cap) {
+    if (this._entries.has(cap.id)) {
+      throw new Error(`Capability already registered: ${cap.id}`);
+    }
+    this._entries.set(cap.id, cap);
+    return this;
+  }
+  toJson() {
+    const result = {};
+    for (const [id, cap] of this._entries.entries()) {
+      const { id: _, ...rest } = cap;
+      result[id] = rest;
+    }
+    return result;
+  }
+  tryGet(id) {
+    return this._entries.get(id);
+  }
+};
+function createCapabilityRegistry() {
+  return new CapabilityRegistry();
+}
+
+// src/capabilities/surfaceMap.ts
+var BRANCH_SURFACE = {
+  // Connection-level branches.
+  "network": "node",
+  "networkStake": "indexed",
+  "runner": "node",
+  "storage": "indexed",
+  // viewer.* branches.
+  "viewer.block": "node",
+  "viewer.transaction": "node",
+  "viewer.mempool": "node",
+  "viewer.finalization": "node",
+  "viewer.time": "node",
+  // AccountBalanceViewer is a point query (`f(address) → balance`) — node-surface,
+  // even though indexer-backed today via summary maps.
+  "viewer.account.balance": "node",
+  // Cross-key indexes — indexer-surface.
+  "viewer.networkStake": "indexed",
+  "viewer.stake": "indexed",
+  "viewer.step": "indexed"
+};
+function surfaceForBranch(branch) {
+  return BRANCH_SURFACE[branch];
+}
+var VIEWER_BRANCH_KEYS = [
+  ["block", "viewer.block"],
+  ["transaction", "viewer.transaction"],
+  ["mempool", "viewer.mempool"],
+  ["finalization", "viewer.finalization"],
+  ["time", "viewer.time"],
+  ["account", "viewer.account.balance"],
+  ["networkStake", "viewer.networkStake"],
+  ["stake", "viewer.stake"],
+  ["step", "viewer.step"]
+];
+
+// src/capabilities/connectionSubsetBySurface.ts
+function connectionSubsetBySurface(connection, surface) {
+  const result = { moniker: connection.moniker };
+  if (connection.network && surfaceForBranch("network") === surface) result.network = connection.network;
+  if (connection.networkStake && surfaceForBranch("networkStake") === surface) result.networkStake = connection.networkStake;
+  if (connection.runner && surfaceForBranch("runner") === surface) result.runner = connection.runner;
+  if (connection.storage && surfaceForBranch("storage") === surface) result.storage = connection.storage;
+  if (connection.viewer) {
+    const viewer = filterViewerBySurface(connection.viewer, surface);
+    if (viewer) result.viewer = viewer;
+  }
+  return result;
+}
+function filterViewerBySurface(viewer, surface) {
+  const filtered = {};
+  let kept = false;
+  for (const [viewerKey, branchKey] of VIEWER_BRANCH_KEYS) {
+    const value = viewer[viewerKey] ?? void 0;
+    if (value === void 0) continue;
+    if (surfaceForBranch(branchKey) !== surface) continue;
+    filtered[viewerKey] = value;
+    kept = true;
+  }
+  if (!kept) return void 0;
+  return {
+    ...filtered,
+    moniker: viewer.moniker
+  };
+}
+
+// src/capabilities/factoryBrand.ts
+function backedFactory(_backings, factory) {
+  return factory;
+}
+function networkBackedFactory(factory) {
+  return factory;
+}
+function factoryBackingsCompatible(declared, available) {
+  return backingsSatisfied(declared, available);
+}
+
+// src/capabilities/resolveProviders.ts
+var MissingCapabilityError = class extends Error {
+  moniker;
+  reasons;
+  constructor(moniker, reasons) {
+    const detail = reasons.length === 0 ? "(no candidates registered)" : reasons.join("; ");
+    super(`No provider satisfies capability '${moniker}': ${detail}`);
+    this.name = "MissingCapabilityError";
+    this.moniker = moniker;
+    this.reasons = reasons;
+  }
+};
+function resolveProviders(needs, candidates, ctx, options = {}) {
+  const wanted = expandNeeds(needs, ctx);
+  const { backingFiltered, backingRejected } = filterByBackings(candidates, options.availableBackings);
+  const { surviving, rejected: preconditionRejected } = filterByPreconditions(backingFiltered, ctx);
+  const rejected = [...backingRejected, ...preconditionRejected];
+  const byCapability = groupByCapability(surviving, wanted);
+  const { bindings, selectedById } = pickWinners(wanted, byCapability, rejected, candidates);
+  const selected = topoSort([...selectedById.values()], ctx);
+  return {
+    bindings,
+    rejected,
+    selected
+  };
+}
+function filterByBackings(candidates, availableBackings) {
+  if (!availableBackings) {
+    return { backingFiltered: [...candidates], backingRejected: [] };
+  }
+  const backingFiltered = [];
+  const backingRejected = [];
+  for (const descriptor of candidates) {
+    if (backingsSatisfied(descriptor.backings, availableBackings)) {
+      backingFiltered.push(descriptor);
+    } else {
+      const missing = unmetBackings(descriptor.backings, availableBackings);
+      const rendered = missing.map((m) => `${m.backing}:${m.mode}`).join(", ");
+      backingRejected.push({ descriptor, reason: `missing backings [${rendered}]` });
+    }
+  }
+  return { backingFiltered, backingRejected };
+}
+function expandNeeds(needs, ctx) {
+  const wanted = new Set(needs);
+  const stack = [...needs];
+  while (stack.length > 0) {
+    const moniker = stack.pop();
+    const cap = ctx.capabilities.tryGet(moniker);
+    if (!cap?.implies) continue;
+    for (const dep of cap.implies) {
+      if (!wanted.has(dep)) {
+        wanted.add(dep);
+        stack.push(dep);
+      }
+    }
+  }
+  return wanted;
+}
+function filterByPreconditions(candidates, ctx) {
+  const surviving = [];
+  const rejected = [];
+  for (const descriptor of candidates) {
+    try {
+      if (descriptor.preconditions(ctx)) {
+        surviving.push(descriptor);
+      } else {
+        rejected.push({ descriptor, reason: "preconditions returned false" });
+      }
+    } catch (err) {
+      rejected.push({
+        descriptor,
+        reason: `preconditions threw: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  }
+  return { surviving, rejected };
+}
+function groupByCapability(surviving, wanted) {
+  const byCapability = /* @__PURE__ */ new Map();
+  for (const descriptor of surviving) {
+    for (const moniker of descriptor.satisfies) {
+      if (!wanted.has(moniker)) continue;
+      const list = byCapability.get(moniker) ?? [];
+      list.push(descriptor);
+      byCapability.set(moniker, list);
+    }
+  }
+  return byCapability;
+}
+function pickWinners(wanted, byCapability, rejected, allCandidates) {
+  const bindings = {};
+  const selectedById = /* @__PURE__ */ new Map();
+  for (const moniker of wanted) {
+    const group = byCapability.get(moniker);
+    if (!group || group.length === 0) {
+      throw new MissingCapabilityError(moniker, reasonsFor(moniker, rejected, allCandidates));
+    }
+    const sorted = group.toSorted(compareDescriptors);
+    const winner = sorted[0];
+    bindings[moniker] = winner.id;
+    selectedById.set(winner.id, winner);
+    for (const loser of sorted.slice(1)) {
+      rejected.push({
+        descriptor: loser,
+        reason: `tier ${loser.tier} lost to ${winner.id} (tier ${winner.tier}) for ${moniker}`
+      });
+    }
+  }
+  return { bindings, selectedById };
+}
+function reasonsFor(moniker, rejected, allCandidates) {
+  const candidatesForMoniker = allCandidates.filter((c) => c.satisfies.includes(moniker));
+  if (candidatesForMoniker.length === 0) return [];
+  return rejected.filter((r) => r.descriptor.satisfies.includes(moniker)).map((r) => `${r.descriptor.id}: ${r.reason}`);
+}
+function compareDescriptors(a, b) {
+  if (a.tier !== b.tier) return a.tier - b.tier;
+  const pa = a.priority ?? 0;
+  const pb = b.priority ?? 0;
+  if (pa !== pb) return pb - pa;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function topoSort(descriptors, ctx) {
+  const byMoniker = /* @__PURE__ */ new Map();
+  for (const d of descriptors) for (const m of d.satisfies) byMoniker.set(m, d);
+  const order = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const visit = (d) => {
+    if (seen.has(d.id)) return;
+    if (visiting.has(d.id)) {
+      throw new Error(`Cycle detected through provider ${d.id}`);
+    }
+    visiting.add(d.id);
+    for (const moniker of d.satisfies) {
+      const cap = ctx.capabilities.tryGet(moniker);
+      if (!cap?.implies) continue;
+      for (const dep of cap.implies) {
+        const depDesc = byMoniker.get(dep);
+        if (depDesc) visit(depDesc);
+      }
+    }
+    visiting.delete(d.id);
+    seen.add(d.id);
+    order.push(d);
+  };
+  for (const d of descriptors) visit(d);
+  return order;
+}
+
 // src/config/Actor.ts
 import {
   zodAsFactory as zodAsFactory3,
@@ -6381,6 +6654,7 @@ export {
   LruCacheMap,
   MemoryMap,
   MemoryPermissionsStore,
+  MissingCapabilityError,
   MnemonicStringZod,
   PRODUCER_DIVERSITY_BONUS,
   PostMessageRpcRemoteConfigZod,
@@ -6435,6 +6709,7 @@ export {
   TypedDataTypesZod,
   TypedDataValueZod,
   UsageMetaSchema,
+  VIEWER_BRANCH_KEYS,
   WALLET_COMPLIANCE,
   XL1Amount,
   XL1_NETWORK_STAKING_GENESIS_PERIOD_END_EPOCH,
@@ -6470,6 +6745,8 @@ export {
   asSchemasStepSummaryWithStorageMeta,
   asTransfersStepSummary,
   asTransfersStepSummaryWithStorageMeta,
+  backedFactory,
+  backingsSatisfied,
   balancesStepSummaryFromRange,
   balancesSummary,
   blockFromBlockNumber,
@@ -6486,12 +6763,14 @@ export {
   calculateTimeRate,
   chainStepRewardAddress,
   confirmSubmittedTransaction,
+  connectionSubsetBySurface,
   contextCache,
   crackOperation,
   crackOperations,
   creatableProvider,
   createBlockHydrator,
   createBoundWitnessHydrator,
+  createCapabilityRegistry,
   createDeclarationIntent,
   createTransactionHydrator,
   createTransferPayload,
@@ -6499,6 +6778,7 @@ export {
   externalBlockNumberFromXL1BlockNumber,
   externalBlockRangeFromStep,
   externalBlockRangeFromXL1BlockRange,
+  factoryBackingsCompatible,
   findBestUncle,
   findMostRecentBlock,
   findUncles,
@@ -6557,6 +6837,7 @@ export {
   netBalancesForPayloads,
   netSchemasForPayloads,
   netTransfersForPayloads,
+  networkBackedFactory,
   networkStakeStepRewardPositionWeight,
   parseSignedBigInt,
   payloadMapFromStore,
@@ -6567,6 +6848,7 @@ export {
   registerCreatableProviderFactories,
   registerCreatableProviderFactory,
   resolveConfig,
+  resolveProviders,
   rewardFromBlockNumber,
   schemasStepSummaryFromRange,
   schemasSummary,
@@ -6583,6 +6865,7 @@ export {
   stepsRewardTotal,
   stepsRewardTotalGenesisPeriod,
   stepsRewardTotalRange,
+  surfaceForBranch,
   timeDurations,
   toActorConfig,
   toActorConfigContext,
@@ -6610,6 +6893,7 @@ export {
   tryUnflattenHydratedTransaction,
   unflattenHydratedBlock,
   unflattenHydratedTransaction,
+  unmetBackings,
   validateTransactionsOpcodes,
   verifyEIP712Message,
   weightedStakeForRangeByPosition,