@ledgerhq/coin-module-framework 8.0.0 → 8.2.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.
- package/CHANGELOG.md +106 -0
- package/lib/api/impl.d.ts +74 -0
- package/lib/api/impl.d.ts.map +1 -0
- package/lib/api/impl.js +60 -0
- package/lib/api/impl.js.map +1 -0
- package/lib/api/index.d.ts +4 -0
- package/lib/api/index.d.ts.map +1 -1
- package/lib/api/index.js +4 -0
- package/lib/api/index.js.map +1 -1
- package/lib/api/notSupported.d.ts +14 -0
- package/lib/api/notSupported.d.ts.map +1 -1
- package/lib/api/notSupported.js +31 -2
- package/lib/api/notSupported.js.map +1 -1
- package/lib/api/notSupportedApi.d.ts +37 -0
- package/lib/api/notSupportedApi.d.ts.map +1 -0
- package/lib/api/notSupportedApi.js +68 -0
- package/lib/api/notSupportedApi.js.map +1 -0
- package/lib/api/types.d.ts +4 -0
- package/lib/api/types.d.ts.map +1 -1
- package/lib/api/withDefaults.d.ts +31 -0
- package/lib/api/withDefaults.d.ts.map +1 -0
- package/lib/api/withDefaults.js +57 -0
- package/lib/api/withDefaults.js.map +1 -0
- package/lib/api/wrappers/index.d.ts +17 -0
- package/lib/api/wrappers/index.d.ts.map +1 -0
- package/lib/api/wrappers/index.js +35 -0
- package/lib/api/wrappers/index.js.map +1 -0
- package/lib/api/wrappers/instrumenter.d.ts +27 -0
- package/lib/api/wrappers/instrumenter.d.ts.map +1 -0
- package/lib/api/wrappers/instrumenter.js +46 -0
- package/lib/api/wrappers/instrumenter.js.map +1 -0
- package/lib/api/wrappers/withLogging.d.ts +11 -0
- package/lib/api/wrappers/withLogging.d.ts.map +1 -0
- package/lib/api/wrappers/withLogging.js +40 -0
- package/lib/api/wrappers/withLogging.js.map +1 -0
- package/lib/api/wrappers/withTracing.d.ts +18 -0
- package/lib/api/wrappers/withTracing.d.ts.map +1 -0
- package/lib/api/wrappers/withTracing.js +40 -0
- package/lib/api/wrappers/withTracing.js.map +1 -0
- package/lib/test-utils/capabilities.d.ts +44 -0
- package/lib/test-utils/capabilities.d.ts.map +1 -0
- package/lib/test-utils/capabilities.js +44 -0
- package/lib/test-utils/capabilities.js.map +1 -0
- package/lib/test-utils/helpers.d.ts +1 -1
- package/lib/test-utils/helpers.d.ts.map +1 -1
- package/lib/test-utils/helpers.js +15 -0
- package/lib/test-utils/helpers.js.map +1 -1
- package/lib-es/api/impl.d.ts +74 -0
- package/lib-es/api/impl.d.ts.map +1 -0
- package/lib-es/api/impl.js +57 -0
- package/lib-es/api/impl.js.map +1 -0
- package/lib-es/api/index.d.ts +4 -0
- package/lib-es/api/index.d.ts.map +1 -1
- package/lib-es/api/index.js +4 -0
- package/lib-es/api/index.js.map +1 -1
- package/lib-es/api/notSupported.d.ts +14 -0
- package/lib-es/api/notSupported.d.ts.map +1 -1
- package/lib-es/api/notSupported.js +30 -2
- package/lib-es/api/notSupported.js.map +1 -1
- package/lib-es/api/notSupportedApi.d.ts +37 -0
- package/lib-es/api/notSupportedApi.d.ts.map +1 -0
- package/lib-es/api/notSupportedApi.js +65 -0
- package/lib-es/api/notSupportedApi.js.map +1 -0
- package/lib-es/api/types.d.ts +4 -0
- package/lib-es/api/types.d.ts.map +1 -1
- package/lib-es/api/withDefaults.d.ts +31 -0
- package/lib-es/api/withDefaults.d.ts.map +1 -0
- package/lib-es/api/withDefaults.js +54 -0
- package/lib-es/api/withDefaults.js.map +1 -0
- package/lib-es/api/wrappers/index.d.ts +17 -0
- package/lib-es/api/wrappers/index.d.ts.map +1 -0
- package/lib-es/api/wrappers/index.js +19 -0
- package/lib-es/api/wrappers/index.js.map +1 -0
- package/lib-es/api/wrappers/instrumenter.d.ts +27 -0
- package/lib-es/api/wrappers/instrumenter.d.ts.map +1 -0
- package/lib-es/api/wrappers/instrumenter.js +43 -0
- package/lib-es/api/wrappers/instrumenter.js.map +1 -0
- package/lib-es/api/wrappers/withLogging.d.ts +11 -0
- package/lib-es/api/wrappers/withLogging.d.ts.map +1 -0
- package/lib-es/api/wrappers/withLogging.js +37 -0
- package/lib-es/api/wrappers/withLogging.js.map +1 -0
- package/lib-es/api/wrappers/withTracing.d.ts +18 -0
- package/lib-es/api/wrappers/withTracing.d.ts.map +1 -0
- package/lib-es/api/wrappers/withTracing.js +37 -0
- package/lib-es/api/wrappers/withTracing.js.map +1 -0
- package/lib-es/test-utils/capabilities.d.ts +44 -0
- package/lib-es/test-utils/capabilities.d.ts.map +1 -0
- package/lib-es/test-utils/capabilities.js +41 -0
- package/lib-es/test-utils/capabilities.js.map +1 -0
- package/lib-es/test-utils/helpers.d.ts +1 -1
- package/lib-es/test-utils/helpers.d.ts.map +1 -1
- package/lib-es/test-utils/helpers.js +1 -0
- package/lib-es/test-utils/helpers.js.map +1 -1
- package/package.json +1 -1
- package/src/api/impl.test.ts +83 -0
- package/src/api/impl.ts +112 -0
- package/src/api/index.ts +4 -0
- package/src/api/notSupported.ts +32 -2
- package/src/api/notSupportedApi.test.ts +67 -0
- package/src/api/notSupportedApi.ts +74 -0
- package/src/api/types.ts +4 -0
- package/src/api/withDefaults.test.ts +190 -0
- package/src/api/withDefaults.ts +87 -0
- package/src/api/wrappers/index.ts +20 -0
- package/src/api/wrappers/instrumenter.test.ts +123 -0
- package/src/api/wrappers/instrumenter.ts +58 -0
- package/src/api/wrappers/withLogging.test.ts +137 -0
- package/src/api/wrappers/withLogging.ts +47 -0
- package/src/api/wrappers/withTracing.test.ts +125 -0
- package/src/api/wrappers/withTracing.ts +56 -0
- package/src/test-utils/capabilities.test.ts +108 -0
- package/src/test-utils/capabilities.ts +93 -0
- package/src/test-utils/helpers.ts +2 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: © 2024 LEDGER SAS
|
|
2
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
import { instrumentApi } from './instrumenter';
|
|
4
|
+
/**
|
|
5
|
+
* Wraps a {@link CoinModuleApi} to emit log entries via the per-call {@link Context}'s
|
|
6
|
+
* logger before and after each method invocation, including on error.
|
|
7
|
+
*
|
|
8
|
+
* The Context is forwarded unchanged to the underlying method.
|
|
9
|
+
* Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
|
|
10
|
+
*/
|
|
11
|
+
export function withLogging(api) {
|
|
12
|
+
return instrumentApi(api, (name, fn, args) => {
|
|
13
|
+
// oxlint-disable-next-line consistent-type-assertions -- args[0] is always Context<C> per CoinModuleApi contract; unknown cast needed to access logger
|
|
14
|
+
const logger = args[0]?.logger;
|
|
15
|
+
logger?.(`[coin-module] ${name}: call`);
|
|
16
|
+
let result;
|
|
17
|
+
try {
|
|
18
|
+
result = fn(...args);
|
|
19
|
+
}
|
|
20
|
+
catch (e) {
|
|
21
|
+
logger?.(`[coin-module] ${name}: error`, e);
|
|
22
|
+
throw e;
|
|
23
|
+
}
|
|
24
|
+
if (result instanceof Promise) {
|
|
25
|
+
return result.then((v) => {
|
|
26
|
+
logger?.(`[coin-module] ${name}: ok`);
|
|
27
|
+
return v;
|
|
28
|
+
}, (e) => {
|
|
29
|
+
logger?.(`[coin-module] ${name}: error`, e);
|
|
30
|
+
throw e;
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
logger?.(`[coin-module] ${name}: ok`);
|
|
34
|
+
return result;
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=withLogging.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"withLogging.js","sourceRoot":"","sources":["../../../src/api/wrappers/withLogging.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAItC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAKzB,GAAmC;IACnC,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QAC3C,uJAAuJ;QACvJ,MAAM,MAAM,GAAI,IAAI,CAAC,CAAC,CAA4B,EAAE,MAAM,CAAA;QAC1D,MAAM,EAAE,CAAC,iBAAiB,IAAI,QAAQ,CAAC,CAAA;QACvC,IAAI,MAAe,CAAA;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,EAAE,CAAC,iBAAiB,IAAI,SAAS,EAAE,CAAC,CAAC,CAAA;YAC3C,MAAM,CAAC,CAAA;QACT,CAAC;QACD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE;gBACJ,MAAM,EAAE,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAA;gBACrC,OAAO,CAAC,CAAA;YACV,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;gBACJ,MAAM,EAAE,CAAC,iBAAiB,IAAI,SAAS,EAAE,CAAC,CAAC,CAAA;gBAC3C,MAAM,CAAC,CAAA;YACT,CAAC,CACF,CAAA;QACH,CAAC;QACD,MAAM,EAAE,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAA;QACrC,OAAO,MAAM,CAAA;IACf,CAAC,CAAC,CAAA;AACJ,CAAC"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { CurrencyConfig } from '../../config';
|
|
2
|
+
import type { CoinModuleApi, Memo, MemoNotSupported, TxData, TxDataNotSupported } from '../types';
|
|
3
|
+
export interface Span {
|
|
4
|
+
end(): void;
|
|
5
|
+
setError(error: unknown): void;
|
|
6
|
+
}
|
|
7
|
+
export interface Tracer {
|
|
8
|
+
startSpan(name: string): Span;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Wraps a {@link CoinModuleApi} to open a tracing span around each method invocation.
|
|
12
|
+
*
|
|
13
|
+
* The span is ended on success, or after `setError` on throw.
|
|
14
|
+
* The Context is forwarded unchanged to the underlying method.
|
|
15
|
+
* Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
|
|
16
|
+
*/
|
|
17
|
+
export declare function withTracing<C extends CurrencyConfig, M extends Memo = MemoNotSupported, T extends TxData = TxDataNotSupported, Extra extends object = Record<never, never>>(api: CoinModuleApi<C, M, T> & Extra, tracer: Tracer): CoinModuleApi<C, M, T> & Extra;
|
|
18
|
+
//# sourceMappingURL=withTracing.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"withTracing.d.ts","sourceRoot":"","sources":["../../../src/api/wrappers/withTracing.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGjG,MAAM,WAAW,IAAI;IACnB,GAAG,IAAI,IAAI,CAAA;IACX,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,MAAM;IACrB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,CAAC,SAAS,cAAc,EACxB,CAAC,SAAS,IAAI,GAAG,gBAAgB,EACjC,CAAC,SAAS,MAAM,GAAG,kBAAkB,EACrC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC3C,GAAG,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CA2BrF"}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: © 2024 LEDGER SAS
|
|
2
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
import { instrumentApi } from './instrumenter';
|
|
4
|
+
/**
|
|
5
|
+
* Wraps a {@link CoinModuleApi} to open a tracing span around each method invocation.
|
|
6
|
+
*
|
|
7
|
+
* The span is ended on success, or after `setError` on throw.
|
|
8
|
+
* The Context is forwarded unchanged to the underlying method.
|
|
9
|
+
* Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
|
|
10
|
+
*/
|
|
11
|
+
export function withTracing(api, tracer) {
|
|
12
|
+
return instrumentApi(api, (name, fn, args) => {
|
|
13
|
+
const span = tracer.startSpan(name);
|
|
14
|
+
let result;
|
|
15
|
+
try {
|
|
16
|
+
result = fn(...args);
|
|
17
|
+
}
|
|
18
|
+
catch (e) {
|
|
19
|
+
span.setError(e);
|
|
20
|
+
span.end();
|
|
21
|
+
throw e;
|
|
22
|
+
}
|
|
23
|
+
if (result instanceof Promise) {
|
|
24
|
+
return result.then((v) => {
|
|
25
|
+
span.end();
|
|
26
|
+
return v;
|
|
27
|
+
}, (e) => {
|
|
28
|
+
span.setError(e);
|
|
29
|
+
span.end();
|
|
30
|
+
throw e;
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
span.end();
|
|
34
|
+
return result;
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=withTracing.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"withTracing.js","sourceRoot":"","sources":["../../../src/api/wrappers/withTracing.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;AAItC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAW9C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAKzB,GAAmC,EAAE,MAAc;IACnD,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,MAAe,CAAA;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAChB,IAAI,CAAC,GAAG,EAAE,CAAA;YACV,MAAM,CAAC,CAAA;QACT,CAAC;QACD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE;gBACJ,IAAI,CAAC,GAAG,EAAE,CAAA;gBACV,OAAO,CAAC,CAAA;YACV,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;gBACJ,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;gBAChB,IAAI,CAAC,GAAG,EAAE,CAAA;gBACV,MAAM,CAAC,CAAA;YACT,CAAC,CACF,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAA;QACV,OAAO,MAAM,CAAA;IACf,CAAC,CAAC,CAAA;AACJ,CAAC"}
|
|
@@ -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 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/test-utils/helpers.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sCAAsC;
|
|
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
|
@@ -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
|
+
})
|
package/src/api/impl.ts
ADDED
|
@@ -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
package/src/api/notSupported.ts
CHANGED
|
@@ -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) =>
|
|
12
|
-
|
|
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
|
+
}
|