Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,10 @@ src/
│ └── builder.ts # InstantSend lock proof building
├── api/ # Network communication
│ ├── insight.ts # Insight API client (UTXO fetching, broadcast)
│ ├── dapi.ts # JSON-RPC client (mainnet InstantSend locks, best chain lock)
│ ├── dapi-subscription.ts # DAPI bloom-filter stream (testnet/devnet InstantSend locks)
│ ├── dapi.ts # JSON-RPC client (only for a custom devnet with its own rpcUrl)
│ ├── dapi-subscription.ts # DAPI bloom-filter streams (InstantSend locks on every network)
│ ├── islock.ts # IslockService: picks the InstantSend lock source per network
│ ├── evonode-discovery.ts # Testnet evonodes from the masternode list the seeds serve
│ ├── evonode-discovery.ts # Testnet/mainnet evonodes from the masternode list the seeds serve
│ └── evonodes.ts # Quorum-service evonode list (discovery fallback)
├── platform/ # Dash Platform operations
│ ├── identity.ts # Identity registration and top-up
Expand Down Expand Up @@ -87,8 +87,7 @@ Network is determined by URL parameter: `?network=mainnet` (defaults to testnet)

InstantSend lock source and Platform status per network:

- **mainnet**: JSON-RPC at `rpc.digitalcash.dev` (`rpcUrl` in `config.ts`).
- **testnet**: no JSON-RPC service (trpc.digitalcash.dev never upgraded to Core V24). The lock comes from the DAPI bloom-filter stream on 3 evonodes at once. They are discovered when a funding flow starts, from the masternode list served by `@dashevo/dapi-client`'s testnet seeds, with the quorum service list as fallback; the subscription rejects before broadcast if both fail. There is no built-in node list. Platform status is read through the EvoSDK (`platform/status.ts`) because dapi-client's `platform.getStatus()` throws on testnet nodes.
- **testnet and mainnet**: no JSON-RPC service, and no digitalcash.dev anywhere (the build check fails if it reappears). The lock comes from the DAPI bloom-filter stream on 3 evonodes at once. They are discovered when a funding flow starts, from the masternode list served by `@dashevo/dapi-client`'s seeds for that network, preferring nodes the quorum service health-checks and falling back to its list; the subscription rejects before broadcast if both fail. There is no built-in node list. Platform status is read through the EvoSDK (`platform/status.ts`) (it tolerates sections nodes leave out).
- **devnets**: their configured `rpcUrl` if any, otherwise the DAPI stream over their `dapiAddresses`; Platform status through dapi-client.

## Dependencies
Expand Down
24 changes: 24 additions & 0 deletions e2e/deterministic.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,30 @@ test.describe('Deterministic UI E2E (mock mode)', () => {
expect(discoveryRequests).toEqual([]);
});

test('an idle mainnet page never calls digitalcash.dev, starts no evonode discovery and does not load the SDK', async ({ page }) => {
const forbidden: string[] = [];
page.on('request', (request) => {
const url = new URL(request.url());
if (
/(^|\.)digitalcash\.dev$/.test(url.hostname) ||
/^seed-\d+\./.test(url.hostname) ||
url.pathname === '/masternodes' ||
/evo-sdk|wasm[-_]sdk/i.test(url.pathname)
) {
forbidden.push(request.url());
}
});
const islockChunk = page.waitForRequest((request) => /\/islock(-[^/]*\.js|\.ts)$/.test(new URL(request.url()).pathname), {
timeout: 15000,
});
await page.goto('/?network=mainnet&e2e=mock');
await islockChunk;
// Let the first network-status poll go out.
await page.waitForTimeout(2000);

expect(forbidden).toEqual([]);
});

test('create identity flow transitions to completion and DPNS registration', async ({ page }) => {
await page.goto(MOCK_QUERY);

Expand Down
15 changes: 15 additions & 0 deletions scripts/check-build-artifacts.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -128,4 +128,19 @@ if (typeof verifyLogin !== 'function' || bogus?.ok !== false) {
fail('dist/widget-verify.mjs does not export a working verifyLogin');
}

// No Digital Cash service anywhere: IS locks and chain-lock heights come from
// DAPI (evonode streams, the EvoSDK). Guard against one creeping back in.
function builtFiles(dir) {
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const path = join(dir, entry.name);
return entry.isDirectory() ? builtFiles(path) : [path];
});
}
const digitalcashFiles = builtFiles(distDir.pathname).filter((path) =>
/\.(?:js|mjs|html|json|css)$/.test(path) && readFileSync(path, 'utf8').toLowerCase().includes('digitalcash')
);
Comment thread
PastaPastaPasta marked this conversation as resolved.
Resolved
if (digitalcashFiles.length > 0) {
fail(`build references digitalcash: ${digitalcashFiles.join(', ')}`);
}

console.log('Build artifact smoke check passed');
45 changes: 31 additions & 14 deletions src/api/dapi-subscription-multi.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -114,15 +114,15 @@ vi.mock('cbor', () => ({ default: { decodeFirstSync: (bytes: Buffer) => JSON.par
const fallbackMock = vi.hoisted(() => vi.fn<[], Promise<string[]>>());
vi.mock('./evonodes.js', async (importOriginal) => ({
...(await importOriginal<typeof import('./evonodes.js')>()),
fetchTestnetEvonodeAddresses: fallbackMock,
fetchHealthyEvonodeAddresses: fallbackMock,
}));

import {
DAPISubscriptionClient,
ISLOCK_CONCURRENT_NODES,
ISLOCK_MAX_NODE_ATTEMPTS,
ISLOCK_HEIGHT_TIMEOUT_MS,
ISLOCK_READINESS_CAP_MS,
ISLOCK_READINESS_TIMEOUT_MS,
} from './dapi-subscription.js';

const TXID = 'aa'.repeat(32);
Expand Down Expand Up @@ -447,15 +447,17 @@ describe('DAPISubscriptionClient multi-node IS lock subscription', () => {
for (const node of nodeClients()) expect(node.disconnect).toHaveBeenCalled();
});

it('still returns a handle when readiness comes from the cap, and a later total failure surfaces via wait()', async () => {
it('rejects subscribe before returning when no stream delivers data within the readiness timeout', async () => {
const client = new DAPISubscriptionClient({ network: 'testnet', dapiAddresses: addresses(3) });
const pending = client.subscribeForInstantSendLock(TXID, PUBKEY, UTXO, TIMEOUT);
await vi.advanceTimersByTimeAsync(ISLOCK_READINESS_CAP_MS);
const sub = await pending; // streams are open but silent: returns at the cap

const outcome = expect(sub.wait()).rejects.toThrow(/3 nodes tried.*last error: late boom 2/);
liveStreams().forEach((stream, i) => stream.emit('error', new Error(`late boom ${i}`)));
const outcome = expect(pending).rejects.toThrow(
new RegExp(`no evonode stream delivered data within ${ISLOCK_READINESS_TIMEOUT_MS}ms`)
);
// Streams are open but silent: none is known to be listening.
await vi.advanceTimersByTimeAsync(ISLOCK_READINESS_TIMEOUT_MS);
await outcome;
for (const stream of liveStreams()) expect(stream.cancel).toHaveBeenCalled();
for (const node of nodeClients()) expect(node.disconnect).toHaveBeenCalled();
});

it('rejects subscribe itself, before returning, when every stream fails inside the readiness window', async () => {
Expand Down Expand Up @@ -569,20 +571,19 @@ describe('DAPISubscriptionClient multi-node IS lock subscription', () => {
expect(late.listenerCount('data')).toBe(0);
});

it('returns after the readiness cap when no stream emits data', async () => {
it('waits for the first stream data, however late within the readiness timeout, before returning', async () => {
const client = new DAPISubscriptionClient({ network: 'testnet', dapiAddresses: addresses(3) });
let returned = false;
const pending = client
.subscribeForInstantSendLock(TXID, PUBKEY, UTXO, TIMEOUT)
.then((sub) => { returned = true; return sub; });

await vi.advanceTimersByTimeAsync(ISLOCK_READINESS_CAP_MS - 1);
await vi.advanceTimersByTimeAsync(ISLOCK_READINESS_TIMEOUT_MS - 1);
expect(returned).toBe(false);
await vi.advanceTimersByTimeAsync(1);
liveStreams()[2].emit('data', blockMessage);
const sub = await pending;
expect(returned).toBe(true);

// Streams are still connecting in the background and can still win.
liveStreams()[2].emit('data', lockMessage(TXID));
await sub.wait();
});
Expand All @@ -603,8 +604,8 @@ describe('DAPISubscriptionClient multi-node IS lock subscription', () => {
await sub.wait();
});

it('uses the single shared client with fewer than two configured addresses', async () => {
for (const dapiAddresses of [undefined, [] as string[], addresses(1)]) {
it('uses the single shared client for a devnet with one configured address', async () => {
for (const dapiAddresses of [addresses(1)]) {
state.clients.length = 0;
const client = new DAPISubscriptionClient({ network: 'devnet-moutai', dapiAddresses });
expect(state.clients).toHaveLength(1);
Expand Down Expand Up @@ -798,6 +799,22 @@ describe('DAPISubscriptionClient multi-node IS lock subscription', () => {
expect(nodeClients()).toHaveLength(3);
});

it('mainnet discovers its evonodes from the mainnet seeds the same way', async () => {
state.smlHosts = hosts(4);
const client = new DAPISubscriptionClient({ network: 'mainnet' });

const sub = await startDiscovered(client);

expect(seedClients()).toHaveLength(1);
const seed = seedClients()[0].options.dapiAddresses[0];
expect(seed.host).toMatch(/\.mainnet\.networks\.dash\.org$|pshenmic/);
// The health hint comes from the mainnet quorum service, never testnet's.
expect(fallbackMock).toHaveBeenCalledWith('mainnet');
expect(nodeClients()).toHaveLength(ISLOCK_CONCURRENT_NODES);
liveStreams()[0].emit('data', lockMessage(TXID));
await expect(sub.wait()).resolves.toBeInstanceOf(Uint8Array);
});

it('configured addresses (devnets) never start discovery', async () => {
const client = new DAPISubscriptionClient({ network: 'devnet-moutai', dapiAddresses: addresses(3) });

Expand Down
85 changes: 53 additions & 32 deletions src/api/dapi-subscription.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import { hash160 } from '../crypto/hash.js';
import { describeIslock } from '../utils/islock-debug.js';
import {
EvonodeDiscovery,
type DiscoveryNetwork,
parseDapiAddress,
seedAddresses,
shuffled,
Expand Down Expand Up @@ -49,8 +50,14 @@ export const ISLOCK_CONCURRENT_NODES = 3;
export const ISLOCK_MAX_NODE_ATTEMPTS = ISLOCK_CONCURRENT_NODES + 6;
/** Deadline for each node's best-block-height answer before the stream starts. */
export const ISLOCK_HEIGHT_TIMEOUT_MS = 8000;
/** Longest subscribeForInstantSendLock waits for a first stream message before returning. */
export const ISLOCK_READINESS_CAP_MS = 3000;
/**
* Longest subscribeForInstantSendLock waits for a first stream message. With
* no message by then it rejects (nothing has been broadcast yet): a stream
* that has not delivered anything is not known to be listening, and an IS
* lock arriving before it is would be lost. Streams replay the last 10 blocks
* first, so a live one answers within about a second.
*/
export const ISLOCK_READINESS_TIMEOUT_MS = 15000;

const CLIENT_OPTIONS = { timeout: 30000, retries: 3 };

Expand All @@ -60,11 +67,19 @@ interface NodeSlot {
failed: boolean;
}

/**
* The public network a config belongs to (by type, so an unknown name that
* falls back to the testnet config counts as testnet); undefined for devnets.
*/
function publicNetwork(network: string): DiscoveryNetwork | undefined {
const { type } = getNetwork(network);
return type === 'testnet' || type === 'mainnet' ? type : undefined;
}

export class DAPISubscriptionClient {
readonly network: string;
// Exactly one of these is set: testnet discovers its evonodes, every other
// network uses one client over its configured addresses (or, on mainnet,
// dapi-client's default seeds).
// Exactly one of these is set: testnet and mainnet discover their evonodes,
// devnets use one client over their configured addresses.
private readonly discovery?: EvonodeDiscovery;
private readonly fixedClient?: any;
private readonly nodeAddresses: DapiAddress[];
Expand All @@ -83,32 +98,30 @@ export class DAPISubscriptionClient {
// A repeated address would put two "distinct" streams on one node.
this.nodeAddresses = [...new Map(parsed.map((a) => [`${a.host}:${a.port}`, a])).values()];
this.fixedClient = new DAPIClientClass({ ...CLIENT_OPTIONS, dapiAddresses: parsed });
} else if (getNetwork(config.network).type === 'testnet') {
} else {
// Seeds come from the published dapi-client, so they follow its releases.
// A devnet without addresses can't be reached; it discovers testnet's,
// as dapi-client's default would have.
const network = publicNetwork(config.network) ?? 'testnet';
this.discovery = new EvonodeDiscovery({
network: 'testnet',
seeds: seedAddresses(dapiNetworkConfigs.testnet.seeds),
network,
seeds: seedAddresses(dapiNetworkConfigs[network].seeds),
createClient: (dapiAddresses) => new DAPIClientClass({ ...CLIENT_OPTIONS, dapiAddresses }),
});
} else {
this.fixedClient = new DAPIClientClass({
...CLIENT_OPTIONS,
network: config.network === 'mainnet' ? 'mainnet' : 'testnet',
});
}
}

/**
* Client for calls that may go to any node. On testnet it covers the
* evonodes found by the last discovery, so it is undefined before the
* first subscription.
* Client for calls that may go to any node. On testnet and mainnet it
* covers the evonodes found by the last discovery, so it is undefined
* before the first subscription.
*/
private get dapiClient(): any {
return this.discovery ? this.discovery.sharedClient : this.fixedClient;
}

/**
* Start syncing the testnet masternode list so the first IS lock
* Start reading the testnet or mainnet masternode list so the first IS lock
* subscription doesn't wait for it. Never rejects; resolves at once on
* networks with configured addresses.
*/
Expand Down Expand Up @@ -438,11 +451,11 @@ export class DAPISubscriptionClient {
* pick nodes at random and could land on the same one twice.
*
* subscribeToTransactionsWithProofs resolves before any connection exists, so
* readiness is approximated: return once any stream delivers a message (the
* server replays recent blocks, usually within ~1 s) or after the readiness
* cap, whichever comes first. The remaining streams keep connecting. If every
* node attempt has already failed by then, this rejects instead of returning
* a handle, so nothing is broadcast without a listener.
* readiness means a stream has delivered a message (the server replays
* recent blocks first, usually within ~1 s). Return then; the remaining
* streams keep connecting. If every node attempt fails first, or no stream
* delivers anything within {@link ISLOCK_READINESS_TIMEOUT_MS}, this rejects
* instead of returning a handle, so nothing is broadcast without a listener.
*/
private async subscribeOnMultipleNodes(
txid: string,
Expand All @@ -463,7 +476,7 @@ export class DAPISubscriptionClient {

let markReady!: () => void;
const ready = new Promise<void>((resolve) => { markReady = resolve; });
const readyTimerId = setTimeout(markReady, ISLOCK_READINESS_CAP_MS);
let readyTimerId: ReturnType<typeof setTimeout> | undefined;
// Set when every node attempt failed. Only read once, right after the
// readiness wait, to fail before the caller broadcasts.
let allFailed: Error | undefined;
Expand Down Expand Up @@ -507,6 +520,14 @@ export class DAPISubscriptionClient {
finish(() => reject(new Error(`Timeout waiting for InstantSend lock for ${txid} after ${timeoutMs}ms`)));
}, timeoutMs);

readyTimerId = setTimeout(() => {
const silent = new Error(
`InstantSend lock subscription failed for ${txid}: no evonode stream delivered data within ${ISLOCK_READINESS_TIMEOUT_MS}ms`
);
allFailed = silent;
finish(() => reject(silent));
}, ISLOCK_READINESS_TIMEOUT_MS);

const openNode = (): void => {
const address = nodes[attempts++];
if (!address) return;
Expand Down Expand Up @@ -622,7 +643,7 @@ export class DAPISubscriptionClient {
* Devnets go straight to dapi-client (`platform.getStatus()`) rather than
* `sdk.system.status()` because the wasm SDK in trusted mode can return
* testnet-cached values there, while this path is authoritative for
* whatever masternode the dapiAddresses point at. Testnet uses the SDK;
* whatever masternode the dapiAddresses point at. Testnet and mainnet use the SDK;
* see {@link getPlatformStatus}.
*
* @returns the chain-locked height, or `undefined` if the masternode
Expand All @@ -640,8 +661,8 @@ export class DAPISubscriptionClient {
* Tenderdash is stuck). Fields are `undefined` when the masternode doesn't
* report them.
*
* Testnet reads through the EvoSDK (see `fetchPlatformStatus` for why);
* every other network keeps the dapi-client gRPC call.
* Testnet and mainnet read through the EvoSDK (see `fetchPlatformStatus`
* for why); devnets keep the dapi-client gRPC call.
*/
async getPlatformStatus(): Promise<PlatformStatus> {
if (this.readsStatusViaSdk()) {
Expand All @@ -652,10 +673,11 @@ export class DAPISubscriptionClient {

/**
* Passive variant of {@link getPlatformStatus} for background health polling.
* On testnet it resolves `undefined`, without loading the EvoSDK, until a
* funding flow has started connecting it (and while that connect is in
* flight); from then on it reads, and failures reject. Other networks read
* exactly as getPlatformStatus does (dapi-client needs no SDK download).
* On testnet and mainnet it resolves `undefined`, without loading the
* EvoSDK, until a funding flow has started connecting it (and while that
* connect is in flight); from then on it reads, and failures reject.
* Devnets read exactly as getPlatformStatus does (dapi-client needs no SDK
* download).
*/
async peekPlatformStatus(): Promise<PlatformStatus | undefined> {
if (this.readsStatusViaSdk()) {
Expand All @@ -664,9 +686,8 @@ export class DAPISubscriptionClient {
return this.fetchStatusViaDapiClient();
}

/** By config type, not name: an unknown name falls back to the testnet config. */
private readsStatusViaSdk(): boolean {
return getNetwork(this.network).type === 'testnet';
return publicNetwork(this.network) !== undefined;
}

private async fetchStatusViaDapiClient(): Promise<PlatformStatus> {
Expand Down
Loading
Loading