@totemsdk/chain-provider 0.2.1 → 0.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/dist/cjs/index.d.ts +10 -0
- package/dist/cjs/index.js +22 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/providers/composite.d.ts +20 -0
- package/dist/cjs/providers/composite.js +54 -0
- package/dist/cjs/providers/hosted.d.ts +58 -0
- package/dist/cjs/providers/hosted.js +243 -0
- package/dist/cjs/providers/lookup-client.d.ts +62 -0
- package/dist/cjs/providers/lookup-client.js +67 -0
- package/dist/cjs/providers/minima-rpc.d.ts +49 -0
- package/dist/cjs/providers/minima-rpc.js +196 -0
- package/dist/cjs/resolve.d.ts +63 -0
- package/dist/cjs/resolve.js +100 -0
- package/dist/cjs/types.d.ts +150 -0
- package/dist/cjs/types.js +5 -0
- package/dist/cjs/verify-deposit.d.ts +53 -0
- package/dist/cjs/verify-deposit.js +212 -0
- package/dist/index.js +6 -22
- package/dist/providers/composite.js +1 -5
- package/dist/providers/hosted.js +1 -5
- package/dist/providers/lookup-client.js +1 -5
- package/dist/providers/minima-rpc.d.ts +19 -0
- package/dist/providers/minima-rpc.js +80 -11
- package/dist/resolve.js +12 -18
- package/dist/types.d.ts +13 -0
- package/dist/types.js +1 -2
- package/dist/verify-deposit.js +15 -25
- package/package.json +15 -9
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* MinimaRpcProvider — thin wrapper over @totemsdk/minima-rpc.
|
|
4
|
+
*/
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.MinimaRpcProvider = void 0;
|
|
7
|
+
const verify_deposit_js_1 = require("../verify-deposit.js");
|
|
8
|
+
class MinimaRpcProvider {
|
|
9
|
+
constructor(client) {
|
|
10
|
+
this.client = client;
|
|
11
|
+
}
|
|
12
|
+
async getCoins(query) {
|
|
13
|
+
const result = await this.client.coins({
|
|
14
|
+
address: query.address,
|
|
15
|
+
tokenid: query.tokenId,
|
|
16
|
+
sendable: query.sendable,
|
|
17
|
+
relevant: query.relevant,
|
|
18
|
+
coinid: query.coinId,
|
|
19
|
+
megammr: query.megammr,
|
|
20
|
+
});
|
|
21
|
+
return result;
|
|
22
|
+
}
|
|
23
|
+
async getCoin(coinId) {
|
|
24
|
+
// `coins` only returns wallet-relevant coins, so it never sees coins locked
|
|
25
|
+
// to an app/channel script. `coinexport` is the chain-level primitive and is
|
|
26
|
+
// the only reliable way to resolve an arbitrary coinid (see verifyDeposit).
|
|
27
|
+
try {
|
|
28
|
+
const exported = await this.client.coinExport(coinId);
|
|
29
|
+
const coin = exported?.coinproof?.coin;
|
|
30
|
+
if (coin) {
|
|
31
|
+
return { ...coin, spent: coin.spent === true };
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
// fall through to the wallet query
|
|
36
|
+
}
|
|
37
|
+
try {
|
|
38
|
+
const coins = await this.getCoins({ coinId });
|
|
39
|
+
return coins[0] ?? null;
|
|
40
|
+
}
|
|
41
|
+
catch {
|
|
42
|
+
return null;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Authoritative live check via `coinexport` (the coinproof endpoint): returns
|
|
47
|
+
* found/unspent/owned/token/amount + the full coin proof. `coincheck` on
|
|
48
|
+
* totem-node wants a full proof payload rather than a coinid, so coinexport
|
|
49
|
+
* is the canonical primitive (#3).
|
|
50
|
+
*/
|
|
51
|
+
async verifyDeposit(params) {
|
|
52
|
+
try {
|
|
53
|
+
const exported = await this.client.coinExport(params.coinId);
|
|
54
|
+
const coin = exported?.coinproof?.coin;
|
|
55
|
+
const spent = coin?.spent === true;
|
|
56
|
+
if (!coin) {
|
|
57
|
+
return (0, verify_deposit_js_1.notFoundResult)(`coin ${params.coinId} not found on chain`);
|
|
58
|
+
}
|
|
59
|
+
return (0, verify_deposit_js_1.evaluateDeposit)(coin, spent, params);
|
|
60
|
+
}
|
|
61
|
+
catch (error) {
|
|
62
|
+
return {
|
|
63
|
+
valid: false,
|
|
64
|
+
exists: false,
|
|
65
|
+
unspent: false,
|
|
66
|
+
confirmed: false,
|
|
67
|
+
ownedByOwner: false,
|
|
68
|
+
tokenMatches: false,
|
|
69
|
+
amountSufficient: false,
|
|
70
|
+
reason: 'unable to reach chain provider',
|
|
71
|
+
error,
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
depositAddressFor(lp, opts) {
|
|
76
|
+
return (0, verify_deposit_js_1.depositAddressFor)(lp, opts);
|
|
77
|
+
}
|
|
78
|
+
/** MMR root at tip — the anchor peers verify offline proofs against. */
|
|
79
|
+
async getMmrRoot() {
|
|
80
|
+
const info = await this.client.megammr();
|
|
81
|
+
return info?.hash ?? null;
|
|
82
|
+
}
|
|
83
|
+
async getProof(coinId) {
|
|
84
|
+
return this.client.mmrProof(coinId);
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Current minimum TxPoW work from the tip block's Magic numbers (`magic`
|
|
88
|
+
* command). This is the live target locally mined transactions must meet;
|
|
89
|
+
* using it avoids hardcoding a difficulty that may be harder than the
|
|
90
|
+
* network currently requires (or easier than it has drifted to).
|
|
91
|
+
*/
|
|
92
|
+
async getMinTxPowWork() {
|
|
93
|
+
try {
|
|
94
|
+
const info = await this.client.magic();
|
|
95
|
+
return info?.lastblock?.currentmintxpowwork ?? null;
|
|
96
|
+
}
|
|
97
|
+
catch {
|
|
98
|
+
return null;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
async getTip() {
|
|
102
|
+
return this.client.getTip();
|
|
103
|
+
}
|
|
104
|
+
async getToken(tokenId) {
|
|
105
|
+
const tokens = await this.client.tokens(tokenId);
|
|
106
|
+
if (!tokens || tokens.length === 0) {
|
|
107
|
+
throw new Error(`Token not found: ${tokenId}`);
|
|
108
|
+
}
|
|
109
|
+
return tokens[0];
|
|
110
|
+
}
|
|
111
|
+
async searchTokens(query) {
|
|
112
|
+
const all = await this.client.tokens();
|
|
113
|
+
let results = all;
|
|
114
|
+
if (query.name) {
|
|
115
|
+
const needle = query.name.toLowerCase();
|
|
116
|
+
results = results.filter((t) => {
|
|
117
|
+
const nameStr = JSON.stringify(t.name ?? '').toLowerCase();
|
|
118
|
+
return nameStr.includes(needle);
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
if (query.creatorAddress) {
|
|
122
|
+
const addr = query.creatorAddress;
|
|
123
|
+
results = results.filter((t) => {
|
|
124
|
+
const desc = JSON.stringify(t.description ?? '');
|
|
125
|
+
return desc.includes(addr);
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
if (query.offset)
|
|
129
|
+
results = results.slice(query.offset);
|
|
130
|
+
if (query.limit)
|
|
131
|
+
results = results.slice(0, query.limit);
|
|
132
|
+
return results;
|
|
133
|
+
}
|
|
134
|
+
async getTokensByCreator(address) {
|
|
135
|
+
return this.searchTokens({ creatorAddress: address });
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Submit a raw transaction + witness via the node's explicit-mine path.
|
|
139
|
+
*
|
|
140
|
+
* `sendtransaction` only adds a pre-built TxPoW to the mempool; a TxPoW built
|
|
141
|
+
* outside the node has a placeholder header (block number 0, block difficulty
|
|
142
|
+
* MAX_HASH), which the node's block builder does not reliably promote. The
|
|
143
|
+
* node's own `txnmine` builds the header with the real tip fields and mines
|
|
144
|
+
* it. We then post that mined TxPoW with `sendtransaction`.
|
|
145
|
+
*
|
|
146
|
+
* TxnRow wire format (Java/C++): MiniString(id) || Transaction || Witness.
|
|
147
|
+
*/
|
|
148
|
+
async submitTransaction(txBytes, witnessBytes, id = `omnia-${Date.now()}`) {
|
|
149
|
+
try {
|
|
150
|
+
const idBytes = new TextEncoder().encode(id);
|
|
151
|
+
const len = idBytes.length;
|
|
152
|
+
const prefix = new Uint8Array([
|
|
153
|
+
(len >>> 24) & 0xff,
|
|
154
|
+
(len >>> 16) & 0xff,
|
|
155
|
+
(len >>> 8) & 0xff,
|
|
156
|
+
len & 0xff,
|
|
157
|
+
]);
|
|
158
|
+
const row = Buffer.concat([
|
|
159
|
+
Buffer.from(prefix),
|
|
160
|
+
Buffer.from(idBytes),
|
|
161
|
+
Buffer.from(txBytes),
|
|
162
|
+
Buffer.from(witnessBytes),
|
|
163
|
+
]);
|
|
164
|
+
const mined = await this.client.txnMine({ data: Buffer.from(row).toString('hex') });
|
|
165
|
+
if (!mined?.data) {
|
|
166
|
+
return { success: false, message: 'txnmine returned no data' };
|
|
167
|
+
}
|
|
168
|
+
const posted = await this.client.sendTransaction(mined.data);
|
|
169
|
+
return {
|
|
170
|
+
success: true,
|
|
171
|
+
txpowid: mined.txpowid ?? posted?.txpowid,
|
|
172
|
+
message: 'submitted via txnmine + sendtransaction',
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
catch (e) {
|
|
176
|
+
return { success: false, message: String(e) };
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
async broadcastTxPoW(txpowHex) {
|
|
180
|
+
try {
|
|
181
|
+
// `sendtransaction` submits a pre-mined TxPoW to the mempool where the
|
|
182
|
+
// node mines it into a block. `txnminepost` only posts the TxPoW (via the
|
|
183
|
+
// peer NIO path) and does not get it mined.
|
|
184
|
+
const result = await this.client.sendTransaction(txpowHex);
|
|
185
|
+
return {
|
|
186
|
+
success: true,
|
|
187
|
+
txpowid: result?.txpowid,
|
|
188
|
+
message: 'broadcast via MinimaRpc sendtransaction',
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
catch (e) {
|
|
192
|
+
return { success: false, message: String(e) };
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
exports.MinimaRpcProvider = MinimaRpcProvider;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module @totemsdk/chain-provider/resolve
|
|
3
|
+
*
|
|
4
|
+
* User-selectable chain access (RFC-013 §7). Axia remains the default relay;
|
|
5
|
+
* self-hosted mode resolves reads/broadcast through a user's own Minima node,
|
|
6
|
+
* with an optional composite (node-first, Axia-fallback) mode.
|
|
7
|
+
*
|
|
8
|
+
* The resolver is wallet-agnostic: it takes the persisted
|
|
9
|
+
* {@link ChainProviderConfig} plus the hosted-relay credentials the wallet
|
|
10
|
+
* already holds, and returns a {@link ChainStateProvider}. URL consent is
|
|
11
|
+
* enforced structurally (HTTPS remote, HTTP loopback only) so a hostile node URL
|
|
12
|
+
* cannot be configured silently.
|
|
13
|
+
*/
|
|
14
|
+
import type { ChainStateProvider } from './types.js';
|
|
15
|
+
export type ChainProviderMode = 'axia' | 'minima-rpc' | 'composite';
|
|
16
|
+
/** Persisted, user-selectable chain access config. */
|
|
17
|
+
export interface ChainProviderConfig {
|
|
18
|
+
readonly mode: ChainProviderMode;
|
|
19
|
+
/** `http(s)://host:port` for a self-hosted Minima node. */
|
|
20
|
+
readonly minimaRpcUrl?: string;
|
|
21
|
+
readonly minimaRpcUser?: string;
|
|
22
|
+
readonly minimaRpcPass?: string;
|
|
23
|
+
/** Composite only: fall back to the hosted relay on node error. Default true. */
|
|
24
|
+
readonly fallbackToAxia?: boolean;
|
|
25
|
+
}
|
|
26
|
+
export interface HostedRelayConfig {
|
|
27
|
+
readonly baseUrl: string;
|
|
28
|
+
readonly apiKey: string;
|
|
29
|
+
readonly timeoutMs?: number;
|
|
30
|
+
}
|
|
31
|
+
export interface ResolveChainProviderOptions {
|
|
32
|
+
/** Hosted relay credentials (Axia by default). */
|
|
33
|
+
readonly hosted: HostedRelayConfig;
|
|
34
|
+
/** Override hosted provider construction (tests / custom relay). */
|
|
35
|
+
readonly hostedProvider?: ChainStateProvider;
|
|
36
|
+
/** Override node provider construction (tests). */
|
|
37
|
+
readonly createMinimaProvider?: (config: ChainProviderConfig) => ChainStateProvider;
|
|
38
|
+
readonly onFallback?: (method: string, error: unknown) => void;
|
|
39
|
+
/** URL consent check. Defaults to {@link assertConsentedNodeUrl}. */
|
|
40
|
+
readonly validateUrl?: (url: string) => void;
|
|
41
|
+
}
|
|
42
|
+
export interface ParsedMinimaRpcUrl {
|
|
43
|
+
readonly host: string;
|
|
44
|
+
readonly port: number;
|
|
45
|
+
readonly ssl: boolean;
|
|
46
|
+
}
|
|
47
|
+
/** Parse `http(s)://host:port` into the minima-rpc client config shape. */
|
|
48
|
+
export declare function parseMinimaRpcUrl(url: string): ParsedMinimaRpcUrl;
|
|
49
|
+
/**
|
|
50
|
+
* Consent guard (RFC-013 §11): HTTPS is required for remote hosts; plain `http`
|
|
51
|
+
* is permitted only for loopback. Never ships a build-time localhost bypass.
|
|
52
|
+
*/
|
|
53
|
+
export declare function assertConsentedNodeUrl(url: string): void;
|
|
54
|
+
/**
|
|
55
|
+
* Resolve a {@link ChainStateProvider} from the persisted config.
|
|
56
|
+
*
|
|
57
|
+
* - `axia` → the hosted relay (default).
|
|
58
|
+
* - `minima-rpc` → the user's own node.
|
|
59
|
+
* - `composite` → node first, hosted fallback (unless `fallbackToAxia === false`).
|
|
60
|
+
*/
|
|
61
|
+
export declare function resolveChainProvider(config: ChainProviderConfig, options: ResolveChainProviderOptions): ChainStateProvider;
|
|
62
|
+
/** True when the config routes reads/broadcast away from the hosted relay. */
|
|
63
|
+
export declare function isSelfHosted(config: ChainProviderConfig): boolean;
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @module @totemsdk/chain-provider/resolve
|
|
4
|
+
*
|
|
5
|
+
* User-selectable chain access (RFC-013 §7). Axia remains the default relay;
|
|
6
|
+
* self-hosted mode resolves reads/broadcast through a user's own Minima node,
|
|
7
|
+
* with an optional composite (node-first, Axia-fallback) mode.
|
|
8
|
+
*
|
|
9
|
+
* The resolver is wallet-agnostic: it takes the persisted
|
|
10
|
+
* {@link ChainProviderConfig} plus the hosted-relay credentials the wallet
|
|
11
|
+
* already holds, and returns a {@link ChainStateProvider}. URL consent is
|
|
12
|
+
* enforced structurally (HTTPS remote, HTTP loopback only) so a hostile node URL
|
|
13
|
+
* cannot be configured silently.
|
|
14
|
+
*/
|
|
15
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
|
+
exports.parseMinimaRpcUrl = parseMinimaRpcUrl;
|
|
17
|
+
exports.assertConsentedNodeUrl = assertConsentedNodeUrl;
|
|
18
|
+
exports.resolveChainProvider = resolveChainProvider;
|
|
19
|
+
exports.isSelfHosted = isSelfHosted;
|
|
20
|
+
const minima_rpc_1 = require("@totemsdk/minima-rpc");
|
|
21
|
+
const hosted_js_1 = require("./providers/hosted.js");
|
|
22
|
+
const minima_rpc_js_1 = require("./providers/minima-rpc.js");
|
|
23
|
+
const composite_js_1 = require("./providers/composite.js");
|
|
24
|
+
const DEFAULT_RPC_PORT = 9005;
|
|
25
|
+
/** Parse `http(s)://host:port` into the minima-rpc client config shape. */
|
|
26
|
+
function parseMinimaRpcUrl(url) {
|
|
27
|
+
let parsed;
|
|
28
|
+
try {
|
|
29
|
+
parsed = new URL(url);
|
|
30
|
+
}
|
|
31
|
+
catch {
|
|
32
|
+
throw new Error(`Invalid Minima RPC URL: ${url}`);
|
|
33
|
+
}
|
|
34
|
+
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
|
|
35
|
+
throw new Error('Minima RPC URL must use http: (loopback) or https:');
|
|
36
|
+
}
|
|
37
|
+
const ssl = parsed.protocol === 'https:';
|
|
38
|
+
const port = parsed.port ? Number(parsed.port) : ssl ? 443 : DEFAULT_RPC_PORT;
|
|
39
|
+
if (!Number.isInteger(port) || port <= 0 || port > 65535) {
|
|
40
|
+
throw new Error(`Invalid Minima RPC port in URL: ${url}`);
|
|
41
|
+
}
|
|
42
|
+
return { host: parsed.hostname, port, ssl };
|
|
43
|
+
}
|
|
44
|
+
function isLoopbackHost(hostname) {
|
|
45
|
+
return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Consent guard (RFC-013 §11): HTTPS is required for remote hosts; plain `http`
|
|
49
|
+
* is permitted only for loopback. Never ships a build-time localhost bypass.
|
|
50
|
+
*/
|
|
51
|
+
function assertConsentedNodeUrl(url) {
|
|
52
|
+
const parsed = new URL(url);
|
|
53
|
+
if (parsed.protocol === 'https:')
|
|
54
|
+
return;
|
|
55
|
+
if (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname))
|
|
56
|
+
return;
|
|
57
|
+
throw new Error('Self-hosted node URL must use HTTPS. Plain http is allowed only for localhost/127.0.0.1/::1.');
|
|
58
|
+
}
|
|
59
|
+
function createNodeProvider(config) {
|
|
60
|
+
if (!config.minimaRpcUrl) {
|
|
61
|
+
throw new Error('minima-rpc mode requires minimaRpcUrl');
|
|
62
|
+
}
|
|
63
|
+
const { host, port, ssl } = parseMinimaRpcUrl(config.minimaRpcUrl);
|
|
64
|
+
const client = (0, minima_rpc_1.createMinimaRpcClient)({
|
|
65
|
+
host,
|
|
66
|
+
port,
|
|
67
|
+
ssl,
|
|
68
|
+
...(config.minimaRpcUser ? { username: config.minimaRpcUser } : {}),
|
|
69
|
+
...(config.minimaRpcPass ? { password: config.minimaRpcPass } : {}),
|
|
70
|
+
});
|
|
71
|
+
return new minima_rpc_js_1.MinimaRpcProvider(client);
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Resolve a {@link ChainStateProvider} from the persisted config.
|
|
75
|
+
*
|
|
76
|
+
* - `axia` → the hosted relay (default).
|
|
77
|
+
* - `minima-rpc` → the user's own node.
|
|
78
|
+
* - `composite` → node first, hosted fallback (unless `fallbackToAxia === false`).
|
|
79
|
+
*/
|
|
80
|
+
function resolveChainProvider(config, options) {
|
|
81
|
+
const hosted = options.hostedProvider ?? new hosted_js_1.HostedProvider(options.hosted);
|
|
82
|
+
if (config.mode === 'axia') {
|
|
83
|
+
return hosted;
|
|
84
|
+
}
|
|
85
|
+
if (!config.minimaRpcUrl) {
|
|
86
|
+
throw new Error(`chain provider mode "${config.mode}" requires minimaRpcUrl`);
|
|
87
|
+
}
|
|
88
|
+
(options.validateUrl ?? assertConsentedNodeUrl)(config.minimaRpcUrl);
|
|
89
|
+
const node = options.createMinimaProvider
|
|
90
|
+
? options.createMinimaProvider(config)
|
|
91
|
+
: createNodeProvider(config);
|
|
92
|
+
if (config.mode === 'minima-rpc' || config.fallbackToAxia === false) {
|
|
93
|
+
return node;
|
|
94
|
+
}
|
|
95
|
+
return new composite_js_1.CompositeProvider(node, hosted, options.onFallback);
|
|
96
|
+
}
|
|
97
|
+
/** True when the config routes reads/broadcast away from the hosted relay. */
|
|
98
|
+
function isSelfHosted(config) {
|
|
99
|
+
return config.mode === 'minima-rpc' || config.mode === 'composite';
|
|
100
|
+
}
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @totemsdk/chain-provider — shared types and ChainStateProvider interface
|
|
3
|
+
*/
|
|
4
|
+
export interface CoinsQuery {
|
|
5
|
+
address?: string;
|
|
6
|
+
tokenId?: string;
|
|
7
|
+
sendable?: boolean;
|
|
8
|
+
relevant?: boolean;
|
|
9
|
+
coinId?: string;
|
|
10
|
+
megammr?: boolean;
|
|
11
|
+
}
|
|
12
|
+
export interface Coin {
|
|
13
|
+
coinid: string;
|
|
14
|
+
amount: string;
|
|
15
|
+
address: string;
|
|
16
|
+
miniaddress?: string;
|
|
17
|
+
tokenid: string;
|
|
18
|
+
token?: unknown;
|
|
19
|
+
storestate?: boolean;
|
|
20
|
+
state?: unknown[];
|
|
21
|
+
spent?: boolean;
|
|
22
|
+
mmrentry?: string;
|
|
23
|
+
created?: string;
|
|
24
|
+
}
|
|
25
|
+
export interface MMRProof {
|
|
26
|
+
coinid: string;
|
|
27
|
+
data: unknown;
|
|
28
|
+
}
|
|
29
|
+
export interface ChainTip {
|
|
30
|
+
block: number;
|
|
31
|
+
hash: string;
|
|
32
|
+
time?: string;
|
|
33
|
+
}
|
|
34
|
+
export interface TokenInfo {
|
|
35
|
+
tokenid: string;
|
|
36
|
+
name: Record<string, unknown>;
|
|
37
|
+
total?: string;
|
|
38
|
+
confirmed?: string;
|
|
39
|
+
sendable?: string;
|
|
40
|
+
coins?: number;
|
|
41
|
+
script?: string;
|
|
42
|
+
description?: unknown;
|
|
43
|
+
}
|
|
44
|
+
export interface TokenSearchQuery {
|
|
45
|
+
name?: string;
|
|
46
|
+
category?: string[];
|
|
47
|
+
creatorAddress?: string;
|
|
48
|
+
limit?: number;
|
|
49
|
+
offset?: number;
|
|
50
|
+
}
|
|
51
|
+
export interface BroadcastResult {
|
|
52
|
+
txpowid?: string;
|
|
53
|
+
success: boolean;
|
|
54
|
+
message?: string;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Inputs for a live deposit-funding check. "Verified" here means a check against
|
|
58
|
+
* on-chain truth (unspent coin owned by the LP for the claimed token+amount) —
|
|
59
|
+
* never a declared string on a record.
|
|
60
|
+
*/
|
|
61
|
+
export interface VerifyDepositParams {
|
|
62
|
+
/** Coin spendable as the funding source. */
|
|
63
|
+
coinId: string;
|
|
64
|
+
/** Address that must own the coin (Mx form; 0x-hex roots are normalized against). */
|
|
65
|
+
ownerAddress: string;
|
|
66
|
+
/** Required token ID; omit to accept base MINIMA. */
|
|
67
|
+
tokenId?: string;
|
|
68
|
+
/** Claimed funding amount (decimal string); coin.amount must be >= this. */
|
|
69
|
+
claimedAmount?: string;
|
|
70
|
+
/** When true, only chain-confirmed coins pass (mmrentry != '0'). */
|
|
71
|
+
requireConfirmed?: boolean;
|
|
72
|
+
}
|
|
73
|
+
/** Granular result of a deposit-funding check. `valid` is the all-gates AND. */
|
|
74
|
+
export interface DepositVerification {
|
|
75
|
+
valid: boolean;
|
|
76
|
+
exists: boolean;
|
|
77
|
+
/** Coin exists and is not spent (on-chain confirm, not declared). */
|
|
78
|
+
unspent: boolean;
|
|
79
|
+
/** Coin is confirmed on-chain (not a mempool entry). */
|
|
80
|
+
confirmed: boolean;
|
|
81
|
+
/** Coin address equals the claimed owner (Mx or 0x-root form). */
|
|
82
|
+
ownedByOwner: boolean;
|
|
83
|
+
/** Coin tokenid matches the requested token (or base token when none given). */
|
|
84
|
+
tokenMatches: boolean;
|
|
85
|
+
/** Coin amount covers the claimed amount. */
|
|
86
|
+
amountSufficient: boolean;
|
|
87
|
+
reason?: string;
|
|
88
|
+
/** The coin as observed on-chain. */
|
|
89
|
+
coin?: Coin;
|
|
90
|
+
error?: unknown;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* A chunk-based MMR proof (legacy Minima shape), i.e. the sibling hashes
|
|
94
|
+
* between a leaf and the root. Matches `@totemsdk/core` `MMRProof`.
|
|
95
|
+
*/
|
|
96
|
+
export interface MmrChunkProof {
|
|
97
|
+
chunks: Array<{
|
|
98
|
+
isLeft: boolean;
|
|
99
|
+
mmrData: {
|
|
100
|
+
data: Uint8Array;
|
|
101
|
+
value: bigint;
|
|
102
|
+
};
|
|
103
|
+
}>;
|
|
104
|
+
}
|
|
105
|
+
/** Address-derivation policy for LP funding deposits. */
|
|
106
|
+
export interface DepositAddressOptions {
|
|
107
|
+
poolId?: string;
|
|
108
|
+
tokenId?: string;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Optional funding-truth extension port. Providers that can attest deposits
|
|
112
|
+
* implement this; `withDepositVerifier(provider)` provides a default that uses
|
|
113
|
+
* the base provider's `getCoin` for the live path.
|
|
114
|
+
*/
|
|
115
|
+
export interface DepositVerifier {
|
|
116
|
+
verifyDeposit(params: VerifyDepositParams): Promise<DepositVerification>;
|
|
117
|
+
/** Deterministic deposit address the LP funds the pool/channel from. */
|
|
118
|
+
depositAddressFor(lp: string, opts?: DepositAddressOptions): string;
|
|
119
|
+
/** Chain MMR root for offline proof verification; null when unavailable. */
|
|
120
|
+
getMmrRoot(): Promise<string | null>;
|
|
121
|
+
/** Offline (root-anchored) proof check; falls back to the live path when absent. */
|
|
122
|
+
verifyMmrDeposit?(params: {
|
|
123
|
+
leafPubkey: Uint8Array;
|
|
124
|
+
proof: MmrChunkProof;
|
|
125
|
+
expectedRoot: Uint8Array;
|
|
126
|
+
}): Promise<boolean>;
|
|
127
|
+
}
|
|
128
|
+
export interface ChainStateProvider {
|
|
129
|
+
getCoins(query: CoinsQuery): Promise<Coin[]>;
|
|
130
|
+
getCoin(coinId: string): Promise<Coin | null>;
|
|
131
|
+
getProof(coinId: string): Promise<MMRProof>;
|
|
132
|
+
getTip(): Promise<ChainTip>;
|
|
133
|
+
getToken(tokenId: string): Promise<TokenInfo>;
|
|
134
|
+
searchTokens(query: TokenSearchQuery): Promise<TokenInfo[]>;
|
|
135
|
+
getTokensByCreator(address: string): Promise<TokenInfo[]>;
|
|
136
|
+
broadcastTxPoW(txpowHex: string): Promise<BroadcastResult>;
|
|
137
|
+
/**
|
|
138
|
+
* Live minimum TxPoW work (32-byte hex target) from the node's Magic numbers.
|
|
139
|
+
* Optional: providers that cannot read it let callers fall back to the
|
|
140
|
+
* protocol default. Used to mine transactions to the current network target.
|
|
141
|
+
*/
|
|
142
|
+
getMinTxPowWork?(): Promise<string | null>;
|
|
143
|
+
/**
|
|
144
|
+
* Submit a raw transaction + witness through the node's explicit-mine path:
|
|
145
|
+
* `txnmine` (node builds the TxPoW header with the real block number /
|
|
146
|
+
* difficulty / magic and mines) followed by `sendtransaction`. When absent,
|
|
147
|
+
* callers fall back to SDK-side mining + `broadcastTxPoW`.
|
|
148
|
+
*/
|
|
149
|
+
submitTransaction?(txBytes: Uint8Array, witnessBytes: Uint8Array, id?: string): Promise<BroadcastResult>;
|
|
150
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* chain-provider/verify-deposit.ts — Funding-truth verification.
|
|
3
|
+
*
|
|
4
|
+
* "Verified every time means on-chain check," so this module is the single
|
|
5
|
+
* place a deposit's funding is checked: an unspent coin, owned by the LP,
|
|
6
|
+
* for the claimed token and amount. The offline variant anchors a legacy
|
|
7
|
+
* chunk MMR proof against a known root so a peer with a lookup root can
|
|
8
|
+
* re-validate a deposit without reaching the node.
|
|
9
|
+
*/
|
|
10
|
+
import type { ChainStateProvider, Coin, DepositAddressOptions, DepositVerification, DepositVerifier, MmrChunkProof, VerifyDepositParams } from './types.js';
|
|
11
|
+
export declare const DEPOSIT_ADDRESS_DOMAIN = "totemsdk/chain-provider/deposit/v1";
|
|
12
|
+
/**
|
|
13
|
+
* The shared all-gates deposit evaluation. Used by the generic `verifyDeposit`
|
|
14
|
+
* and by `MinimaRpcProvider` (which reads the coin proof via `coinexport`).
|
|
15
|
+
*/
|
|
16
|
+
export declare function evaluateDeposit(coin: Coin, spent: boolean, params: VerifyDepositParams): DepositVerification;
|
|
17
|
+
export declare function notFoundResult(reason: string): DepositVerification;
|
|
18
|
+
/**
|
|
19
|
+
* Live deposit check against a chain provider. All gates must hold:
|
|
20
|
+
* 1. the coin exists;
|
|
21
|
+
* 2. it is unspent (confirmed on-chain, never a declared flag);
|
|
22
|
+
* 3. it is owned by `ownerAddress` (Mx or 0x-root form);
|
|
23
|
+
* 4. its tokenid matches (base MINIMA = '0x00' when none is requested);
|
|
24
|
+
* 5. its amount covers `claimedAmount`;
|
|
25
|
+
* 6. when `requireConfirmed` is set, the coin is chain-confirmed.
|
|
26
|
+
*/
|
|
27
|
+
export declare function verifyDeposit(provider: Pick<ChainStateProvider, 'getCoin'>, params: VerifyDepositParams): Promise<DepositVerification>;
|
|
28
|
+
/**
|
|
29
|
+
* Offline verification of a legacy chunk MMR proof against an expected root.
|
|
30
|
+
* Pure function — a peer holding (leafPubkey, proof, root) can re-validate a
|
|
31
|
+
* deposit commitment without node access. The proof is encoded to the wasm
|
|
32
|
+
* contract (hex `data`, decimal-string `value` per chunk).
|
|
33
|
+
*/
|
|
34
|
+
export declare function verifyDepositMmrProof(leafPubkey: Uint8Array, proof: MmrChunkProof, expectedRoot: Uint8Array): boolean;
|
|
35
|
+
/**
|
|
36
|
+
* Deterministic, domain-separated funding address for an LP deposit. In
|
|
37
|
+
* production this is the channel/pool script address the LP pays into and the
|
|
38
|
+
* funding check is run against; keeping it a pure derivation keeps issue #25
|
|
39
|
+
* constructable and checkable without a live script compiler.
|
|
40
|
+
*/
|
|
41
|
+
export declare function depositAddressFor(lp: string, opts?: DepositAddressOptions): string;
|
|
42
|
+
/**
|
|
43
|
+
* Default `DepositVerifier` over any `ChainStateProvider`. The live path uses
|
|
44
|
+
* `getCoin`; the MMR-root path returns `null` unless the base provider knows a
|
|
45
|
+
* root (concrete providers override `getMmrRoot`).
|
|
46
|
+
*/
|
|
47
|
+
export declare function withDepositVerifier(provider: ChainStateProvider): ChainStateProvider & DepositVerifier;
|
|
48
|
+
/**
|
|
49
|
+
* Compare two decimal amounts exactly at a common scale derived from the
|
|
50
|
+
* inputs. Neither side is fixed-truncated, so a claim can never be rounded
|
|
51
|
+
* down into passing (AUD-038).
|
|
52
|
+
*/
|
|
53
|
+
export declare function compareAmounts(a: string, b: string): number;
|