@xo-cash/engine 0.0.1-development.14141361677 → 0.0.1-development.14146115040

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { bigIntToVmNumber, binToHex, binToUtf8, createCompilerBch, encodeTransaction, generateRandomBytes, generateTransaction, hash256, hashTransaction, hexToBin, sha256, stringify, utf8ToBin, vmNumberToBigInt } from "@bitauth/libauth";
1
+ import { bigIntToVmNumber, binToHex, binToUtf8, createCompilerBch, encodeTransaction, generateRandomBytes, generateTransaction, hashTransaction, hexToBin, sha256, utf8ToBin, vmNumberToBigInt } from "@bitauth/libauth";
2
2
  import { Crypto, buildInvitationCommitSigningPayload, convertMnemonicToSeedBytes, verifySchnorrSignature } from "@xo-cash/crypto";
3
3
  import { State, StorageType, UnspentOutputStatus, createStorageAdapter } from "@xo-cash/state";
4
4
  import { generateTemplateIdentifier, generateTemplateIdentifier as generateTemplateIdentifier$1, parseTemplate, parseTemplate as parseTemplate$1, scriptToScriptHash } from "@xo-cash/utils";
@@ -11,19 +11,17 @@ import { PublicKey } from "@xo-cash/primitives";
11
11
  /**
12
12
  * Error thrown when an action is not found in the template.
13
13
  */
14
- var ActionNotFoundError = class extends Error {
14
+ var TemplateActionNotFoundError = class extends Error {
15
15
  constructor(actionIdentifier) {
16
- const defaultMessage = "Action not found in template";
17
- super(actionIdentifier ? `${defaultMessage}: actionIdentifier "${actionIdentifier}"` : defaultMessage);
16
+ super(`Template action not found, actionIdentifier "${actionIdentifier}"`);
18
17
  }
19
18
  };
20
19
  /**
21
20
  * Error thrown when an output is not found in the template.
22
21
  */
23
- var OutputNotFoundError = class extends Error {
22
+ var TemplateOutputNotFoundError = class extends Error {
24
23
  constructor(outputIdentifier) {
25
- const defaultMessage = "Output not found in template";
26
- super(outputIdentifier ? `${defaultMessage}: outputIdentifier "${outputIdentifier}"` : defaultMessage);
24
+ super(`Template output not found, outputIdentifier "${outputIdentifier}"`);
27
25
  }
28
26
  };
29
27
  /**
@@ -31,26 +29,23 @@ var OutputNotFoundError = class extends Error {
31
29
  */
32
30
  var TemplateNotFoundError = class extends Error {
33
31
  constructor(templateIdentifier) {
34
- const defaultMessage = "Template not found";
35
- super(templateIdentifier ? `${defaultMessage}: templateIdentifier "${templateIdentifier}"` : defaultMessage);
32
+ super(`Template not found, templateIdentifier "${templateIdentifier}"`);
36
33
  }
37
34
  };
38
35
  /**
39
36
  * Error thrown when a locking script is not found in the template.
40
37
  */
41
- var LockingScriptNotFoundError = class extends Error {
38
+ var TemplateLockingScriptNotFoundError = class extends Error {
42
39
  constructor(lockingScriptIdentifier) {
43
- const defaultMessage = "Locking script not found in template";
44
- super(lockingScriptIdentifier ? `${defaultMessage}: lockingScriptIdentifier "${lockingScriptIdentifier}"` : defaultMessage);
40
+ super(`Template locking script not found, lockingScriptIdentifier "${lockingScriptIdentifier}"`);
45
41
  }
46
42
  };
47
43
  /**
48
44
  * Error thrown when a locking script type is not found in the template.
49
45
  */
50
- var LockingScriptTypeNotFoundError = class extends Error {
46
+ var TemplateLockingScriptTypeNotFoundError = class extends Error {
51
47
  constructor(lockingScriptIdentifier) {
52
- const defaultMessage = "Locking script type not found in template";
53
- super(lockingScriptIdentifier ? `${defaultMessage}: lockingScriptIdentifier "${lockingScriptIdentifier}"` : defaultMessage);
48
+ super(`Template locking script type not found, lockingScriptIdentifier "${lockingScriptIdentifier}"`);
54
49
  }
55
50
  };
56
51
  /**
@@ -83,10 +78,9 @@ var StartingActionNotFoundError = class extends Error {
83
78
  /**
84
79
  * Error thrown when a transaction is not found in the template.
85
80
  */
86
- var TransactionNotFoundError = class extends Error {
81
+ var TemplateTransactionNotFoundError = class extends Error {
87
82
  constructor(transactionIdentifier) {
88
- const defaultMessage = "Transaction not found in template";
89
- super(transactionIdentifier ? `${defaultMessage}: transactionIdentifier "${transactionIdentifier}"` : defaultMessage);
83
+ super(`Template transaction not found, transactionIdentifier "${transactionIdentifier}"`);
90
84
  }
91
85
  };
92
86
  /**
@@ -273,7 +267,7 @@ var ItemNotFoundInCommitError = class extends Error {
273
267
  */
274
268
  var LockingBytecodeNotFoundForOutputError = class extends Error {
275
269
  constructor(outputIdentifier, transactionIndex) {
276
- const indexInfo = transactionIndex !== void 0 ? ` (transactionIndex: ${transactionIndex})` : " (transactionIndex: undefined)";
270
+ const indexInfo = ` (transactionIndex: ${transactionIndex ?? "undefined"})`;
277
271
  super(`Locking bytecode not found for output: ${outputIdentifier}${indexInfo}`);
278
272
  }
279
273
  };
@@ -293,9 +287,12 @@ var DuplicateTransactionLocktimeError = class extends Error {
293
287
  super(`Transaction locktime is defined in multiple commits: ${commitIdentifiers.join(", ")}`);
294
288
  }
295
289
  };
296
- var TemplateIdentifierMismatchError = class extends Error {
297
- constructor() {
298
- super("Template identifier mismatch");
290
+ /**
291
+ * Error thrown when the provided template's identifier does not match the invitation's template identifier.
292
+ */
293
+ var InvitationTemplateMismatchError = class extends Error {
294
+ constructor(expectedTemplateIdentifier, receivedTemplateIdentifier) {
295
+ super(`Invitation template mismatch in validation, expected templateIdentifier "${expectedTemplateIdentifier}", got "${receivedTemplateIdentifier}"`);
299
296
  }
300
297
  };
301
298
  /**
@@ -378,10 +375,9 @@ var RoleNotDefinedForActionError = class extends Error {
378
375
  /**
379
376
  * Error thrown when a role is not found.
380
377
  */
381
- var RoleNotFoundError = class extends Error {
382
- constructor(roleIdentifier) {
383
- const defaultMessage = "Role not found";
384
- super(roleIdentifier ? `${defaultMessage}: roleIdentifier "${roleIdentifier}"` : defaultMessage);
378
+ var TemplateLockingScriptRoleNotFoundError = class extends Error {
379
+ constructor(lockingScriptIdentifier, roleIdentifier) {
380
+ super(`Template locking script role not found, lockingScriptIdentifier "${lockingScriptIdentifier}", roleIdentifier "${roleIdentifier}"`);
385
381
  }
386
382
  };
387
383
  /**
@@ -585,9 +581,9 @@ var InvalidVariableDefinitionError = class extends Error {
585
581
  /**
586
582
  * Error thrown when an output does not have a locking script.
587
583
  */
588
- var OutputLockingScriptNotFoundError = class extends Error {
584
+ var TemplateLockingScriptInOutputNotFoundError = class extends Error {
589
585
  constructor(outputIdentifier) {
590
- super(`Output does not have a locking script: outputIdentifier "${outputIdentifier}"`);
586
+ super(`Template locking script in output not found, outputIdentifier "${outputIdentifier}"`);
591
587
  }
592
588
  };
593
589
  /**
@@ -842,7 +838,7 @@ const createLibauthCompilerDataFromUnspentOutput = async (template, unspentOutpu
842
838
  const { outputIdentifier } = unspentOutput;
843
839
  const output = template.getOutput(outputIdentifier);
844
840
  const lockingScriptForOutput = template.getLockingScriptForOutput(outputIdentifier);
845
- if (!lockingScriptForOutput.lockingBytecode) throw new LockingScriptNotFoundError(lockingScriptForOutput.lockingBytecode);
841
+ if (lockingScriptForOutput.lockingBytecode === void 0) throw new TemplateLockingScriptInOutputNotFoundError(outputIdentifier);
846
842
  template.validateLockingScript(lockingScriptForOutput, output.lockingScript);
847
843
  const lockingScriptIdentifier = output.lockingScript;
848
844
  let roleIdentifier = "owner";
@@ -1130,6 +1126,9 @@ var BlockchainMonitor = class {
1130
1126
  electrumEvents.on("OutputFinalized", (_data) => {});
1131
1127
  electrumEvents.on("OutputSpent", (_data) => {});
1132
1128
  electrumEvents.on("AddressUpdate", (_data) => {});
1129
+ electrumEvents.on("ScriptHashUpdate", async (data) => {
1130
+ await this.onScriptHashUpdate(data);
1131
+ });
1133
1132
  this.eventListenersInitialized = true;
1134
1133
  }
1135
1134
  /**
@@ -1151,14 +1150,13 @@ var BlockchainMonitor = class {
1151
1150
  }
1152
1151
  /**
1153
1152
  * Handles script hash update notifications from the electrum protocol.
1154
- * When a script hash update is received, this method finds all associated
1155
- * locking bytecodes and updates their unspent outputs in the store.
1153
+ * When a script hash update is received, this method finds the scriptHash and updates the unspent outputs for it.
1156
1154
  *
1157
- * @param {ScriptHashSubscribeNotification} data - The script hash subscription notification data.
1158
- * @returns {Promise<void>} Resolves when all unspent outputs are updated.
1155
+ * @param {ScriptHashUpdate} data - The script hash update data.
1156
+ * @returns {Promise<void>} Resolves when the unspent outputs are updated.
1159
1157
  */
1160
1158
  async onScriptHashUpdate(data) {
1161
- const [scriptHash] = data.params;
1159
+ const { scriptHash } = data;
1162
1160
  const scriptHashDataList = await this.state.listScriptHashData({ scriptHash });
1163
1161
  const [firstElectrumClient] = electrumClients.values();
1164
1162
  for (const scriptHashData of scriptHashDataList) await updateUnspentOutputsForScriptHashInStore(this.state, scriptHashData.scriptHash, async () => {
@@ -1167,6 +1165,28 @@ var BlockchainMonitor = class {
1167
1165
  }
1168
1166
  };
1169
1167
 
1168
+ //#endregion
1169
+ //#region source/invitation/commit.ts
1170
+ /**
1171
+ * Generates a random 16-byte commit identifier.
1172
+ *
1173
+ * @returns {string} The generated commit identifier as a hex string.
1174
+ */
1175
+ const generateCommitIdentifier = () => {
1176
+ return binToHex(generateRandomBytes(16));
1177
+ };
1178
+ /**
1179
+ * Finds the root commit identifier for a given entity in an invitation. The root commit is
1180
+ * the first commit the entity added to the invitation.
1181
+ *
1182
+ * @param {XOInvitation} invitation The invitation whose commits are searched.
1183
+ * @param {string} entityIdentifier The entity identifier to search for among the invitation commits.
1184
+ * @returns {string | undefined} The root commit identifier if the entity has a commit in the invitation, otherwise undefined.
1185
+ */
1186
+ const findRootCommitIdentifierInInvitation = (invitation, entityIdentifier) => {
1187
+ for (const commit of invitation.commits) if (commit.entityIdentifier === entityIdentifier) return commit.commitIdentifier;
1188
+ };
1189
+
1170
1190
  //#endregion
1171
1191
  //#region source/invitation/builder.ts
1172
1192
  /**
@@ -1247,7 +1267,8 @@ var InvitationBuilder = class InvitationBuilder {
1247
1267
  * @throws {InvalidCommitSignaturesError} If the commit signatures are invalid.
1248
1268
  */
1249
1269
  validate(template) {
1250
- if (generateTemplateIdentifier(template) !== this.templateIdentifier) throw new TemplateIdentifierMismatchError();
1270
+ const templateIdentifier = generateTemplateIdentifier(template);
1271
+ if (templateIdentifier !== this.templateIdentifier) throw new InvitationTemplateMismatchError(this.templateIdentifier, templateIdentifier);
1251
1272
  const action = new Template(template).getActionOrThrow(this.actionIdentifier);
1252
1273
  const invitation = this.build();
1253
1274
  if (hasInvitationExpired(invitation)) throw new InvitationExpiredError();
@@ -1313,15 +1334,21 @@ var InvitationBuilder = class InvitationBuilder {
1313
1334
  * This is a private helper method that initializes the commit building logic.
1314
1335
  */
1315
1336
  createCommit(params) {
1337
+ let variables;
1338
+ if (params.variables !== void 0 && params.variables.length > 0) variables = params.variables;
1339
+ let inputs;
1340
+ if (params.inputs !== void 0 && params.inputs.length > 0) inputs = params.inputs;
1341
+ let outputs;
1342
+ if (params.outputs !== void 0 && params.outputs.length > 0) outputs = params.outputs;
1316
1343
  const data = {
1317
- variables: params.variables && params.variables.length > 0 ? params.variables : void 0,
1318
- inputs: params.inputs && params.inputs.length > 0 ? params.inputs : void 0,
1319
- outputs: params.outputs && params.outputs.length > 0 ? params.outputs : void 0
1344
+ variables,
1345
+ inputs,
1346
+ outputs
1320
1347
  };
1321
1348
  if (params.transactionVersion !== void 0) data.transactionVersion = params.transactionVersion;
1322
1349
  if (params.transactionLocktime !== void 0) data.transactionLocktime = params.transactionLocktime;
1323
1350
  return {
1324
- commitIdentifier: binToHex(hash256(hexToBin(stringify(data) + params.previousCommitIdentifier + params.expiresAtTimestamp))),
1351
+ commitIdentifier: generateCommitIdentifier(),
1325
1352
  previousCommitIdentifier: params.previousCommitIdentifier,
1326
1353
  data,
1327
1354
  expiresAtTimestamp: params.expiresAtTimestamp
@@ -1338,28 +1365,6 @@ var InvitationBuilder = class InvitationBuilder {
1338
1365
  }
1339
1366
  };
1340
1367
 
1341
- //#endregion
1342
- //#region source/invitation/commit.ts
1343
- /**
1344
- * Generates a random 16-byte commit identifier.
1345
- *
1346
- * @returns {string} The generated commit identifier as a hex string.
1347
- */
1348
- const generateCommitIdentifier = () => {
1349
- return binToHex(generateRandomBytes(16));
1350
- };
1351
- /**
1352
- * Finds the root commit identifier for a given entity in an invitation. The root commit is
1353
- * the first commit the entity added to the invitation.
1354
- *
1355
- * @param {XOInvitation} invitation The invitation whose commits are searched.
1356
- * @param {string} entityIdentifier The entity identifier to search for among the invitation commits.
1357
- * @returns {string | undefined} The root commit identifier if the entity has a commit in the invitation, otherwise undefined.
1358
- */
1359
- const findRootCommitIdentifierInInvitation = (invitation, entityIdentifier) => {
1360
- for (const commit of invitation.commits) if (commit.entityIdentifier === entityIdentifier) return commit.commitIdentifier;
1361
- };
1362
-
1363
1368
  //#endregion
1364
1369
  //#region source/utils/template.ts
1365
1370
  /**
@@ -1374,7 +1379,6 @@ var Template = class {
1374
1379
  * Creates a Template class from a template object.
1375
1380
  */
1376
1381
  constructor(template) {
1377
- if (!template) throw new TemplateNotFoundError();
1378
1382
  this.template = template;
1379
1383
  }
1380
1384
  /**
@@ -1392,41 +1396,37 @@ var Template = class {
1392
1396
  }
1393
1397
  /**
1394
1398
  * Retrieves an output definition by identifier.
1395
- * Step 1 in the flow: template → output
1396
- * @throws {OutputNotFoundError} If the output is not found.
1399
+ * @throws {TemplateOutputNotFoundError} If the output is not found.
1397
1400
  */
1398
1401
  getOutput(outputIdentifier) {
1399
1402
  const output = this.template.outputs[outputIdentifier];
1400
- if (!output) throw new OutputNotFoundError(outputIdentifier);
1403
+ if (output === void 0) throw new TemplateOutputNotFoundError(outputIdentifier);
1401
1404
  return output;
1402
1405
  }
1403
1406
  /**
1404
1407
  * Retrieves the locking script identifier from an output.
1405
- * Step 2 in the flow: output → locking script identifier
1406
- * @throws {OutputNotFoundError} If the output is not found.
1407
- * @throws {LockingScriptNotFoundError} If the output doesn't have a locking script identifier.
1408
+ * @throws {TemplateOutputNotFoundError} If the output is not found.
1409
+ * @throws {TemplateLockingScriptInOutputNotFoundError} If the output has no locking script reference.
1408
1410
  */
1409
1411
  getLockingScriptIdentifier(outputIdentifier) {
1410
1412
  const output = this.getOutput(outputIdentifier);
1411
- if (!output.lockingScript) throw new LockingScriptNotFoundError(outputIdentifier);
1413
+ if (output.lockingScript === void 0) throw new TemplateLockingScriptInOutputNotFoundError(outputIdentifier);
1412
1414
  return output.lockingScript;
1413
1415
  }
1414
1416
  /**
1415
1417
  * Retrieves a locking script definition by identifier.
1416
- * Step 3 in the flow: locking script identifier → locking script
1417
- * @throws {LockingScriptNotFoundError} If the locking script is not found.
1418
+ * @throws {TemplateLockingScriptNotFoundError} If the locking script is not found.
1418
1419
  */
1419
1420
  getLockingScript(lockingScriptIdentifier) {
1420
1421
  const lockingScript = this.template.lockingScripts[lockingScriptIdentifier];
1421
- if (!lockingScript) throw new LockingScriptNotFoundError(lockingScriptIdentifier);
1422
+ if (lockingScript === void 0) throw new TemplateLockingScriptNotFoundError(lockingScriptIdentifier);
1422
1423
  return lockingScript;
1423
1424
  }
1424
1425
  /**
1425
1426
  * Retrieves the locking script for a given output.
1426
- * Combines steps 1-3: output → locking script identifier → locking script
1427
- * @throws {OutputNotFoundError} If the output is not found.
1428
- * @throws {LockingScriptNotFoundError} If the output doesn't have a locking script identifier.
1429
- * @throws {LockingScriptNotFoundError} If the locking script is not found.
1427
+ * @throws {TemplateOutputNotFoundError} If the output is not found.
1428
+ * @throws {TemplateLockingScriptInOutputNotFoundError} If the output has no locking script reference.
1429
+ * @throws {TemplateLockingScriptNotFoundError} If the locking script definition is not found.
1430
1430
  */
1431
1431
  getLockingScriptForOutput(outputIdentifier) {
1432
1432
  const lockingScriptIdentifier = this.getLockingScriptIdentifier(outputIdentifier);
@@ -1434,85 +1434,81 @@ var Template = class {
1434
1434
  }
1435
1435
  /**
1436
1436
  * Validates that a locking script has required unlocking script and locking type.
1437
- * Step 4 in the flow: validate locking script
1438
1437
  * @param lockingScript - The locking script to validate.
1439
1438
  * @param lockingScriptIdentifier - The identifier of the locking script (for error messages).
1440
- * @throws {LockingScriptTypeNotFoundError} If lockingType is missing.
1439
+ * @throws {TemplateLockingScriptTypeNotFoundError} If lockingType is missing.
1441
1440
  */
1442
1441
  validateLockingScript(lockingScript, lockingScriptIdentifier) {
1443
- if (!lockingScript.lockingType) throw new LockingScriptTypeNotFoundError(lockingScriptIdentifier);
1442
+ if (lockingScript.lockingType === void 0) throw new TemplateLockingScriptTypeNotFoundError(lockingScriptIdentifier);
1444
1443
  }
1445
1444
  /**
1446
1445
  * Retrieves a role within a locking script.
1447
- * Step 5 in the flow: locking script → role
1448
1446
  * @param lockingScriptIdentifier - The locking script identifier.
1449
1447
  * @param roleIdentifier - The role identifier.
1450
- * @throws {LockingScriptNotFoundError} If the locking script is not found.
1451
- * @throws {RoleNotFoundError} If the role is not found.
1448
+ * @throws {TemplateLockingScriptNotFoundError} If the locking script is not found.
1449
+ * @throws {TemplateLockingScriptRoleNotFoundError} If the role is not found.
1452
1450
  */
1453
1451
  getRole(lockingScriptIdentifier, roleIdentifier) {
1454
1452
  const role = this.getLockingScript(lockingScriptIdentifier).roles?.[roleIdentifier];
1455
- if (!role) throw new RoleNotFoundError(roleIdentifier);
1453
+ if (role === void 0) throw new TemplateLockingScriptRoleNotFoundError(lockingScriptIdentifier, roleIdentifier);
1456
1454
  return role;
1457
1455
  }
1458
1456
  /**
1459
1457
  * Retrieves the first available role in a locking script, or throws if none exist.
1460
1458
  * @param lockingScriptIdentifier - The locking script identifier.
1461
1459
  * @returns A tuple of [roleIdentifier, role].
1462
- * @throws {LockingScriptNotFoundError} If the locking script is not found.
1463
- * @throws {RoleNotFoundError} If no roles exist.
1460
+ * @throws {TemplateLockingScriptNotFoundError} If the locking script is not found.
1461
+ * @throws {TemplateLockingScriptRoleNotFoundError} If no roles exist.
1464
1462
  */
1465
1463
  getFirstRole(lockingScriptIdentifier) {
1466
1464
  const roles = this.getLockingScript(lockingScriptIdentifier).roles ?? {};
1467
1465
  const roleKeys = Object.keys(roles);
1468
- if (roleKeys.length === 0) throw new RoleNotFoundError();
1466
+ if (roleKeys.length === 0) throw new TemplateLockingScriptRoleNotFoundError(lockingScriptIdentifier, "");
1469
1467
  return [roleKeys[0], roles[roleKeys[0]]];
1470
1468
  }
1471
1469
  /**
1472
1470
  * Retrieves secrets for a locking script.
1473
1471
  * If roleIdentifier is provided, returns secrets from the role's state.
1474
1472
  * Otherwise, returns secrets from the locking script itself.
1475
- * Step 6 in the flow: role → secrets (or locking script → secrets)
1476
1473
  * @param lockingScriptIdentifier - The locking script identifier.
1477
1474
  * @param roleIdentifier - The role identifier (optional, if not provided uses locking script secrets).
1478
1475
  * @returns Array of secret identifiers.
1479
- * @throws {LockingScriptNotFoundError} If the locking script is not found.
1480
- * @throws {RoleNotFoundError} If roleIdentifier is provided but the role is not found.
1476
+ * @throws {TemplateLockingScriptNotFoundError} If the locking script is not found.
1477
+ * @throws {TemplateLockingScriptRoleNotFoundError} If roleIdentifier is provided but the role is not found.
1481
1478
  */
1482
1479
  getSecrets(lockingScriptIdentifier, roleIdentifier) {
1483
- if (roleIdentifier) return this.getRole(lockingScriptIdentifier, roleIdentifier).state?.secrets ?? [];
1480
+ if (roleIdentifier !== void 0) return this.getRole(lockingScriptIdentifier, roleIdentifier).state?.secrets ?? [];
1484
1481
  return this.getLockingScript(lockingScriptIdentifier).state?.secrets ?? [];
1485
1482
  }
1486
1483
  /**
1487
1484
  * Retrieves an action definition by identifier.
1488
1485
  * @param actionIdentifier - The identifier of the action.
1489
- * @throws {ActionNotFoundError} If the action is not found.
1486
+ * @throws {TemplateActionNotFoundError} If the action is not found.
1490
1487
  */
1491
1488
  getActionOrThrow(actionIdentifier) {
1492
1489
  const action = this.template.actions[actionIdentifier];
1493
- if (!action) throw new ActionNotFoundError(actionIdentifier);
1490
+ if (action === void 0) throw new TemplateActionNotFoundError(actionIdentifier);
1494
1491
  return action;
1495
1492
  }
1496
1493
  /**
1497
1494
  * Retrieves a transaction definition by identifier.
1498
1495
  * @param transactionIdentifier - The identifier of the transaction.
1499
- * @throws {TransactionNotFoundError} If the transaction is not found.
1496
+ * @throws {TemplateTransactionNotFoundError} If the transaction is not found.
1500
1497
  */
1501
1498
  getTransaction(transactionIdentifier) {
1502
1499
  const transaction = this.template.transactions?.[transactionIdentifier];
1503
- if (!transaction) throw new TransactionNotFoundError(transactionIdentifier);
1500
+ if (transaction === void 0) throw new TemplateTransactionNotFoundError(transactionIdentifier);
1504
1501
  return transaction;
1505
1502
  }
1506
1503
  /**
1507
1504
  * Retrieves the transaction for a given action.
1508
- * Flow: action → transaction identifier → transaction
1509
1505
  * @param actionIdentifier - The identifier of the action.
1510
- * @throws {ActionNotFoundError} If the action is not found.
1511
- * @throws {TransactionNotFoundError} If the action doesn't have a transaction or it's not found.
1506
+ * @throws {TemplateActionNotFoundError} If the action is not found.
1507
+ * @throws {TemplateTransactionNotFoundError} If the action has no transaction defined or the transaction is not found.
1512
1508
  */
1513
1509
  getTransactionForAction(actionIdentifier) {
1514
1510
  const action = this.getActionOrThrow(actionIdentifier);
1515
- if (!action.transaction) throw new TransactionNotFoundError(action.transaction);
1511
+ if (action.transaction === void 0) throw new TemplateTransactionNotFoundError(actionIdentifier);
1516
1512
  return this.getTransaction(action.transaction);
1517
1513
  }
1518
1514
  };
@@ -2204,12 +2200,12 @@ var Engine = class Engine {
2204
2200
  /**
2205
2201
  * Constructs a new instance of XO Engine.
2206
2202
  * @private
2207
- * @param {string} seed - The wallet seed.
2208
- * @param {State} store - Store instance.
2203
+ * @param {string} mnemonic - The BIP39 mnemonic to be used for this instance of the engine.
2204
+ * @param {State} state - State instance.
2209
2205
  * @param {BlockchainMonitor} blockchainMonitor - Blockchain monitor instance.
2210
2206
  */
2211
- constructor(seed, state, blockchainMonitor) {
2212
- this.crypto = new Crypto(convertMnemonicToSeedBytes(seed));
2207
+ constructor(mnemonic, state, blockchainMonitor) {
2208
+ this.crypto = new Crypto(convertMnemonicToSeedBytes(mnemonic));
2213
2209
  this.state = state;
2214
2210
  this.blockchainMonitor = blockchainMonitor;
2215
2211
  }
@@ -2217,16 +2213,16 @@ var Engine = class Engine {
2217
2213
  * Initializes and creates a new XO Engine instance.
2218
2214
  * Configures the state, initializes the sync server and monitor for app and blockchain events
2219
2215
  *
2220
- * @param {string} seed - Wallet seed used for signing and/or key derivation.
2216
+ * @param {string} mnemonic - BIP39 mnemonic to be used for this instance of the engine.
2221
2217
  * @param {XOEngineOptions} options - Database configuration options.
2222
2218
  * @returns {Promise<Engine>} An initialized Engine instance.
2223
2219
  */
2224
- static async create(seed, options) {
2220
+ static async create(mnemonic, options) {
2225
2221
  await initializeElectrumApplication(options.electrumApplicationIdentifier ?? DEFAULT_ELECTRUM_APPLICATION_IDENTIFIER, {
2226
2222
  electrumServers,
2227
2223
  ...options
2228
2224
  });
2229
- const accountHash = binToHex(sha256.hash(utf8ToBin(seed)));
2225
+ const accountHash = binToHex(sha256.hash(utf8ToBin(mnemonic)));
2230
2226
  const stateInstance = new State(await createStorageAdapter({
2231
2227
  storageType: options.storageType ?? DEFAULT_STORAGE_TYPE,
2232
2228
  databasePath: options.databasePath,
@@ -2235,7 +2231,7 @@ var Engine = class Engine {
2235
2231
  }));
2236
2232
  const blockchainMonitor = new BlockchainMonitor(stateInstance);
2237
2233
  blockchainMonitor.initializeEventListeners();
2238
- const engineInstance = new Engine(seed, stateInstance, blockchainMonitor);
2234
+ const engineInstance = new Engine(mnemonic, stateInstance, blockchainMonitor);
2239
2235
  await engineInstance.initializeStateSync();
2240
2236
  return engineInstance;
2241
2237
  }
@@ -2259,7 +2255,7 @@ var Engine = class Engine {
2259
2255
  * @returns {Promise<XOTemplate | undefined>} The template object.
2260
2256
  */
2261
2257
  async getTemplate(templateIdentifier) {
2262
- return await this.state.getTemplate(templateIdentifier);
2258
+ return this.state.getTemplate(templateIdentifier);
2263
2259
  }
2264
2260
  /**
2265
2261
  * Imports a template into the Engine after sanitization and validation.
@@ -2280,7 +2276,7 @@ var Engine = class Engine {
2280
2276
  * @returns {Promise<XOTemplate[]>} The list of imported templates.
2281
2277
  */
2282
2278
  async listImportedTemplates() {
2283
- return await this.state.listTemplates() ?? [];
2279
+ return this.state.listTemplates();
2284
2280
  }
2285
2281
  /**
2286
2282
  * Lists the starting actions available in a specified template.
@@ -2355,7 +2351,7 @@ var Engine = class Engine {
2355
2351
  * @param {string} params.actionIdentifier - Identifier for the action to initiate.
2356
2352
  * @returns {Promise<XOInvitation>} A promise that resolves to the constructed invitation.
2357
2353
  * @throws {TemplateNotFoundError} If the template is not found.
2358
- * @throws {ActionNotFoundError} If the action is not found.
2354
+ * @throws {TemplateActionNotFoundError} If the action is not found.
2359
2355
  *
2360
2356
  * TODO: Add all the throws that happen during the execution of the method.
2361
2357
  */
@@ -2386,7 +2382,7 @@ var Engine = class Engine {
2386
2382
  * @param {AcceptInvitationParameters} params - Optional parameters for accepting the invitation.
2387
2383
  * @returns {Promise<XOInvitation>} The updated XOInvitation instance.
2388
2384
  * @throws {TemplateNotFoundError} If the template is not found.
2389
- * @throws {ActionNotFoundError} If the action is not found.
2385
+ * @throws {TemplateActionNotFoundError} If the action is not found.
2390
2386
  * @throws {InvalidEntityIdentifierError} If the entity identifiers are invalid.
2391
2387
  * @throws {InvalidRequirementsError} If the requirements are invalid.
2392
2388
  * @throws {InvalidCommitSignaturesError} If the commit signatures are invalid.
@@ -2551,7 +2547,7 @@ var Engine = class Engine {
2551
2547
  const action = new Template(templateFromStore).getActionOrThrow(builder.actionIdentifier);
2552
2548
  const mergedCommit = mergeInvitationCommits(builder, templateFromStore);
2553
2549
  if (!mergedCommit) throw new MergedCommitNotFoundError();
2554
- if (!action.transaction) throw new TransactionNotFoundError();
2550
+ if (action.transaction === void 0) throw new TemplateTransactionNotFoundError(builder.actionIdentifier);
2555
2551
  const resultTransaction = generateTransaction({
2556
2552
  version: mergedCommit.transactionVersion,
2557
2553
  locktime: mergedCommit.transactionLocktime,
@@ -2565,33 +2561,12 @@ var Engine = class Engine {
2565
2561
  return txHash;
2566
2562
  }
2567
2563
  /**
2568
- * Fully validates a given XOInvitation according to template and signature checks.
2569
- *
2570
- * @param {XOInvitation} invitation - The invitation to validate.
2571
- * @returns {Promise<void>} Resolves if invitation is valid.
2572
- * @throws {TemplateNotFoundError} If the template is not found.
2573
- * @throws {ActionNotFoundError} If the action is not found.
2574
- * @throws {InvitationExpiredError} If the invitation has expired.
2575
- * @throws {InvalidEntityIdentifierError} If the entity identifiers are invalid.
2576
- * @throws {InvalidRequirementsError} If the requirements are invalid.
2577
- * @throws {InvalidCommitSignaturesError} If the commit signatures are invalid.
2578
- */
2579
- async isInvitationValid(invitation) {
2580
- const template = new Template(await this.state.getTemplate(invitation.templateIdentifier));
2581
- try {
2582
- InvitationBuilder.fromInvitation(invitation).validate(template.getTemplate());
2583
- return true;
2584
- } catch {
2585
- return false;
2586
- }
2587
- }
2588
- /**
2589
2564
  * Lists available roles for the given invitation.
2590
2565
  *
2591
2566
  * @param {XOInvitation} invitation - The invitation to examine.
2592
2567
  * @returns {Promise<string[]>} The list of roles that still require data.
2593
2568
  * @throws {TemplateNotFoundError} If the template is not found.
2594
- * @throws {ActionNotFoundError} If the action is not found.
2569
+ * @throws {TemplateActionNotFoundError} If the action is not found.
2595
2570
  */
2596
2571
  async listAvailableRoles(invitation) {
2597
2572
  return listAvailableRolesForInvitation(invitation, new Template(await this.getTemplateOrThrow(invitation.templateIdentifier)).getActionOrThrow(invitation.actionIdentifier));
@@ -2706,10 +2681,12 @@ var Engine = class Engine {
2706
2681
  * @throws {Error} If any required template, output, or configuration is not found, or if compilation fails.
2707
2682
  */
2708
2683
  async generateLockingBytecode(templateIdentifier, outputIdentifier, roleIdentifier) {
2709
- const template = new Template(await this.state.getTemplate(templateIdentifier));
2684
+ const templateData = await this.state.getTemplate(templateIdentifier);
2685
+ if (templateData === void 0) throw new TemplateNotFoundError(templateIdentifier);
2686
+ const template = new Template(templateData);
2710
2687
  const output = template.getOutput(outputIdentifier);
2711
2688
  const lockingScriptForOutput = template.getLockingScriptForOutput(outputIdentifier);
2712
- if (!output.lockingScript) throw new LockingScriptTypeNotFoundError(outputIdentifier);
2689
+ if (!output.lockingScript) throw new TemplateLockingScriptTypeNotFoundError(outputIdentifier);
2713
2690
  template.validateLockingScript(lockingScriptForOutput, output.lockingScript);
2714
2691
  const selectedRoleId = roleIdentifier ?? template.getFirstRole(output.lockingScript)[0];
2715
2692
  if (roleIdentifier) template.getRole(output.lockingScript, roleIdentifier);
@@ -2717,10 +2694,10 @@ var Engine = class Engine {
2717
2694
  const entityOwnership = entityOwnershipForLibauthCompiler(template.getTemplate(), finalRoleIdentifier);
2718
2695
  const scripts = scriptsForLibauthCompiler(template.getTemplate());
2719
2696
  const variables = assignTypeToVariablesForLibauthCompiler(template.getTemplate());
2720
- if (lockingScriptForOutput.unlockingBytecode === void 0 || lockingScriptForOutput.lockingBytecode === void 0) throw new LockingScriptTypeNotFoundError(outputIdentifier);
2697
+ if (lockingScriptForOutput.unlockingBytecode === void 0 || lockingScriptForOutput.lockingBytecode === void 0) throw new TemplateLockingScriptTypeNotFoundError(outputIdentifier);
2721
2698
  const unlockingScripts = { [lockingScriptForOutput.unlockingBytecode]: lockingScriptForOutput.lockingBytecode };
2722
2699
  const { lockingType } = lockingScriptForOutput;
2723
- if (!lockingType) throw new LockingScriptTypeNotFoundError(outputIdentifier);
2700
+ if (!lockingType) throw new TemplateLockingScriptTypeNotFoundError(outputIdentifier);
2724
2701
  const compiler = createCompilerBch({
2725
2702
  entityOwnership,
2726
2703
  scripts,
@@ -2740,7 +2717,7 @@ var Engine = class Engine {
2740
2717
  };
2741
2718
  break;
2742
2719
  }
2743
- default: throw new LockingScriptTypeNotFoundError(output.lockingScript ?? outputIdentifier);
2720
+ default: throw new TemplateLockingScriptTypeNotFoundError(output.lockingScript ?? outputIdentifier);
2744
2721
  }
2745
2722
  if (!lockingData) throw new LockingDataNotFoundError();
2746
2723
  const scriptId = lockingScriptForOutput.lockingBytecode;
@@ -2874,5 +2851,5 @@ var Engine = class Engine {
2874
2851
  };
2875
2852
 
2876
2853
  //#endregion
2877
- export { ActionNotFoundError, BlockchainMonitor, CashAssemblyCompilationFailedError, CashAssemblyVariableNotIntegerError, CircularMergeReferenceError, CommitEntityIdentifierNotFoundError, CommitNotFoundInInvitationError, CommitNotSignedError, CreatedByIdentifierAlreadySetError, CreatedByIdentifierSignatureAlreadySetError, DataNotFoundError, DuplicateTransactionIndexError, DuplicateTransactionLocktimeError, DuplicateTransactionVersionError, ElectrumClientNotFoundError, Engine, InvalidActionError, InvalidCommitSignaturesError, InvalidDataTypeError, InvalidDerivativeIndexTypeError, InvalidEntityIdentifierError, InvalidInputError, InvalidInvitationError, InvalidLockingScriptTypeError, InvalidLockingTypeError, InvalidRequirementsError, InvalidRoleError, InvalidTemplateOutputSatoshisTypeError, InvalidVariableDefinitionError, InvalidVariableTypeError, InvitationAlreadyAcceptedError, InvitationBuilder, InvitationCreatedInFutureError, InvitationExpiredError, InvitationNotAcceptedError, InvitationNotFoundInStoreError, ItemNotFoundInCommitError, LockingBytecodeGenerationFailedError, LockingBytecodeNotFoundForOutputError, LockingDataNotFoundError, LockingScriptNotFoundError, LockingScriptTypeNotFoundError, MergedCommitNotFoundError, MergesWithCommitNotFoundError, MissingRequiredDataError, MissingRequiredFieldError, MissingRequiredRoleForEntityError, MissingRequiredSignatureByEntityError, MissingRequiredVariableError, MultipleRolesForStartingActionError, NoRoleSpecifiedAndMultipleRolesAvailableToBeAcceptedError, OutputLockingScriptNotFoundError, OutputNotFoundError, ParentCommitNotFoundError, ReserveResourcesFailedError, RoleAlreadyAcceptedByAnotherEntityError, RoleCannotStartActionError, RoleNotAvailableToBeAcceptedError, RoleNotDefinedForActionError, RoleNotFoundError, RootCommitNotFoundError, ScriptHashDataNotFoundError, ScriptNotFoundError, SignatureVerificationFailedError, StartingActionNotFoundError, Template, TemplateIdentifierMismatchError, TemplateNotFoundError, TransactionGenerationFailedError, TransactionNotFoundError, UnknownVariableError, UnlockingScriptNotFoundError, UnspentOutputNotFoundError, VariableRequiredError, VariableValidationFailedError, assignTypeToVariablesForLibauthCompiler, compileCashAssemblyEvaluations, compileCashAssemblyString, convertCommitVariablesIntoObject, convertXOLockingTypeToLibauth, createLibauthCompilerDataFromUnspentOutput, decodeCompiledCashAssemblyEvaluation, entityOwnershipForLibauthCompiler, extractCashAssemblyEvaluations, extractVariablesFromEvaluations, findRootCommitIdentifierInInvitation, generateCashAssemblyBytecode, generateCommitIdentifier, generateTemplateIdentifier, hasInvitationExpired, isCashAssemblyExpression, listAvailableRolesForInvitation, listMissingRequirements, listPopulatedRequirementsInInvitation, listRequirementsFromTemplate, mergeInvitationCommits, parseTemplate, scriptsForLibauthCompiler, updateUnspentOutputsForScriptHashInStore, validateInvitationCommits, validateInvitationEntities, validateRoleRequirements };
2854
+ export { BlockchainMonitor, CashAssemblyCompilationFailedError, CashAssemblyVariableNotIntegerError, CircularMergeReferenceError, CommitEntityIdentifierNotFoundError, CommitNotFoundInInvitationError, CommitNotSignedError, CreatedByIdentifierAlreadySetError, CreatedByIdentifierSignatureAlreadySetError, DataNotFoundError, DuplicateTransactionIndexError, DuplicateTransactionLocktimeError, DuplicateTransactionVersionError, ElectrumClientNotFoundError, Engine, InvalidActionError, InvalidCommitSignaturesError, InvalidDataTypeError, InvalidDerivativeIndexTypeError, InvalidEntityIdentifierError, InvalidInputError, InvalidInvitationError, InvalidLockingScriptTypeError, InvalidLockingTypeError, InvalidRequirementsError, InvalidRoleError, InvalidTemplateOutputSatoshisTypeError, InvalidVariableDefinitionError, InvalidVariableTypeError, InvitationAlreadyAcceptedError, InvitationBuilder, InvitationCreatedInFutureError, InvitationExpiredError, InvitationNotAcceptedError, InvitationNotFoundInStoreError, InvitationTemplateMismatchError, ItemNotFoundInCommitError, LockingBytecodeGenerationFailedError, LockingBytecodeNotFoundForOutputError, LockingDataNotFoundError, MergedCommitNotFoundError, MergesWithCommitNotFoundError, MissingRequiredDataError, MissingRequiredFieldError, MissingRequiredRoleForEntityError, MissingRequiredSignatureByEntityError, MissingRequiredVariableError, MultipleRolesForStartingActionError, NoRoleSpecifiedAndMultipleRolesAvailableToBeAcceptedError, ParentCommitNotFoundError, ReserveResourcesFailedError, RoleAlreadyAcceptedByAnotherEntityError, RoleCannotStartActionError, RoleNotAvailableToBeAcceptedError, RoleNotDefinedForActionError, RootCommitNotFoundError, ScriptHashDataNotFoundError, ScriptNotFoundError, SignatureVerificationFailedError, StartingActionNotFoundError, Template, TemplateActionNotFoundError, TemplateLockingScriptInOutputNotFoundError, TemplateLockingScriptNotFoundError, TemplateLockingScriptRoleNotFoundError, TemplateLockingScriptTypeNotFoundError, TemplateNotFoundError, TemplateOutputNotFoundError, TemplateTransactionNotFoundError, TransactionGenerationFailedError, UnknownVariableError, UnlockingScriptNotFoundError, UnspentOutputNotFoundError, VariableRequiredError, VariableValidationFailedError, assignTypeToVariablesForLibauthCompiler, compileCashAssemblyEvaluations, compileCashAssemblyString, convertCommitVariablesIntoObject, convertXOLockingTypeToLibauth, createLibauthCompilerDataFromUnspentOutput, decodeCompiledCashAssemblyEvaluation, entityOwnershipForLibauthCompiler, extractCashAssemblyEvaluations, extractVariablesFromEvaluations, findRootCommitIdentifierInInvitation, generateCashAssemblyBytecode, generateCommitIdentifier, generateTemplateIdentifier, hasInvitationExpired, isCashAssemblyExpression, listAvailableRolesForInvitation, listMissingRequirements, listPopulatedRequirementsInInvitation, listRequirementsFromTemplate, mergeInvitationCommits, parseTemplate, scriptsForLibauthCompiler, updateUnspentOutputsForScriptHashInStore, validateInvitationCommits, validateInvitationEntities, validateRoleRequirements };
2878
2855
  //# sourceMappingURL=index.mjs.map