@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.
- package/CHANGELOG.md +104 -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/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/errors.d.ts +9 -0
- package/lib/errors.d.ts.map +1 -1
- package/lib/errors.js +17 -1
- package/lib/errors.js.map +1 -1
- 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/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/errors.d.ts +9 -0
- package/lib-es/errors.d.ts.map +1 -1
- package/lib-es/errors.js +14 -0
- package/lib-es/errors.js.map +1 -1
- 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/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/errors.ts +17 -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,125 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: © 2024 LEDGER SAS
|
|
2
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import type { CurrencyConfig, Context } from '../../config'
|
|
5
|
+
import type { CoinModuleImpl } from '../impl'
|
|
6
|
+
import type { BlockInfo, ListOperationsOptions, TransactionIntent } from '../types'
|
|
7
|
+
import type { Tracer, Span } from './withTracing'
|
|
8
|
+
import { withDefaults } from '../withDefaults'
|
|
9
|
+
import { withLogging } from './withLogging'
|
|
10
|
+
import { withTracing } from './withTracing'
|
|
11
|
+
|
|
12
|
+
type Cfg = CurrencyConfig
|
|
13
|
+
type Ctx = Context<Cfg>
|
|
14
|
+
|
|
15
|
+
const block: BlockInfo = { height: 1, hash: '0xabc', time: new Date(0) }
|
|
16
|
+
|
|
17
|
+
const ctx: Ctx = {
|
|
18
|
+
config: () => Promise.reject(new Error('stub')),
|
|
19
|
+
logger: () => undefined,
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const minimalModule: CoinModuleImpl<Cfg> = {
|
|
23
|
+
lastBlock: (_ctx: Ctx): Promise<BlockInfo> => Promise.reject(new Error('stub')),
|
|
24
|
+
getBalance: (_ctx: Ctx, _addr: string) => Promise.resolve([]),
|
|
25
|
+
listOperations: (_ctx: Ctx, _addr: string, _opts: ListOperationsOptions) =>
|
|
26
|
+
Promise.resolve({ items: [] }),
|
|
27
|
+
craftTransaction: (_ctx: Ctx, _intent: TransactionIntent) => Promise.reject(new Error('stub')),
|
|
28
|
+
estimateFees: (_ctx: Ctx, _intent: TransactionIntent) => Promise.reject(new Error('stub')),
|
|
29
|
+
combine: (_ctx: Ctx, tx: string, _sig: string[]): string => tx,
|
|
30
|
+
broadcast: (_ctx: Ctx, _tx: string) => Promise.reject(new Error('stub')),
|
|
31
|
+
craftTransactionData: (_ctx: Ctx, _intent: TransactionIntent) => ({ type: 'none' }) as const,
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function makeSpan(): { mock: Span; end: jest.Mock; setError: jest.Mock } {
|
|
35
|
+
const end = jest.fn()
|
|
36
|
+
const setError = jest.fn()
|
|
37
|
+
return { mock: { end, setError }, end, setError }
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function makeTracer(span: Span): { mock: Tracer; startSpan: jest.Mock } {
|
|
41
|
+
const startSpan = jest.fn().mockReturnValue(span)
|
|
42
|
+
return { mock: { startSpan }, startSpan }
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
describe('withTracing', () => {
|
|
46
|
+
it('calls startSpan with the method name', async () => {
|
|
47
|
+
const { mock: span } = makeSpan()
|
|
48
|
+
const { mock: tracer, startSpan } = makeTracer(span)
|
|
49
|
+
const impl: CoinModuleImpl<Cfg> = {
|
|
50
|
+
...minimalModule,
|
|
51
|
+
lastBlock: (_c: Ctx) => Promise.resolve(block),
|
|
52
|
+
}
|
|
53
|
+
await withTracing(withDefaults(impl), tracer).lastBlock(ctx)
|
|
54
|
+
expect(startSpan).toHaveBeenCalledWith('lastBlock')
|
|
55
|
+
})
|
|
56
|
+
|
|
57
|
+
it('calls span.end() after a successful async method', async () => {
|
|
58
|
+
const { mock: span, end } = makeSpan()
|
|
59
|
+
const { mock: tracer } = makeTracer(span)
|
|
60
|
+
const impl: CoinModuleImpl<Cfg> = {
|
|
61
|
+
...minimalModule,
|
|
62
|
+
lastBlock: (_c: Ctx) => Promise.resolve(block),
|
|
63
|
+
}
|
|
64
|
+
await withTracing(withDefaults(impl), tracer).lastBlock(ctx)
|
|
65
|
+
expect(end).toHaveBeenCalledTimes(1)
|
|
66
|
+
})
|
|
67
|
+
|
|
68
|
+
it('calls span.setError and span.end then re-throws on a rejected async method', async () => {
|
|
69
|
+
const error = new Error('net-fail')
|
|
70
|
+
const { mock: span, end, setError } = makeSpan()
|
|
71
|
+
const { mock: tracer } = makeTracer(span)
|
|
72
|
+
const impl: CoinModuleImpl<Cfg> = {
|
|
73
|
+
...minimalModule,
|
|
74
|
+
lastBlock: (_c: Ctx) => Promise.reject(error),
|
|
75
|
+
}
|
|
76
|
+
await expect(withTracing(withDefaults(impl), tracer).lastBlock(ctx)).rejects.toThrow(error)
|
|
77
|
+
expect(setError).toHaveBeenCalledWith(error)
|
|
78
|
+
expect(end).toHaveBeenCalledTimes(1)
|
|
79
|
+
})
|
|
80
|
+
|
|
81
|
+
it('calls span.end and returns result for a successful synchronous method', () => {
|
|
82
|
+
const { mock: span, end } = makeSpan()
|
|
83
|
+
const { mock: tracer } = makeTracer(span)
|
|
84
|
+
const result = withTracing(withDefaults(minimalModule), tracer).combine(ctx, 'tx', [])
|
|
85
|
+
expect(result).toBe('tx')
|
|
86
|
+
expect(end).toHaveBeenCalledTimes(1)
|
|
87
|
+
})
|
|
88
|
+
|
|
89
|
+
it('calls span.setError and span.end then re-throws on a synchronous throw', () => {
|
|
90
|
+
const error = new Error('sync-fail')
|
|
91
|
+
const { mock: span, end, setError } = makeSpan()
|
|
92
|
+
const { mock: tracer } = makeTracer(span)
|
|
93
|
+
const impl: CoinModuleImpl<Cfg> = {
|
|
94
|
+
...minimalModule,
|
|
95
|
+
combine: (_c: Ctx, _tx: string, _sig: string[]): string => {
|
|
96
|
+
throw error
|
|
97
|
+
},
|
|
98
|
+
}
|
|
99
|
+
expect(() => withTracing(withDefaults(impl), tracer).combine(ctx, 'tx', [])).toThrow(error)
|
|
100
|
+
expect(setError).toHaveBeenCalledWith(error)
|
|
101
|
+
expect(end).toHaveBeenCalledTimes(1)
|
|
102
|
+
})
|
|
103
|
+
|
|
104
|
+
it('stacks logging and tracing when composed withLogging(withTracing(api, tracer))', async () => {
|
|
105
|
+
const logger = jest.fn()
|
|
106
|
+
const logCtx: Ctx = { ...ctx, logger }
|
|
107
|
+
const { mock: span, end } = makeSpan()
|
|
108
|
+
const { mock: tracer, startSpan } = makeTracer(span)
|
|
109
|
+
const impl: CoinModuleImpl<Cfg> = {
|
|
110
|
+
...minimalModule,
|
|
111
|
+
lastBlock: (_c: Ctx) => Promise.resolve(block),
|
|
112
|
+
}
|
|
113
|
+
const composed = withLogging(withTracing(withDefaults(impl), tracer))
|
|
114
|
+
await composed.lastBlock(logCtx)
|
|
115
|
+
// Logging layer fired
|
|
116
|
+
expect(logger).toHaveBeenCalledWith('[coin-module] lastBlock: call')
|
|
117
|
+
expect(logger).toHaveBeenCalledWith('[coin-module] lastBlock: ok')
|
|
118
|
+
// Tracing layer fired
|
|
119
|
+
expect(startSpan).toHaveBeenCalledWith('lastBlock')
|
|
120
|
+
expect(end).toHaveBeenCalledTimes(1)
|
|
121
|
+
// The underlying method's return value is preserved through both layers
|
|
122
|
+
const result = await composed.lastBlock(logCtx)
|
|
123
|
+
expect(result).not.toBe(undefined)
|
|
124
|
+
})
|
|
125
|
+
})
|
|
@@ -0,0 +1,56 @@
|
|
|
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
|
+
import { instrumentApi } from './instrumenter'
|
|
7
|
+
|
|
8
|
+
export interface Span {
|
|
9
|
+
end(): void
|
|
10
|
+
setError(error: unknown): void
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export interface Tracer {
|
|
14
|
+
startSpan(name: string): Span
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Wraps a {@link CoinModuleApi} to open a tracing span around each method invocation.
|
|
19
|
+
*
|
|
20
|
+
* The span is ended on success, or after `setError` on throw.
|
|
21
|
+
* The Context is forwarded unchanged to the underlying method.
|
|
22
|
+
* Handles both synchronous methods (e.g. `combine`) and async methods uniformly.
|
|
23
|
+
*/
|
|
24
|
+
export function withTracing<
|
|
25
|
+
C extends CurrencyConfig,
|
|
26
|
+
M extends Memo = MemoNotSupported,
|
|
27
|
+
T extends TxData = TxDataNotSupported,
|
|
28
|
+
Extra extends object = Record<never, never>,
|
|
29
|
+
>(api: CoinModuleApi<C, M, T> & Extra, tracer: Tracer): CoinModuleApi<C, M, T> & Extra {
|
|
30
|
+
return instrumentApi(api, (name, fn, args) => {
|
|
31
|
+
const span = tracer.startSpan(name)
|
|
32
|
+
let result: unknown
|
|
33
|
+
try {
|
|
34
|
+
result = fn(...args)
|
|
35
|
+
} catch (e) {
|
|
36
|
+
span.setError(e)
|
|
37
|
+
span.end()
|
|
38
|
+
throw e
|
|
39
|
+
}
|
|
40
|
+
if (result instanceof Promise) {
|
|
41
|
+
return result.then(
|
|
42
|
+
(v) => {
|
|
43
|
+
span.end()
|
|
44
|
+
return v
|
|
45
|
+
},
|
|
46
|
+
(e) => {
|
|
47
|
+
span.setError(e)
|
|
48
|
+
span.end()
|
|
49
|
+
throw e
|
|
50
|
+
}
|
|
51
|
+
)
|
|
52
|
+
}
|
|
53
|
+
span.end()
|
|
54
|
+
return result
|
|
55
|
+
})
|
|
56
|
+
}
|
package/src/errors.ts
CHANGED
|
@@ -108,3 +108,20 @@ export class NotEnoughBalanceInParentAccount extends Error {
|
|
|
108
108
|
super(message || 'NotEnoughBalanceInParentAccount')
|
|
109
109
|
}
|
|
110
110
|
}
|
|
111
|
+
|
|
112
|
+
export class UnknownError extends Error {
|
|
113
|
+
override name = 'UnknownError'
|
|
114
|
+
cause: unknown
|
|
115
|
+
|
|
116
|
+
constructor(message?: string, cause?: unknown) {
|
|
117
|
+
super(message || 'UnknownError')
|
|
118
|
+
this.cause = cause
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export class BlockNotFoundError extends Error {
|
|
123
|
+
override name = 'BlockNotFoundError'
|
|
124
|
+
constructor(message?: string) {
|
|
125
|
+
super(message || 'BlockNotFoundError')
|
|
126
|
+
}
|
|
127
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: © 2026 LEDGER SAS
|
|
2
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import type { CoinModuleImpl } from '../api/impl'
|
|
5
|
+
import type { BlockInfo, ListOperationsOptions, TransactionIntent } from '../api/types'
|
|
6
|
+
import type { Context, CurrencyConfig } from '../config'
|
|
7
|
+
import { notSupported } from '../api/notSupported'
|
|
8
|
+
import { notSupportedApi } from '../api/notSupportedApi'
|
|
9
|
+
import { capabilityReport } from './capabilities'
|
|
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 minimalModule: CoinModuleImpl<Cfg> = {
|
|
17
|
+
lastBlock: (_ctx: Ctx): Promise<BlockInfo> => Promise.reject(new Error('stub')),
|
|
18
|
+
getBalance: (_ctx: Ctx, _addr: string) => Promise.resolve([]),
|
|
19
|
+
listOperations: (_ctx: Ctx, _addr: string, _opts: ListOperationsOptions) =>
|
|
20
|
+
Promise.resolve({ items: [] }),
|
|
21
|
+
craftTransaction: (_ctx: Ctx, _intent: TransactionIntent) => Promise.reject(new Error('stub')),
|
|
22
|
+
estimateFees: (_ctx: Ctx, _intent: TransactionIntent) => Promise.reject(new Error('stub')),
|
|
23
|
+
combine: (_ctx: Ctx, tx: string, _sig: string[]): string => tx,
|
|
24
|
+
broadcast: (_ctx: Ctx, _tx: string) => Promise.reject(new Error('stub')),
|
|
25
|
+
craftTransactionData: (_ctx: Ctx, _intent: TransactionIntent) => ({ type: 'none' }) as const,
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// Every optional capability but getAccountInfo, which ADR-045 answers with a sentinel rather
|
|
29
|
+
// than an error and which the report therefore leaves out.
|
|
30
|
+
const ALL_CAPABILITIES = [
|
|
31
|
+
'call',
|
|
32
|
+
'craftRawTransaction',
|
|
33
|
+
'getBlock',
|
|
34
|
+
'getBlockInfo',
|
|
35
|
+
'getNextSequence',
|
|
36
|
+
'getRewards',
|
|
37
|
+
'getStakes',
|
|
38
|
+
'getValidators',
|
|
39
|
+
'register',
|
|
40
|
+
'validateAddress',
|
|
41
|
+
'validateIntent',
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
describe('capabilityReport', () => {
|
|
45
|
+
it('lists every capability a minimal module leaves out', async () => {
|
|
46
|
+
await expect(capabilityReport(minimalModule, ctx)).resolves.toEqual({
|
|
47
|
+
unsupported: ALL_CAPABILITIES,
|
|
48
|
+
inconsistent: [],
|
|
49
|
+
})
|
|
50
|
+
})
|
|
51
|
+
|
|
52
|
+
it('drops a capability from the list once the module implements it', async () => {
|
|
53
|
+
const withStaking: CoinModuleImpl<Cfg> = {
|
|
54
|
+
...minimalModule,
|
|
55
|
+
getStakes: (_ctx: Ctx, _addr: string) => Promise.resolve({ items: [] }),
|
|
56
|
+
}
|
|
57
|
+
const report = await capabilityReport(withStaking, ctx)
|
|
58
|
+
expect(report.unsupported).not.toContain('getStakes')
|
|
59
|
+
expect(report.unsupported).toContain('getRewards')
|
|
60
|
+
expect(report.inconsistent).toEqual([])
|
|
61
|
+
})
|
|
62
|
+
|
|
63
|
+
// A module built by spreading `notSupportedApi()` carries a stub for everything, where a
|
|
64
|
+
// `CoinModuleImpl` omits it. The report reads both the same way, since it observes what a
|
|
65
|
+
// consumer gets rather than the shape of the authored object.
|
|
66
|
+
it('reads a module built by spreading notSupportedApi the same way', async () => {
|
|
67
|
+
const spread = {
|
|
68
|
+
...notSupportedApi<Cfg>(),
|
|
69
|
+
lastBlock: minimalModule.lastBlock,
|
|
70
|
+
getBalance: minimalModule.getBalance,
|
|
71
|
+
getStakes: (_ctx: Ctx, _addr: string) => Promise.resolve({ items: [] }),
|
|
72
|
+
}
|
|
73
|
+
const report = await capabilityReport(spread, ctx)
|
|
74
|
+
expect(report.unsupported).not.toContain('getStakes')
|
|
75
|
+
expect(report.unsupported).toContain('getValidators')
|
|
76
|
+
expect(report.inconsistent).toEqual([])
|
|
77
|
+
})
|
|
78
|
+
|
|
79
|
+
it('never invokes an implemented capability', async () => {
|
|
80
|
+
const network = jest.fn(() => Promise.reject(new Error('should not be reached')))
|
|
81
|
+
await capabilityReport({ ...minimalModule, getStakes: network }, ctx)
|
|
82
|
+
expect(network).not.toHaveBeenCalled()
|
|
83
|
+
})
|
|
84
|
+
|
|
85
|
+
it('counts a stub that rejects asynchronously as raising the error', async () => {
|
|
86
|
+
const asyncStub = {
|
|
87
|
+
...minimalModule,
|
|
88
|
+
getRewards: (_ctx: Ctx, _addr: string) =>
|
|
89
|
+
Promise.reject(new Error('getRewards is not supported')),
|
|
90
|
+
}
|
|
91
|
+
const report = await capabilityReport(asyncStub, ctx)
|
|
92
|
+
// The module fills the slot, so `supports()` calls it implemented and the report skips it —
|
|
93
|
+
// the tagged-stub check is what tells a placeholder apart, and an inline throw cannot be
|
|
94
|
+
// told apart from an implementation.
|
|
95
|
+
expect(report.unsupported).not.toContain('getRewards')
|
|
96
|
+
expect(report.inconsistent).toEqual([])
|
|
97
|
+
})
|
|
98
|
+
|
|
99
|
+
it('re-labels a tagged stub whose error names another method', async () => {
|
|
100
|
+
const mislabelled = { ...minimalModule, getValidators: notSupported('getStakes') }
|
|
101
|
+
const report = await capabilityReport(mislabelled, ctx)
|
|
102
|
+
// A tagged stub counts as omitted, so `withDefaults` replaces it with its own — which names
|
|
103
|
+
// the method it stands for. The mislabelling `coin-canton` shipped cannot survive the
|
|
104
|
+
// resolver, and `inconsistent` stays empty: it only fills if a backfill goes missing.
|
|
105
|
+
expect(report.unsupported).toContain('getValidators')
|
|
106
|
+
expect(report.inconsistent).toEqual([])
|
|
107
|
+
})
|
|
108
|
+
})
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: © 2026 LEDGER SAS
|
|
2
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import type { CoinModuleImpl, OptionalApiKey } from '../api/impl'
|
|
5
|
+
import type { CoinModuleApi, Memo, TxData } from '../api/types'
|
|
6
|
+
import type { Context, CurrencyConfig } from '../config'
|
|
7
|
+
import { optionalApiKeys } from '../api/impl'
|
|
8
|
+
import { withDefaults } from '../api/withDefaults'
|
|
9
|
+
|
|
10
|
+
/** Narrows a member reached by name to a callable without asserting its type. */
|
|
11
|
+
const isMethod = (value: unknown): value is (...args: unknown[]) => unknown =>
|
|
12
|
+
typeof value === 'function'
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* What a module reports about the capabilities it does not implement, as a consumer sees it
|
|
16
|
+
* through `withDefaults`. Meant to be asserted whole:
|
|
17
|
+
*
|
|
18
|
+
* ```ts
|
|
19
|
+
* await expect(capabilityReport(createApi(), context)).resolves.toEqual({
|
|
20
|
+
* unsupported: ['call', 'craftRawTransaction', 'getRewards', 'getValidators', 'register'],
|
|
21
|
+
* inconsistent: [],
|
|
22
|
+
* })
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* One expectation then covers what a module's api test used to spell out method by method:
|
|
26
|
+
* that each capability is absent, that reaching it raises `"<name> is not supported"`, and
|
|
27
|
+
* that `supports()` agrees. `toEqual` makes it exhaustive — a capability dropped or newly
|
|
28
|
+
* implemented changes the list, so the test notices instead of silently still passing.
|
|
29
|
+
*
|
|
30
|
+
* It reads a module written either way: a `CoinModuleImpl` that omits its capabilities, or a
|
|
31
|
+
* value built by spreading `notSupportedApi()`. Both are "not implemented" as far as
|
|
32
|
+
* `supports()` is concerned, which is what this observes.
|
|
33
|
+
*/
|
|
34
|
+
export type CapabilityReport = {
|
|
35
|
+
/** Capabilities the module does not implement, sorted, each verified to raise its error. */
|
|
36
|
+
unsupported: OptionalApiKey[]
|
|
37
|
+
/**
|
|
38
|
+
* Capabilities `supports()` calls absent but which did not raise `"<name> is not
|
|
39
|
+
* supported"` when reached — a missing backfill, or an error naming another method.
|
|
40
|
+
* Expected to be empty.
|
|
41
|
+
*/
|
|
42
|
+
inconsistent: OptionalApiKey[]
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Builds a {@link CapabilityReport} for a coin module.
|
|
47
|
+
*
|
|
48
|
+
* Only the capabilities `supports()` reports absent are actually invoked — a real
|
|
49
|
+
* implementation is never called, so this never reaches the network.
|
|
50
|
+
*
|
|
51
|
+
* `getAccountInfo` is excluded: per ADR-045 its default is the `{ type: 'none' }` sentinel
|
|
52
|
+
* rather than an error, so it is not a capability in the sense the rest of this list is.
|
|
53
|
+
*/
|
|
54
|
+
export async function capabilityReport<
|
|
55
|
+
ConfigType extends CurrencyConfig,
|
|
56
|
+
MemoType extends Memo,
|
|
57
|
+
TxDataType extends TxData,
|
|
58
|
+
>(
|
|
59
|
+
impl: CoinModuleImpl<ConfigType, MemoType, TxDataType>,
|
|
60
|
+
context: Context<ConfigType>
|
|
61
|
+
): Promise<CapabilityReport> {
|
|
62
|
+
const resolved: CoinModuleApi<ConfigType, MemoType, TxDataType> & {
|
|
63
|
+
supports: (method: OptionalApiKey) => boolean
|
|
64
|
+
} = withDefaults(impl)
|
|
65
|
+
const asRecord: Record<string, unknown> = resolved
|
|
66
|
+
|
|
67
|
+
const unsupported: OptionalApiKey[] = []
|
|
68
|
+
const inconsistent: OptionalApiKey[] = []
|
|
69
|
+
|
|
70
|
+
for (const name of optionalApiKeys) {
|
|
71
|
+
if (name === 'getAccountInfo' || resolved.supports(name)) continue
|
|
72
|
+
|
|
73
|
+
const method = asRecord[name]
|
|
74
|
+
if (!isMethod(method)) {
|
|
75
|
+
inconsistent.push(name)
|
|
76
|
+
continue
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// The framework default throws synchronously, but a module may still carry a stub written
|
|
80
|
+
// as an async function, which rejects instead. Both count as raising the error.
|
|
81
|
+
const raised = await Promise.resolve()
|
|
82
|
+
.then(() => method(context))
|
|
83
|
+
.then(
|
|
84
|
+
() => undefined,
|
|
85
|
+
(error: unknown) => (error instanceof Error ? error.message : String(error))
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
if (raised === `${name} is not supported`) unsupported.push(name)
|
|
89
|
+
else inconsistent.push(name)
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
return { unsupported: unsupported.sort(), inconsistent: inconsistent.sort() }
|
|
93
|
+
}
|