@ledgerhq/coin-module-framework 8.1.0 → 8.3.0

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.
Files changed (117) hide show
  1. package/CHANGELOG.md +104 -0
  2. package/lib/api/impl.d.ts +74 -0
  3. package/lib/api/impl.d.ts.map +1 -0
  4. package/lib/api/impl.js +60 -0
  5. package/lib/api/impl.js.map +1 -0
  6. package/lib/api/index.d.ts +4 -0
  7. package/lib/api/index.d.ts.map +1 -1
  8. package/lib/api/index.js +4 -0
  9. package/lib/api/index.js.map +1 -1
  10. package/lib/api/notSupported.d.ts +14 -0
  11. package/lib/api/notSupported.d.ts.map +1 -1
  12. package/lib/api/notSupported.js +31 -2
  13. package/lib/api/notSupported.js.map +1 -1
  14. package/lib/api/notSupportedApi.d.ts +37 -0
  15. package/lib/api/notSupportedApi.d.ts.map +1 -0
  16. package/lib/api/notSupportedApi.js +68 -0
  17. package/lib/api/notSupportedApi.js.map +1 -0
  18. package/lib/api/withDefaults.d.ts +31 -0
  19. package/lib/api/withDefaults.d.ts.map +1 -0
  20. package/lib/api/withDefaults.js +57 -0
  21. package/lib/api/withDefaults.js.map +1 -0
  22. package/lib/api/wrappers/index.d.ts +17 -0
  23. package/lib/api/wrappers/index.d.ts.map +1 -0
  24. package/lib/api/wrappers/index.js +35 -0
  25. package/lib/api/wrappers/index.js.map +1 -0
  26. package/lib/api/wrappers/instrumenter.d.ts +27 -0
  27. package/lib/api/wrappers/instrumenter.d.ts.map +1 -0
  28. package/lib/api/wrappers/instrumenter.js +46 -0
  29. package/lib/api/wrappers/instrumenter.js.map +1 -0
  30. package/lib/api/wrappers/withLogging.d.ts +11 -0
  31. package/lib/api/wrappers/withLogging.d.ts.map +1 -0
  32. package/lib/api/wrappers/withLogging.js +40 -0
  33. package/lib/api/wrappers/withLogging.js.map +1 -0
  34. package/lib/api/wrappers/withTracing.d.ts +18 -0
  35. package/lib/api/wrappers/withTracing.d.ts.map +1 -0
  36. package/lib/api/wrappers/withTracing.js +40 -0
  37. package/lib/api/wrappers/withTracing.js.map +1 -0
  38. package/lib/errors.d.ts +9 -0
  39. package/lib/errors.d.ts.map +1 -1
  40. package/lib/errors.js +17 -1
  41. package/lib/errors.js.map +1 -1
  42. package/lib/test-utils/capabilities.d.ts +44 -0
  43. package/lib/test-utils/capabilities.d.ts.map +1 -0
  44. package/lib/test-utils/capabilities.js +44 -0
  45. package/lib/test-utils/capabilities.js.map +1 -0
  46. package/lib/test-utils/helpers.d.ts +1 -1
  47. package/lib/test-utils/helpers.d.ts.map +1 -1
  48. package/lib/test-utils/helpers.js +15 -0
  49. package/lib/test-utils/helpers.js.map +1 -1
  50. package/lib-es/api/impl.d.ts +74 -0
  51. package/lib-es/api/impl.d.ts.map +1 -0
  52. package/lib-es/api/impl.js +57 -0
  53. package/lib-es/api/impl.js.map +1 -0
  54. package/lib-es/api/index.d.ts +4 -0
  55. package/lib-es/api/index.d.ts.map +1 -1
  56. package/lib-es/api/index.js +4 -0
  57. package/lib-es/api/index.js.map +1 -1
  58. package/lib-es/api/notSupported.d.ts +14 -0
  59. package/lib-es/api/notSupported.d.ts.map +1 -1
  60. package/lib-es/api/notSupported.js +30 -2
  61. package/lib-es/api/notSupported.js.map +1 -1
  62. package/lib-es/api/notSupportedApi.d.ts +37 -0
  63. package/lib-es/api/notSupportedApi.d.ts.map +1 -0
  64. package/lib-es/api/notSupportedApi.js +65 -0
  65. package/lib-es/api/notSupportedApi.js.map +1 -0
  66. package/lib-es/api/withDefaults.d.ts +31 -0
  67. package/lib-es/api/withDefaults.d.ts.map +1 -0
  68. package/lib-es/api/withDefaults.js +54 -0
  69. package/lib-es/api/withDefaults.js.map +1 -0
  70. package/lib-es/api/wrappers/index.d.ts +17 -0
  71. package/lib-es/api/wrappers/index.d.ts.map +1 -0
  72. package/lib-es/api/wrappers/index.js +19 -0
  73. package/lib-es/api/wrappers/index.js.map +1 -0
  74. package/lib-es/api/wrappers/instrumenter.d.ts +27 -0
  75. package/lib-es/api/wrappers/instrumenter.d.ts.map +1 -0
  76. package/lib-es/api/wrappers/instrumenter.js +43 -0
  77. package/lib-es/api/wrappers/instrumenter.js.map +1 -0
  78. package/lib-es/api/wrappers/withLogging.d.ts +11 -0
  79. package/lib-es/api/wrappers/withLogging.d.ts.map +1 -0
  80. package/lib-es/api/wrappers/withLogging.js +37 -0
  81. package/lib-es/api/wrappers/withLogging.js.map +1 -0
  82. package/lib-es/api/wrappers/withTracing.d.ts +18 -0
  83. package/lib-es/api/wrappers/withTracing.d.ts.map +1 -0
  84. package/lib-es/api/wrappers/withTracing.js +37 -0
  85. package/lib-es/api/wrappers/withTracing.js.map +1 -0
  86. package/lib-es/errors.d.ts +9 -0
  87. package/lib-es/errors.d.ts.map +1 -1
  88. package/lib-es/errors.js +14 -0
  89. package/lib-es/errors.js.map +1 -1
  90. package/lib-es/test-utils/capabilities.d.ts +44 -0
  91. package/lib-es/test-utils/capabilities.d.ts.map +1 -0
  92. package/lib-es/test-utils/capabilities.js +41 -0
  93. package/lib-es/test-utils/capabilities.js.map +1 -0
  94. package/lib-es/test-utils/helpers.d.ts +1 -1
  95. package/lib-es/test-utils/helpers.d.ts.map +1 -1
  96. package/lib-es/test-utils/helpers.js +1 -0
  97. package/lib-es/test-utils/helpers.js.map +1 -1
  98. package/package.json +1 -1
  99. package/src/api/impl.test.ts +83 -0
  100. package/src/api/impl.ts +112 -0
  101. package/src/api/index.ts +4 -0
  102. package/src/api/notSupported.ts +32 -2
  103. package/src/api/notSupportedApi.test.ts +67 -0
  104. package/src/api/notSupportedApi.ts +74 -0
  105. package/src/api/withDefaults.test.ts +190 -0
  106. package/src/api/withDefaults.ts +87 -0
  107. package/src/api/wrappers/index.ts +20 -0
  108. package/src/api/wrappers/instrumenter.test.ts +123 -0
  109. package/src/api/wrappers/instrumenter.ts +58 -0
  110. package/src/api/wrappers/withLogging.test.ts +137 -0
  111. package/src/api/wrappers/withLogging.ts +47 -0
  112. package/src/api/wrappers/withTracing.test.ts +125 -0
  113. package/src/api/wrappers/withTracing.ts +56 -0
  114. package/src/errors.ts +17 -0
  115. package/src/test-utils/capabilities.test.ts +108 -0
  116. package/src/test-utils/capabilities.ts +93 -0
  117. package/src/test-utils/helpers.ts +2 -0
@@ -1 +1 @@
1
- {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,44 @@
1
+ import type { CoinModuleImpl, OptionalApiKey } from '../api/impl';
2
+ import type { Memo, TxData } from '../api/types';
3
+ import type { Context, CurrencyConfig } from '../config';
4
+ /**
5
+ * What a module reports about the capabilities it does not implement, as a consumer sees it
6
+ * through `withDefaults`. Meant to be asserted whole:
7
+ *
8
+ * ```ts
9
+ * await expect(capabilityReport(createApi(), context)).resolves.toEqual({
10
+ * unsupported: ['call', 'craftRawTransaction', 'getRewards', 'getValidators', 'register'],
11
+ * inconsistent: [],
12
+ * })
13
+ * ```
14
+ *
15
+ * One expectation then covers what a module's api test used to spell out method by method:
16
+ * that each capability is absent, that reaching it raises `"<name> is not supported"`, and
17
+ * that `supports()` agrees. `toEqual` makes it exhaustive — a capability dropped or newly
18
+ * implemented changes the list, so the test notices instead of silently still passing.
19
+ *
20
+ * It reads a module written either way: a `CoinModuleImpl` that omits its capabilities, or a
21
+ * value built by spreading `notSupportedApi()`. Both are "not implemented" as far as
22
+ * `supports()` is concerned, which is what this observes.
23
+ */
24
+ export type CapabilityReport = {
25
+ /** Capabilities the module does not implement, sorted, each verified to raise its error. */
26
+ unsupported: OptionalApiKey[];
27
+ /**
28
+ * Capabilities `supports()` calls absent but which did not raise `"<name> is not
29
+ * supported"` when reached — a missing backfill, or an error naming another method.
30
+ * Expected to be empty.
31
+ */
32
+ inconsistent: OptionalApiKey[];
33
+ };
34
+ /**
35
+ * Builds a {@link CapabilityReport} for a coin module.
36
+ *
37
+ * Only the capabilities `supports()` reports absent are actually invoked — a real
38
+ * implementation is never called, so this never reaches the network.
39
+ *
40
+ * `getAccountInfo` is excluded: per ADR-045 its default is the `{ type: 'none' }` sentinel
41
+ * rather than an error, so it is not a capability in the sense the rest of this list is.
42
+ */
43
+ export declare function capabilityReport<ConfigType extends CurrencyConfig, MemoType extends Memo, TxDataType extends TxData>(impl: CoinModuleImpl<ConfigType, MemoType, TxDataType>, context: Context<ConfigType>): Promise<CapabilityReport>;
44
+ //# sourceMappingURL=capabilities.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/test-utils/capabilities.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjE,OAAO,KAAK,EAAiB,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAQxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4FAA4F;IAC5F,WAAW,EAAE,cAAc,EAAE,CAAA;IAC7B;;;;OAIG;IACH,YAAY,EAAE,cAAc,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,SAAS,cAAc,EACjC,QAAQ,SAAS,IAAI,EACrB,UAAU,SAAS,MAAM,EAEzB,IAAI,EAAE,cAAc,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,EACtD,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAgC3B"}
@@ -0,0 +1,41 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { optionalApiKeys } from '../api/impl';
4
+ import { withDefaults } from '../api/withDefaults';
5
+ /** Narrows a member reached by name to a callable without asserting its type. */
6
+ const isMethod = (value) => typeof value === 'function';
7
+ /**
8
+ * Builds a {@link CapabilityReport} for a coin module.
9
+ *
10
+ * Only the capabilities `supports()` reports absent are actually invoked — a real
11
+ * implementation is never called, so this never reaches the network.
12
+ *
13
+ * `getAccountInfo` is excluded: per ADR-045 its default is the `{ type: 'none' }` sentinel
14
+ * rather than an error, so it is not a capability in the sense the rest of this list is.
15
+ */
16
+ export async function capabilityReport(impl, context) {
17
+ const resolved = withDefaults(impl);
18
+ const asRecord = resolved;
19
+ const unsupported = [];
20
+ const inconsistent = [];
21
+ for (const name of optionalApiKeys) {
22
+ if (name === 'getAccountInfo' || resolved.supports(name))
23
+ continue;
24
+ const method = asRecord[name];
25
+ if (!isMethod(method)) {
26
+ inconsistent.push(name);
27
+ continue;
28
+ }
29
+ // The framework default throws synchronously, but a module may still carry a stub written
30
+ // as an async function, which rejects instead. Both count as raising the error.
31
+ const raised = await Promise.resolve()
32
+ .then(() => method(context))
33
+ .then(() => undefined, (error) => (error instanceof Error ? error.message : String(error)));
34
+ if (raised === `${name} is not supported`)
35
+ unsupported.push(name);
36
+ else
37
+ inconsistent.push(name);
38
+ }
39
+ return { unsupported: unsupported.sort(), inconsistent: inconsistent.sort() };
40
+ }
41
+ //# sourceMappingURL=capabilities.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/test-utils/capabilities.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAKtC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,iFAAiF;AACjF,MAAM,QAAQ,GAAG,CAAC,KAAc,EAA4C,EAAE,CAC5E,OAAO,KAAK,KAAK,UAAU,CAAA;AAiC7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAKpC,IAAsD,EACtD,OAA4B;IAE5B,MAAM,QAAQ,GAEV,YAAY,CAAC,IAAI,CAAC,CAAA;IACtB,MAAM,QAAQ,GAA4B,QAAQ,CAAA;IAElD,MAAM,WAAW,GAAqB,EAAE,CAAA;IACxC,MAAM,YAAY,GAAqB,EAAE,CAAA;IAEzC,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,IAAI,IAAI,KAAK,gBAAgB,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAQ;QAElE,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACvB,SAAQ;QACV,CAAC;QAED,0FAA0F;QAC1F,gFAAgF;QAChF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE;aACnC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;aAC3B,IAAI,CACH,GAAG,EAAE,CAAC,SAAS,EACf,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC7E,CAAA;QAEH,IAAI,MAAM,KAAK,GAAG,IAAI,mBAAmB;YAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;YAC5D,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,YAAY,CAAC,IAAI,EAAE,EAAE,CAAA;AAC/E,CAAC"}
@@ -1,4 +1,5 @@
1
1
  import type { AssetInfo, Memo, MemoNotSupported, SendTransactionIntent, StakingOperation, StakingTransactionIntent, TxData, TxDataNotSupported } from '../api/index';
2
+ export * from './capabilities';
2
3
  type SendPartialBase = {
3
4
  type: string;
4
5
  } & Partial<Omit<SendTransactionIntent<MemoNotSupported, TxDataNotSupported>, 'intentType' | 'type'>>;
@@ -17,5 +18,4 @@ export declare function createStakingTransactionIntentMockData<MemoType extends
17
18
  export declare function createAssetInfoMockData(partial: {
18
19
  type: string;
19
20
  } & Partial<Omit<AssetInfo, 'type'>>): AssetInfo;
20
- export {};
21
21
  //# sourceMappingURL=helpers.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/test-utils/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,IAAI,EACJ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,MAAM,EACN,kBAAkB,EACnB,MAAM,cAAc,CAAA;AAErB,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAC/C,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,CACzF,CAAA;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,EAE9C,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GAChE,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;AAe9C,KAAK,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAAG,OAAO,CAC1E,IAAI,CACF,wBAAwB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,EAC9D,YAAY,GAAG,MAAM,GAAG,MAAM,CAC/B,CACF,CAAA;AAED,wBAAgB,sCAAsC,CACpD,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,EAE9C,OAAO,EAAE,kBAAkB,GAAG;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GACnE,wBAAwB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;AAiBjD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,GAC3D,SAAS,CAGX"}
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/test-utils/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,IAAI,EACJ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,MAAM,EACN,kBAAkB,EACnB,MAAM,cAAc,CAAA;AAErB,cAAc,gBAAgB,CAAA;AAE9B,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAC/C,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,CACzF,CAAA;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,EAE9C,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GAChE,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;AAe9C,KAAK,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAAG,OAAO,CAC1E,IAAI,CACF,wBAAwB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,EAC9D,YAAY,GAAG,MAAM,GAAG,MAAM,CAC/B,CACF,CAAA;AAED,wBAAgB,sCAAsC,CACpD,QAAQ,SAAS,IAAI,GAAG,gBAAgB,EACxC,UAAU,SAAS,MAAM,GAAG,kBAAkB,EAE9C,OAAO,EAAE,kBAAkB,GAAG;IAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GACnE,wBAAwB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;AAiBjD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,GAC3D,SAAS,CAGX"}
@@ -1,5 +1,6 @@
1
1
  // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
2
  // SPDX-License-Identifier: Apache-2.0
3
+ export * from './capabilities';
3
4
  export function createSendTransactionIntentMockData(partial) {
4
5
  const base = {
5
6
  intentType: 'transaction',
@@ -1 +1 @@
1
- {"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/test-utils/helpers.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAuBtC,MAAM,UAAU,mCAAmC,CACjD,OAAwB;IAExB,MAAM,IAAI,GAAgE;QACxE,UAAU,EAAE,aAAa;QACzB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,gBAAgB;QAC1C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,mBAAmB;QACnD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC3C,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AACzC,CAAC;AAeD,MAAM,UAAU,sCAAsC,CACpD,OAA2B;IAE3B,MAAM,IAAI,GAAmE;QAC3E,UAAU,EAAE,SAAS;QACrB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,gBAAgB;QAC1C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,mBAAmB;QACnD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,mBAAmB;KACtD,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAA4D;IAE5D,MAAM,KAAK,GAAc,EAAE,GAAG,OAAO,EAAE,CAAA;IACvC,OAAO,KAAK,CAAA;AACd,CAAC"}
1
+ {"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/test-utils/helpers.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAatC,cAAc,gBAAgB,CAAA;AAY9B,MAAM,UAAU,mCAAmC,CACjD,OAAwB;IAExB,MAAM,IAAI,GAAgE;QACxE,UAAU,EAAE,aAAa;QACzB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,gBAAgB;QAC1C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,mBAAmB;QACnD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC3C,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AACzC,CAAC;AAeD,MAAM,UAAU,sCAAsC,CACpD,OAA2B;IAE3B,MAAM,IAAI,GAAmE;QAC3E,UAAU,EAAE,SAAS;QACrB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,gBAAgB;QAC1C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,mBAAmB;QACnD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,mBAAmB;KACtD,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAA4D;IAE5D,MAAM,KAAK,GAAc,EAAE,GAAG,OAAO,EAAE,CAAA;IACvC,OAAO,KAAK,CAAA;AACd,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ledgerhq/coin-module-framework",
3
- "version": "8.1.0",
3
+ "version": "8.3.0",
4
4
  "description": "Ledger framework for Coin integration",
5
5
  "keywords": [
6
6
  "Ledger",
@@ -0,0 +1,83 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import type { CurrencyConfig } from '../config'
5
+ import type { Context } from '../config'
6
+ import type { CoinModuleImpl } from './index'
7
+ import type {
8
+ Balance,
9
+ BlockInfo,
10
+ CraftedTransaction,
11
+ FeeEstimation,
12
+ ListOperationsOptions,
13
+ TransactionIntent,
14
+ } from './types'
15
+ import { optionalApiKeys, requiredApiKeys } from './impl'
16
+
17
+ type Cfg = CurrencyConfig
18
+ type Ctx = Context<Cfg>
19
+
20
+ /**
21
+ * The shape a module carrying exactly `names` as methods must equal. Asserting against the
22
+ * whole object rather than attribute by attribute states both halves at once: the listed
23
+ * methods are present and callable, and nothing else is there.
24
+ */
25
+ const exactlyMethods = (names: readonly string[]): Record<string, unknown> =>
26
+ Object.fromEntries(names.map((name) => [name, expect.any(Function)]))
27
+
28
+ // Required set: lastBlock, getBalance, listOperations, craftTransaction,
29
+ // estimateFees, combine, broadcast, craftTransactionData.
30
+ const minimalModule: CoinModuleImpl<Cfg> = {
31
+ lastBlock: (_ctx: Ctx): Promise<BlockInfo> => Promise.reject(new Error('stub')),
32
+ getBalance: (_ctx: Ctx, _addr: string): Promise<Balance[]> => Promise.resolve([]),
33
+ listOperations: (_ctx: Ctx, _addr: string, _opts: ListOperationsOptions) =>
34
+ Promise.resolve({ items: [] }),
35
+ craftTransaction: (_ctx: Ctx, _intent: TransactionIntent): Promise<CraftedTransaction> =>
36
+ Promise.reject(new Error('stub')),
37
+ estimateFees: (_ctx: Ctx, _intent: TransactionIntent): Promise<FeeEstimation> =>
38
+ Promise.reject(new Error('stub')),
39
+ combine: (_ctx: Ctx, tx: string, _sig: string[]): string => tx,
40
+ broadcast: (_ctx: Ctx, _tx: string): Promise<string> => Promise.reject(new Error('stub')),
41
+ craftTransactionData: (_ctx: Ctx, _intent: TransactionIntent) => ({ type: 'none' }) as const,
42
+ }
43
+
44
+ describe('CoinModuleImpl', () => {
45
+ it('a module with Required methods only is a valid CoinModuleImpl', () => {
46
+ // Exactly the required methods, all of them callable, and no optional capability. The
47
+ // type enforces the required half at compile time; asserting it pins the set the
48
+ // authoring type demands, so a method leaving that set is a visible change.
49
+ expect(minimalModule).toEqual(exactlyMethods(requiredApiKeys))
50
+ })
51
+
52
+ it('getStakes may be present without getValidators (per-method staking optionality)', () => {
53
+ const partial: CoinModuleImpl<Cfg> = {
54
+ ...minimalModule,
55
+ getStakes: (_ctx: Ctx, _addr: string) => Promise.resolve({ items: [] }),
56
+ // getValidators intentionally absent
57
+ }
58
+ expect(partial).toEqual(exactlyMethods([...requiredApiKeys, 'getStakes']))
59
+ })
60
+
61
+ it('a fully-populated CoinModuleImpl exposes all CoinModuleApi optional methods', () => {
62
+ const full: CoinModuleImpl<Cfg> = {
63
+ ...minimalModule,
64
+ getBlock: (_ctx: Ctx, _h: number) => Promise.reject(new Error('stub')),
65
+ getBlockInfo: (_ctx: Ctx, _h: number) => Promise.reject(new Error('stub')),
66
+ getStakes: (_ctx: Ctx, _addr: string) => Promise.resolve({ items: [] }),
67
+ getRewards: (_ctx: Ctx, _addr: string) => Promise.resolve({ items: [] }),
68
+ getValidators: (_ctx: Ctx) => Promise.resolve({ items: [] }),
69
+ call: (_ctx: Ctx, _params: unknown) => Promise.resolve(null),
70
+ craftRawTransaction: (_ctx: Ctx, _tx: string, _s: string, _pk: string, _seq: bigint) =>
71
+ Promise.reject(new Error('stub')),
72
+ register: (_ctx: Ctx, _addr: string) => Promise.reject(new Error('stub')),
73
+ getNextSequence: (_ctx: Ctx, _addr: string) => Promise.resolve(0n),
74
+ validateIntent: (_ctx: Ctx, _intent: TransactionIntent, _balances: Balance[]) =>
75
+ Promise.reject(new Error('stub')),
76
+ validateAddress: (_ctx: Ctx, _addr: string, _params: object) => Promise.resolve(true),
77
+ getAccountInfo: (_ctx: Ctx, _addr: string) => Promise.resolve({ type: 'none' } as const),
78
+ }
79
+ // Runtime guard: all optional capability methods must be present when explicitly set,
80
+ // confirming that withDefaults can widen this impl to a full CoinModuleApi at runtime.
81
+ expect(full).toEqual(exactlyMethods([...requiredApiKeys, ...optionalApiKeys]))
82
+ })
83
+ })
@@ -0,0 +1,112 @@
1
+ // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import type { CurrencyConfig } from '../config'
5
+ import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from './types'
6
+
7
+ /**
8
+ * Methods a CoinModuleImpl author may omit when the chain does not support them.
9
+ * The framework's `withDefaults` fills the gaps before the consumer receives the
10
+ * object as a full {@link CoinModuleApi}.
11
+ *
12
+ * Block — getBlock, getBlockInfo (many chains throw "not supported")
13
+ * Staking — getStakes, getRewards, (à la carte; a module may ship getStakes
14
+ * getValidators without getValidators)
15
+ * SmartContract— call (optional escape-hatch)
16
+ * RawCrafting — craftRawTransaction (not all chains accept externally-built txs)
17
+ * Enrollment — register (optional indexer backend)
18
+ * Sequence — getNextSequence (some chains have no sequence/nonce concept)
19
+ * Validation — validateIntent, (some chains cannot fully validate intents
20
+ * validateAddress or addresses without a network round-trip)
21
+ * AccountInfo — getAccountInfo (chain-specific account metadata; absent means
22
+ * "nothing to report", not "unsupported")
23
+ */
24
+ export const optionalApiKeys = [
25
+ 'getBlock',
26
+ 'getBlockInfo',
27
+ 'getStakes',
28
+ 'getRewards',
29
+ 'getValidators',
30
+ 'call',
31
+ 'craftRawTransaction',
32
+ 'register',
33
+ 'getNextSequence',
34
+ 'validateIntent',
35
+ 'validateAddress',
36
+ 'getAccountInfo',
37
+ ] as const
38
+
39
+ /**
40
+ * A method name that a {@link CoinModuleImpl} author may omit.
41
+ *
42
+ * Derived from {@link optionalApiKeys} so the type and the runtime list used by
43
+ * `withDefaults` cannot drift apart.
44
+ */
45
+ export type OptionalApiKey = (typeof optionalApiKeys)[number]
46
+
47
+ /**
48
+ * Methods every {@link CoinModuleImpl} author must implement: the minimum a chain has to
49
+ * expose for the module to be usable at all. Complement of {@link optionalApiKeys}.
50
+ */
51
+ export const requiredApiKeys = [
52
+ 'lastBlock',
53
+ 'getBalance',
54
+ 'listOperations',
55
+ 'craftTransaction',
56
+ 'estimateFees',
57
+ 'combine',
58
+ 'broadcast',
59
+ 'craftTransactionData',
60
+ ] as const
61
+
62
+ /** A method name a {@link CoinModuleImpl} author must implement. */
63
+ export type RequiredApiKey = (typeof requiredApiKeys)[number]
64
+
65
+ /**
66
+ * Every method the {@link CoinModuleApi} contract declares.
67
+ *
68
+ * Wrappers iterate this list to instrument an API without reflecting over the object at
69
+ * runtime, so what they touch is fixed and readable rather than "whatever is a function".
70
+ * `listFeeOptions` is neither required nor omittable — the contract itself declares it
71
+ * optional and `withDefaults` does not backfill it — hence its place here and nowhere else.
72
+ */
73
+ export const apiMethodKeys = [...requiredApiKeys, ...optionalApiKeys, 'listFeeOptions'] as const
74
+
75
+ /** A method name declared by the {@link CoinModuleApi} contract. */
76
+ export type ApiMethodKey = (typeof apiMethodKeys)[number]
77
+
78
+ /**
79
+ * Compile-time guard: {@link apiMethodKeys} must name every method of the contract.
80
+ *
81
+ * Add a method to {@link CoinModuleApi} without listing it and `Unlisted` stops being
82
+ * `never`, which this alias rejects — so a wrapper can never silently skip a new method.
83
+ */
84
+ type AssertNever<T extends never> = T
85
+ export type ApiMethodKeysAreExhaustive = AssertNever<
86
+ Exclude<keyof CoinModuleApi<CurrencyConfig>, ApiMethodKey>
87
+ >
88
+
89
+ /**
90
+ * Authoring type for a coin-module implementation.
91
+ *
92
+ * Declare your module's `createApi` return type as `CoinModuleImpl<…>` instead of
93
+ * `CoinModuleApi<…>`. Any method in the optional set (see source) may be omitted;
94
+ * the framework's `withDefaults` wrapper will supply the "not supported" stub before
95
+ * handing the object to consumers.
96
+ *
97
+ * The consumer/full contract ({@link CoinModuleApi}) is structurally unchanged —
98
+ * it remains the required type at every call site.
99
+ *
100
+ * Generic parameters are identical to {@link CoinModuleApi}:
101
+ * - `ConfigType` — the coin-specific config shape
102
+ * - `MemoType` — memo variant (defaults to {@link MemoNotSupported})
103
+ * - `TxDataType` — transaction data variant (defaults to {@link TxDataNotSupported})
104
+ *
105
+ * @see CoinModuleApi — the full consumer/runtime contract (unchanged)
106
+ */
107
+ export type CoinModuleImpl<
108
+ ConfigType extends CurrencyConfig,
109
+ MemoType extends Memo = MemoNotSupported,
110
+ TxDataType extends TxData = TxDataNotSupported,
111
+ > = Omit<CoinModuleApi<ConfigType, MemoType, TxDataType>, OptionalApiKey> &
112
+ Partial<Pick<CoinModuleApi<ConfigType, MemoType, TxDataType>, OptionalApiKey>>
package/src/api/index.ts CHANGED
@@ -8,4 +8,8 @@
8
8
 
9
9
  export * from './errors'
10
10
  export * from './notSupported'
11
+ export * from './notSupportedApi'
11
12
  export * from './types'
13
+ export * from './impl'
14
+ export * from './withDefaults'
15
+ export * from './wrappers/index'
@@ -1,13 +1,43 @@
1
1
  // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
2
  // SPDX-License-Identifier: Apache-2.0
3
3
 
4
+ /**
5
+ * Marks a function as a framework-built "not supported" stub.
6
+ *
7
+ * `Symbol.for` (the global registry) is used deliberately: in a monorepo the framework
8
+ * may be present as more than one physical module instance, and a locally-scoped symbol
9
+ * would not match across them.
10
+ */
11
+ const NOT_SUPPORTED_STUB = Symbol.for('@ledgerhq/coin-module-framework:notSupportedStub')
12
+
4
13
  /**
5
14
  * Build a {@link CoinModuleApi} method stub that always throws a standardized
6
15
  * "not supported" error. Use it for optional API methods a module does not implement.
7
16
  *
17
+ * The returned function is tagged so the framework can tell it apart from a real
18
+ * implementation — see {@link isNotSupportedStub}.
19
+ *
8
20
  * @param name the API method name, used in the error message
9
21
  * @returns a function that throws `"<name> is not supported"` when invoked
10
22
  */
11
- export const notSupported = (name: string) => (): never => {
12
- throw new Error(`${name} is not supported`)
23
+ export const notSupported = (name: string) => {
24
+ const stub = (): never => {
25
+ throw new Error(`${name} is not supported`)
26
+ }
27
+ Object.defineProperty(stub, NOT_SUPPORTED_STUB, { value: true, enumerable: false })
28
+ return stub
29
+ }
30
+
31
+ /**
32
+ * Tells whether a value is a stub produced by {@link notSupported}, i.e. a placeholder
33
+ * rather than a real implementation.
34
+ *
35
+ * **Limitation** — only stubs built by {@link notSupported} are detectable. A module that
36
+ * hand-rolls `() => { throw new Error('x is not supported') }` inline is indistinguishable
37
+ * from a real implementation, because whether a function throws cannot be known without
38
+ * calling it. Modules should therefore either omit an unsupported method entirely (the
39
+ * migrated shape) or build its stub with {@link notSupported}.
40
+ */
41
+ export function isNotSupportedStub(value: unknown): boolean {
42
+ return typeof value === 'function' && NOT_SUPPORTED_STUB in value
13
43
  }
@@ -0,0 +1,67 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import type { Context, CurrencyConfig } from '../config'
5
+ import type { BlockInfo, ListOperationsOptions } from './types'
6
+ import { optionalApiKeys, requiredApiKeys } from './impl'
7
+ import { isNotSupportedStub } from './notSupported'
8
+ import { notSupportedApi } from './notSupportedApi'
9
+ import { withDefaults } from './withDefaults'
10
+
11
+ type Cfg = CurrencyConfig
12
+ type Ctx = Context<Cfg>
13
+
14
+ const ctx: Ctx = { config: () => Promise.reject(new Error('stub')), logger: () => undefined }
15
+
16
+ const isMethod = (value: unknown): value is (...args: unknown[]) => unknown =>
17
+ typeof value === 'function'
18
+
19
+ describe('notSupportedApi', () => {
20
+ it('stubs every capability with the standard error', () => {
21
+ const api: Record<string, unknown> = notSupportedApi<Cfg>()
22
+ for (const name of [...requiredApiKeys, ...optionalApiKeys]) {
23
+ if (name === 'getAccountInfo') continue
24
+ const method = api[name]
25
+ if (!isMethod(method)) throw new Error(`${name} is missing`)
26
+ expect(() => method()).toThrow(`${name} is not supported`)
27
+ }
28
+ })
29
+
30
+ it('answers the ADR-045 sentinel for getAccountInfo rather than throwing', async () => {
31
+ await expect(notSupportedApi<Cfg>().getAccountInfo?.(ctx, 'addr')).resolves.toEqual({
32
+ type: 'none',
33
+ })
34
+ })
35
+
36
+ it('leaves listFeeOptions absent, as withDefaults does', () => {
37
+ expect(notSupportedApi<Cfg>().listFeeOptions).toBe(undefined)
38
+ })
39
+
40
+ it('tags its stubs, so they are distinguishable from implementations', () => {
41
+ expect(isNotSupportedStub(notSupportedApi<Cfg>().getStakes)).toBe(true)
42
+ })
43
+
44
+ // The point of shipping this alongside the authoring type: a module may be written either
45
+ // way and still report the same capabilities through the resolver. Were the stubs not
46
+ // tagged, `supports` would call every spread stub an implementation and say the opposite
47
+ // of the truth.
48
+ it('reports the truth through withDefaults().supports()', () => {
49
+ const partialModule = {
50
+ ...notSupportedApi<Cfg>(),
51
+ lastBlock: (_ctx: Ctx): Promise<BlockInfo> => Promise.reject(new Error('stub')),
52
+ getBalance: (_ctx: Ctx, _addr: string) => Promise.resolve([]),
53
+ listOperations: (_ctx: Ctx, _addr: string, _opts: ListOperationsOptions) =>
54
+ Promise.resolve({ items: [] }),
55
+ getStakes: (_ctx: Ctx, _addr: string) => Promise.resolve({ items: [] }),
56
+ }
57
+ const api = withDefaults(partialModule)
58
+
59
+ expect(api.supports('getStakes')).toBe(true)
60
+ expect(api.supports('getValidators')).toBe(false)
61
+ expect(api.supports('getRewards')).toBe(false)
62
+ // Overridden methods keep the real implementation, not the stub.
63
+ expect(() => api.getBalance(ctx, 'addr')).not.toThrow()
64
+ // Everything left stubbed still raises the same error from the same name.
65
+ expect(() => api.broadcast(ctx, 'tx')).toThrow('broadcast is not supported')
66
+ })
67
+ })
@@ -0,0 +1,74 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import type { CurrencyConfig } from '../config'
5
+ import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from './types'
6
+ import { notSupported } from './notSupported'
7
+
8
+ /**
9
+ * A full {@link CoinModuleApi} whose every capability is a "not supported" stub.
10
+ *
11
+ * Spread it and override what the chain does support, for a module that would rather
12
+ * satisfy the complete contract directly than declare a `CoinModuleImpl` and be widened by
13
+ * `withDefaults`:
14
+ *
15
+ * ```ts
16
+ * export function createApi() {
17
+ * return {
18
+ * ...notSupportedApi<MyConfig>(),
19
+ * lastBlock, getBalance, listOperations,
20
+ * } satisfies CoinModuleApi<MyConfig>
21
+ * }
22
+ * ```
23
+ *
24
+ * The two styles interoperate rather than compete, because the stubs are tagged: a value
25
+ * built this way still tells the truth through `withDefaults`'s `supports()`, which treats a
26
+ * tagged stub as an omitted method rather than as an implementation. So a module may be
27
+ * authored either way, wrapped either way, and reports the same capabilities.
28
+ *
29
+ * It is also what a module can use when it does not implement everything the authoring type
30
+ * requires — a read-only module, or a chain with no crafting path. The contract is satisfied
31
+ * statically, and what the chain does not do stays visible at the definition site.
32
+ *
33
+ * `getAccountInfo` is the one method that does not throw: per ADR-045 a chain carrying no
34
+ * extra account metadata is an answer, not a missing capability, so it resolves the
35
+ * `{ type: 'none' }` sentinel — the same default `withDefaults` supplies. `listFeeOptions` is
36
+ * left absent, likewise matching `withDefaults`.
37
+ *
38
+ * The return type is the contract itself, so a method added to `CoinModuleApi` makes this
39
+ * fail to compile until it is covered here.
40
+ */
41
+ export function notSupportedApi<
42
+ ConfigType extends CurrencyConfig,
43
+ MemoType extends Memo = MemoNotSupported,
44
+ TxDataType extends TxData = TxDataNotSupported,
45
+ >(): CoinModuleApi<ConfigType, MemoType, TxDataType> {
46
+ return {
47
+ // Required by the authoring type — a module spreading this one must override them to
48
+ // be functional at all; they are stubbed here so the contract is satisfied statically.
49
+ lastBlock: notSupported('lastBlock'),
50
+ getBalance: notSupported('getBalance'),
51
+ listOperations: notSupported('listOperations'),
52
+ craftTransaction: notSupported('craftTransaction'),
53
+ estimateFees: notSupported('estimateFees'),
54
+ combine: notSupported('combine'),
55
+ broadcast: notSupported('broadcast'),
56
+ craftTransactionData: notSupported('craftTransactionData'),
57
+
58
+ // Optional capabilities.
59
+ getBlock: notSupported('getBlock'),
60
+ getBlockInfo: notSupported('getBlockInfo'),
61
+ getStakes: notSupported('getStakes'),
62
+ getRewards: notSupported('getRewards'),
63
+ getValidators: notSupported('getValidators'),
64
+ call: notSupported('call'),
65
+ craftRawTransaction: notSupported('craftRawTransaction'),
66
+ register: notSupported('register'),
67
+ getNextSequence: notSupported('getNextSequence'),
68
+ validateIntent: notSupported('validateIntent'),
69
+ validateAddress: notSupported('validateAddress'),
70
+
71
+ // Not a capability: absent metadata is an answer (ADR-045).
72
+ getAccountInfo: () => Promise.resolve({ type: 'none' }),
73
+ }
74
+ }