@unicitylabs/sphere-sdk 0.17.6 → 0.18.0-dev.2

package/dist/core/index.js

@@ -10287,6 +10287,19 @@ async function readTokenNft(token) {
   }
 }
 
+// token-engine/plugin-ops.ts
+function contextWithMintVerifiers(base, verifiers) {
+  const registry = new MintJustificationVerifierService();
+  for (const verifier of verifiers) registry.register(verifier);
+  return new VerificationContext(
+    base.trustBase,
+    base.predicateVerifier,
+    base.unicityCertificateVerifier,
+    registry,
+    new TokenIssuanceVerifierService(false)
+  );
+}
+
 // token-engine/split-checkpoint.ts
 var CHECKPOINT_VERSION = 2;
 var CHECKPOINT_SDK_VERSION = "@unicitylabs/state-transition-sdk@3.0.1";
@@ -10433,6 +10446,10 @@ var SphereTokenEngine = class {
     const data = token.sdkToken.genesis.data;
     return data ? new Uint8Array(data) : null;
   }
+  readTokenJustification(token) {
+    const justification = token.sdkToken.genesis.justification;
+    return justification ? new Uint8Array(justification) : null;
+  }
   readNft(token) {
     return readTokenNft(token);
   }
@@ -10464,7 +10481,7 @@ var SphereTokenEngine = class {
     const recipient = SignaturePredicate.create(params.recipientPubkey);
     const tokenType = params.tokenType ? new TokenType(params.tokenType) : TokenType.generate();
     const salt = params.salt ? TokenSalt.fromBytes(params.salt) : TokenSalt.generate();
-    const mintTx = await MintTransaction.create(this.deps.networkId, recipient, { data: params.data, tokenType, salt });
+    const mintTx = await MintTransaction.create(this.deps.networkId, recipient, { data: params.data, tokenType, salt, justification: params.justification ?? null });
     const certificationData = await CertificationData.fromMintTransaction(mintTx);
     const proof = await this.submitAndAwaitProof(
       certificationData,
@@ -10474,34 +10491,30 @@ var SphereTokenEngine = class {
       options
     );
     const certified = await mintTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
-    const token = await Token.mint(certified, this.deps.verificationContext);
-    return wrapToken(token);
+    const verifiers = params.mintJustificationVerifiers;
+    return wrapToken(await Token.mint(certified, verifiers ? contextWithMintVerifiers(this.deps, verifiers) : this.deps.verificationContext));
   }
   buildNftMint(params) {
     return planNftMint(this.deps, params);
   }
   async transfer(params, options) {
     this.assertOwned(params.token);
-    const transferId = this.resolveTransferId(options);
-    const recipient = SignaturePredicate.create(params.recipientPubkey);
+    return this.spend(params.token, SignaturePredicate.create(params.recipientPubkey), params.data ?? null, options, "Transfer certification failed");
+  }
+  async burn(params, options) {
+    this.assertOwned(params.token);
+    return this.spend(params.token, BurnPredicate.create(sha256(params.reasonBytes)), params.reasonBytes, options, "Burn certification failed");
+  }
+  async spend(token, recipient, data, options, failLabel) {
     const stateMask = StateMask.fromBytes(
-      deriveRealization(this.privateKeyHex, transferId, this.resolveOpIndex(options), "stateMask")
+      deriveRealization(this.privateKeyHex, this.resolveTransferId(options), this.resolveOpIndex(options), "stateMask")
     );
-    const transferTx = await TransferTransaction.create(params.token.sdkToken, recipient, stateMask, {
-      data: params.data ?? null
-    });
+    const transferTx = await TransferTransaction.create(token.sdkToken, recipient, stateMask, { data });
     const unlockScript = await SignaturePredicateUnlockScript.create(transferTx, this.deps.signingService);
     const certificationData = await CertificationData.fromTransaction(transferTx, unlockScript);
-    const proof = await this.submitAndAwaitProof(
-      certificationData,
-      transferTx,
-      "Transfer certification failed",
-      "TRANSFER_FAILED",
-      options
-    );
+    const proof = await this.submitAndAwaitProof(certificationData, transferTx, failLabel, "TRANSFER_FAILED", options);
     const certified = await transferTx.toCertifiedTransaction(this.deps.trustBase, this.deps.predicateVerifier, this.deps.unicityCertificateVerifier, proof);
-    const transferred = await params.token.sdkToken.transfer(certified, this.deps.verificationContext);
-    return wrapToken(transferred);
+    return wrapToken(await token.sdkToken.transfer(certified, this.deps.verificationContext));
   }
   async split(params, options) {
     this.assertOwned(params.token);
@@ -10816,6 +10829,20 @@ var SphereTokenEngine = class {
 
 // token-engine/factory.ts
 var DEFAULT_VERIFICATION_POOL_SIZE = 4;
+function registerPluginVerifiers(registry, plugins) {
+  for (const plugin of plugins ?? []) {
+    for (const verifier of plugin.mintJustificationVerifiers ?? []) {
+      try {
+        registry.register(verifier);
+      } catch (err) {
+        throw new SphereError(
+          `Token plugin '${plugin.id}' registers mint-reason tag ${verifier.tag} twice or over another plugin's: ` + (err instanceof Error ? err.message : String(err)),
+          "INVALID_CONFIG"
+        );
+      }
+    }
+  }
+}
 function disposedError() {
   return new SphereError(
     "Verification worker pool disposed \u2014 the in-flight verification was cancelled",
@@ -10897,6 +10924,7 @@ async function createSphereTokenEngine(config) {
   mintJustificationVerifier.register(
     new SplitMintJustificationVerifier(decodeSpherePaymentData)
   );
+  registerPluginVerifiers(mintJustificationVerifier, config.plugins);
   const deps = {
     client: new StateTransitionClient(new AggregatorClient(config.aggregatorUrl, config.apiKey ?? null)),
     trustBase,
@@ -12014,6 +12042,8 @@ var STORE_KEYS = {
   deliveryJournal: "delivery-journal",
   mintJournal: "mint-journal",
   nftMintJournal: "nft-mint-journal",
+  customMintJournal: "custom-mint-journal",
+  burnJournal: "burn-journal",
   shortfalls: "shortfalls",
   settlingLinks: "settling",
   streamCursor: (s) => `cursor:${s}`,
@@ -12198,6 +12228,8 @@ function createMachineStores(kv) {
     deliveryJournal: new DeliveryJournal(kv),
     mintJournal: new ListStore(kv, STORE_KEYS.mintJournal, (e) => e.mintId),
     nftMintJournal: new ListStore(kv, STORE_KEYS.nftMintJournal, (e) => e.mintId),
+    customMintJournal: new ListStore(kv, STORE_KEYS.customMintJournal, (e) => e.mintId),
+    burnJournal: new ListStore(kv, STORE_KEYS.burnJournal, (e) => e.burnId),
     shortfalls: new ListStore(kv, STORE_KEYS.shortfalls, (e) => e.transferId)
   };
 }
@@ -12905,7 +12937,12 @@ var Converger = class {
     } catch (err) {
       retryAfterMs ??= retryAfterMsOf(err);
     }
-    for (const replay of [() => this.deps.replayMints(), () => this.deps.replayNftMints()]) {
+    for (const replay of [
+      () => this.deps.replayMints(),
+      () => this.deps.replayNftMints(),
+      () => this.deps.replayCustomMints(),
+      () => this.deps.replayBurns()
+    ]) {
       try {
         progress = await replay() > 0 || progress;
       } catch (err) {
@@ -12916,14 +12953,17 @@ var Converger = class {
   }
   /** §4 heartbeat predicate — read fresh from the §6 stores, never cached. */
   async pendingWork() {
-    const [backstop, journal, mints, nftMints] = await Promise.all([
+    const [backstop, journal, mints, nftMints, customMints, burns] = await Promise.all([
       this.deps.stores.backstop.list(),
       this.deps.stores.deliveryJournal.list(),
       this.deps.stores.mintJournal.list(),
-      this.deps.stores.nftMintJournal.list()
+      this.deps.stores.nftMintJournal.list(),
+      this.deps.stores.customMintJournal.list(),
+      this.deps.stores.burnJournal.list()
     ]);
-    const mintsOpen = mints.length > 0 || nftMints.length > 0;
-    return backstop.length > 0 || journal.some((e) => e.undeliverable !== true) || mintsOpen;
+    const mintsOpen = mints.length > 0 || nftMints.length > 0 || customMints.length > 0;
+    const burnsOpen = burns.some((e) => !e.settled);
+    return backstop.length > 0 || journal.some((e) => e.undeliverable !== true) || mintsOpen || burnsOpen;
   }
   async resumePass() {
     const report = await resumeAll(this.filteredMachineDeps(), {
@@ -13155,6 +13195,12 @@ async function decodeView(deps, tokenId, bytes) {
 
 // modules/payments-v2/inventory/token-data.ts
 async function readTokenData(deps, tokenId) {
+  return deps.engine.readTokenData(await heldToken(deps, tokenId));
+}
+async function readTokenJustification(deps, tokenId) {
+  return deps.engine.readTokenJustification(await heldToken(deps, tokenId));
+}
+async function heldToken(deps, tokenId) {
   if (deps.view.stateHashOf(tokenId) === void 0) {
     throw new SphereError(`Token ${tokenId} is not in inventory`, "VALIDATION_ERROR");
   }
@@ -13162,7 +13208,7 @@ async function readTokenData(deps, tokenId) {
   if (bytes === void 0) {
     throw new SphereError(`Token ${tokenId} has no blob in storage`, "STORAGE_ERROR");
   }
-  return deps.engine.readTokenData(await deps.engine.decodeToken({ tokenId, token: bytes }));
+  return deps.engine.decodeToken({ tokenId, token: bytes });
 }
 
 // modules/payments-v2/history/History.ts
@@ -14998,6 +15044,7 @@ function mintParams(recipientPubkey, coinId, amount) {
 
 // modules/payments-v2/mint.ts
 var ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
+var INVENTORY_SCAN_PAGE_LIMIT = 50;
 function runMintUnderJournal(deps, input) {
   return mintUnderJournal(deps, input);
 }
@@ -15050,6 +15097,15 @@ async function finalizeMint(deps, input) {
   deps.noteHeldState(token.blob.tokenId, (await deps.engine.deliveryKeys(bytes)).stateHash);
   deps.refreshView();
 }
+async function tokenInServerInventory(storagePort, tokenId) {
+  let page = await storagePort.listInventory();
+  for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
+    if (page.items.some((item) => item.tokenId === tokenId && item.status === "active")) return true;
+    if (!page.more) return false;
+    page = await storagePort.listInventory(page.cursor);
+  }
+  return false;
+}
 async function replayCoinMints(deps) {
   let resolved = 0;
   for (const entry of await deps.mintJournal.list()) {
@@ -15153,6 +15209,199 @@ async function mintJournaled(deps, entry) {
   await finalizeMint(deps, { mintId: entry.mintId, token, assets: [], journal: deps.nftMintJournal });
 }
 
+// modules/payments-v2/mint-custom.ts
+var HEX32 = /^[0-9a-f]{64}$/;
+function assertRequest(request) {
+  if (request.tokenType.length !== 32) {
+    throw new SphereError("mintCustom: tokenType must be 32 bytes", "VALIDATION_ERROR");
+  }
+  if (request.salt.length < 16 || request.salt.length > 64) {
+    throw new SphereError("mintCustom: salt must be 16 to 64 bytes", "VALIDATION_ERROR");
+  }
+  if (request.data.length === 0) {
+    throw new SphereError("mintCustom: data must not be empty", "VALIDATION_ERROR");
+  }
+  for (const asset of request.assets) {
+    if (!HEX32.test(asset.coinId) || asset.amount <= 0n) {
+      throw new SphereError("mintCustom: assets need a 64-hex coinId and a positive amount", "VALIDATION_ERROR");
+    }
+  }
+}
+async function runCustomMintUnderJournal(deps, input) {
+  try {
+    assertRequest(input.request);
+  } catch (err) {
+    return { success: false, error: messageOf(err) };
+  }
+  const entry = journalEntryOf2(input.mintId, input.request, deps.now());
+  await deps.customMintJournal.upsert(entry);
+  let tokenId;
+  try {
+    tokenId = await mintJournaled2(deps, entry, input.request.mintJustificationVerifiers);
+  } catch (err) {
+    deps.armHeartbeat();
+    return { success: false, error: messageOf(err) };
+  }
+  return { success: true, tokenId };
+}
+async function replayCustomMints(deps) {
+  let resolved = 0;
+  for (const entry of await deps.customMintJournal.list()) {
+    if (deps.isActiveOp(entry.mintId)) continue;
+    try {
+      if (entry.tokenId !== "" && await deps.tokenInServerInventory(entry.tokenId)) {
+        await deps.customMintJournal.removeByKey(entry.mintId);
+      } else {
+        await mintJournaled2(deps, entry, void 0);
+      }
+      resolved += 1;
+    } catch {
+      continue;
+    }
+  }
+  return resolved;
+}
+function journalEntryOf2(mintId, request, createdAt) {
+  return {
+    mintId,
+    tokenId: "",
+    dataHex: bytesToHex3(request.data),
+    saltHex: bytesToHex3(request.salt),
+    tokenTypeHex: bytesToHex3(request.tokenType),
+    justificationHex: request.justification ? bytesToHex3(request.justification) : null,
+    assets: request.assets.map((a) => ({ coinId: a.coinId, amount: a.amount.toString() })),
+    createdAt
+  };
+}
+async function mintJournaled2(deps, entry, mintJustificationVerifiers) {
+  const token = await deps.engine.mintDataToken(
+    {
+      recipientPubkey: deps.ownPubkeyBytes,
+      data: hexToBytes4(entry.dataHex),
+      tokenType: hexToBytes4(entry.tokenTypeHex),
+      salt: hexToBytes4(entry.saltHex),
+      ...entry.justificationHex !== null ? { justification: hexToBytes4(entry.justificationHex) } : {},
+      ...mintJustificationVerifiers ? { mintJustificationVerifiers } : {}
+    },
+    { transferId: entry.mintId }
+  );
+  if (entry.tokenId !== "" && token.blob.tokenId !== entry.tokenId) {
+    throw new SphereError(`minted token ${token.blob.tokenId}, but the journal names ${entry.tokenId}`, "VALIDATION_ERROR");
+  }
+  if (entry.tokenId === "") {
+    await deps.customMintJournal.upsert({ ...entry, tokenId: token.blob.tokenId });
+  }
+  await finalizeMint(deps, {
+    mintId: entry.mintId,
+    token,
+    assets: entry.assets,
+    journal: deps.customMintJournal
+  });
+  return token.blob.tokenId;
+}
+
+// modules/payments-v2/burn.ts
+var HEX322 = /^[0-9a-f]{64}$/;
+async function heldToken2(deps, tokenId) {
+  const bytes = (await deps.storagePort.getBlobs([tokenId])).get(tokenId);
+  if (bytes === void 0) {
+    throw new SphereError(`Token ${tokenId} has no blob in storage; it is not held here`, "STORAGE_ERROR");
+  }
+  return deps.engine.decodeToken({ tokenId, token: bytes });
+}
+function assetsOf(token) {
+  return (token.value?.assets ?? []).map((a) => ({ coinId: a.coinId, amount: a.amount.toString() }));
+}
+async function runBurnUnderJournal(deps, input) {
+  const { burnId } = input;
+  const { tokenId, reasonBytes } = input.request;
+  if (!HEX322.test(tokenId) || reasonBytes.length === 0) {
+    return { success: false, burnId, tokenId, error: "burn: tokenId must be 64 hex and reasonBytes non-empty" };
+  }
+  let token;
+  try {
+    token = await heldToken2(deps, tokenId);
+    if (!deps.engine.isOwnedBy(token, deps.engine.getIdentity().chainPubkey)) {
+      throw new SphereError(`Token ${tokenId} is not owned by this wallet`, "VALIDATION_ERROR");
+    }
+  } catch (err) {
+    return { success: false, burnId, tokenId, error: messageOf(err) };
+  }
+  const entry = {
+    burnId,
+    tokenId,
+    reasonHex: bytesToHex3(reasonBytes),
+    burnedTokenHex: null,
+    settled: false,
+    assets: assetsOf(token),
+    createdAt: deps.now()
+  };
+  await deps.burnJournal.upsert(entry);
+  try {
+    const settled = await burnJournaled(deps, entry, token, { applied: false });
+    return { success: true, burnId, tokenId, burnedToken: hexToBytes4(settled.burnedTokenHex ?? "") };
+  } catch (err) {
+    deps.armHeartbeat();
+    return { success: false, burnId, tokenId, error: messageOf(err) };
+  }
+}
+async function replayBurns(deps) {
+  let progressed = 0;
+  for (const entry of await deps.burnJournal.list()) {
+    if (entry.settled || deps.isActiveOp(entry.burnId)) continue;
+    try {
+      const token = entry.burnedTokenHex === null ? await heldToken2(deps, entry.tokenId) : null;
+      const applied = entry.burnedTokenHex !== null && !await deps.tokenInServerInventory(entry.tokenId);
+      await burnJournaled(deps, entry, token, { applied });
+      progressed += 1;
+    } catch {
+      continue;
+    }
+  }
+  return progressed;
+}
+async function pendingBurns(deps) {
+  return (await deps.burnJournal.list()).map((entry) => ({
+    burnId: entry.burnId,
+    tokenId: entry.tokenId,
+    reasonBytes: hexToBytes4(entry.reasonHex),
+    burnedToken: entry.burnedTokenHex === null ? null : hexToBytes4(entry.burnedTokenHex),
+    settled: entry.settled,
+    createdAt: entry.createdAt
+  }));
+}
+async function acknowledgeBurn(deps, burnId) {
+  const entry = await deps.burnJournal.getByKey(burnId);
+  if (entry === void 0) return;
+  if (!entry.settled) {
+    throw new SphereError(`Burn ${burnId} is not settled yet; it cannot be acknowledged`, "VALIDATION_ERROR");
+  }
+  await deps.burnJournal.removeByKey(burnId);
+}
+async function burnJournaled(deps, entry, token, state) {
+  let current = entry;
+  if (current.burnedTokenHex === null) {
+    if (token === null) throw new SphereError("burn replay needs the held token to certify", "VALIDATION_ERROR");
+    const burned = await deps.engine.burn(
+      { token, reasonBytes: hexToBytes4(current.reasonHex) },
+      { transferId: current.burnId }
+    );
+    if (burned.blob.tokenId !== current.tokenId) {
+      throw new SphereError(`burned token ${burned.blob.tokenId}, but the journal names ${current.tokenId}`, "VALIDATION_ERROR");
+    }
+    current = { ...current, burnedTokenHex: bytesToHex3(burned.blob.token) };
+    await deps.burnJournal.upsert(current);
+  }
+  if (!state.applied) {
+    await deps.storagePort.applyDelta({ transferId: current.burnId, spent: [current.tokenId], added: [] });
+  }
+  await deps.recordSent({ transferId: current.burnId, assets: current.assets, tokenId: current.tokenId });
+  current = { ...current, settled: true };
+  await deps.burnJournal.upsert(current);
+  deps.refreshView();
+  return current;
+}
+
 // modules/payments-v2/send-whole.ts
 async function materializeWholeSpend(deps, input) {
   const { engine } = deps;
@@ -15338,7 +15587,6 @@ async function takeSourceBlobs(deps, sourceIds) {
 
 // modules/payments-v2/PaymentsFacade.ts
 var MAX_RESELECT = 8;
-var INVENTORY_SCAN_PAGE_LIMIT = 50;
 var PaymentsFacade = class {
   constructor(deps) {
     this.deps = deps;
@@ -15375,6 +15623,8 @@ var PaymentsFacade = class {
       refreshView: () => this.view.delta(),
       replayMints: () => replayCoinMints(this.mintDeps()),
       replayNftMints: () => replayNftMints(this.mintDeps()),
+      replayCustomMints: () => replayCustomMints(this.mintDeps()),
+      replayBurns: () => replayBurns(this.mintDeps()),
       isActiveOp: (id) => this.activeMoneyOps.has(id),
       emit: deps.emit,
       now: () => this.nowMs()
@@ -15470,6 +15720,9 @@ var PaymentsFacade = class {
   tokenData(tokenId) {
     return readTokenData(this.readDeps(), tokenId);
   }
+  tokenJustification(tokenId) {
+    return readTokenJustification(this.readDeps(), tokenId);
+  }
   nft(tokenId) {
     return readNft(this.readDeps(), tokenId);
   }
@@ -15518,8 +15771,12 @@ var PaymentsFacade = class {
     return this.track(this.mintInner(coinId, amount));
   }
   mintNft(request) {
-    return this.track(this.ownedMint((mintId) => runNftMintUnderJournal(this.mintDeps(), { mintId, request })));
+    return this.track(this.ownedOp((mintId) => runNftMintUnderJournal(this.mintDeps(), { mintId, request })));
   }
+  mintCustom = (request) => this.track(this.ownedOp((mintId) => runCustomMintUnderJournal(this.mintDeps(), { mintId, request })));
+  burn = (request) => this.track(this.ownedOp((burnId) => runBurnUnderJournal(this.mintDeps(), { burnId, request })));
+  pendingBurns = () => this.track(pendingBurns(this.mintDeps()));
+  acknowledgeBurn = (burnId) => this.track(acknowledgeBurn(this.mintDeps(), burnId));
   // §4 retry verb: coalesces onto the running pass — NEVER re-issue send() (#631/#676).
   async resumeNow() {
     if (!this.started) return;
@@ -15543,12 +15800,15 @@ var PaymentsFacade = class {
   nowMs() {
     return (this.deps.now ?? Date.now)();
   }
-  /** One snapshot serves the coin and the NFT mint, live and replayed. */
+  /** One snapshot serves the coin, NFT and custom mints and the burn, live and replayed. */
   mintDeps() {
     return {
       engine: this.engine(),
       mintJournal: this.machineStores.mintJournal,
       nftMintJournal: this.machineStores.nftMintJournal,
+      customMintJournal: this.machineStores.customMintJournal,
+      burnJournal: this.machineStores.burnJournal,
+      recordSent: (input) => this.historyStore.recordSent(input),
       storagePort: this.deps.storagePort,
       recordMint: (input) => this.historyStore.recordMint(input),
       armHeartbeat: () => this.heartbeat.arm(),
@@ -15557,7 +15817,7 @@ var PaymentsFacade = class {
       ownPubkeyBytes: this.ownPubkeyBytes,
       nftTokenType: this.deps.nftTokenType,
       isActiveOp: (mintId) => this.activeMoneyOps.has(mintId),
-      tokenInServerInventory: (tokenId) => this.tokenInServerInventory(tokenId),
+      tokenInServerInventory: (tokenId) => tokenInServerInventory(this.deps.storagePort, tokenId),
       emit: this.deps.emit,
       now: () => this.nowMs()
     };
@@ -15878,28 +16138,17 @@ var PaymentsFacade = class {
     if (!/^(?:[0-9a-f]{2})+$/.test(coinId) || amount <= 0n) {
       return { success: false, error: "coinId must be even-length lowercase hex and amount positive" };
     }
-    return this.ownedMint((mintId) => runMintUnderJournal(this.mintDeps(), { mintId, coinId, amount }));
+    return this.ownedOp((mintId) => runMintUnderJournal(this.mintDeps(), { mintId, coinId, amount }));
   }
-  /** A live mint under a fresh id — its replay stays hands-off while this attempt runs. */
-  async ownedMint(run) {
-    const mintId = this.newId();
-    this.activeMoneyOps.add(mintId);
+  /** A live money op under a fresh id — its replay stays hands-off while this attempt runs (§7). */
+  async ownedOp(run) {
+    const id = this.newId();
+    this.activeMoneyOps.add(id);
     try {
-      return await run(mintId);
+      return await run(id);
     } finally {
-      this.activeMoneyOps.delete(mintId);
-    }
-  }
-  async tokenInServerInventory(tokenId) {
-    let page = await this.deps.storagePort.listInventory();
-    for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
-      if (page.items.some((item) => item.tokenId === tokenId && item.status === "active")) {
-        return true;
-      }
-      if (!page.more) return false;
-      page = await this.deps.storagePort.listInventory(page.cursor);
+      this.activeMoneyOps.delete(id);
     }
-    return false;
   }
   // ── wiring internals ───────────────────────────────────────────────────────
   engine() {
@@ -17291,6 +17540,8 @@ var Sphere = class _Sphere {
    * the rebuild after an api-key change share one pool configuration.
    */
   _verification;
+  /** Token plugins (SphereInitOptions.plugins), applied to every engine like _verification. */
+  _plugins;
   /** This Sphere's OWN token registry. Disposed by destroy(); never the process global. */
   _registry = null;
   // Events
@@ -17404,6 +17655,7 @@ var Sphere = class _Sphere {
         communications: options.communications,
         password: options.password,
         verification: options.verification,
+        plugins: options.plugins,
         discoverAddresses: options.discoverAddresses,
         onProgress: options.onProgress
       });
@@ -17441,6 +17693,7 @@ var Sphere = class _Sphere {
       communications: options.communications,
       password: options.password,
       verification: options.verification,
+      plugins: options.plugins,
       discoverAddresses: options.discoverAddresses,
       onProgress: options.onProgress
     });
@@ -17619,6 +17872,7 @@ var Sphere = class _Sphere {
       options.communications
     );
     sphere._verification = options.verification;
+    sphere._plugins = options.plugins;
     sphere._paymentsV2Composition = composition;
     sphere._password = options.password ?? null;
     sphere._passwordProtected = sphere._password !== null;
@@ -17683,6 +17937,7 @@ var Sphere = class _Sphere {
       options.communications
     );
     sphere._verification = options.verification;
+    sphere._plugins = options.plugins;
     sphere._paymentsV2Composition = composition;
     sphere._password = options.password ?? null;
     sphere._passwordProtected = sphere._password !== null;
@@ -17769,6 +18024,7 @@ var Sphere = class _Sphere {
       options.communications
     );
     sphere._verification = options.verification;
+    sphere._plugins = options.plugins;
     sphere._paymentsV2Composition = composition;
     sphere._password = options.password ?? null;
     sphere._passwordProtected = sphere._password !== null;
@@ -20079,7 +20335,8 @@ var Sphere = class _Sphere {
         apiKey: oracle.getApiKey?.(),
         privateKey: hexToBytes4(privateKey),
         trustBaseJson,
-        ...this._verification ? { verification: this._verification } : {}
+        ...this._verification ? { verification: this._verification } : {},
+        ...this._plugins ? { plugins: this._plugins } : {}
       });
     } catch (err) {
       logger.warn(