Testnet Mode — switch back to Production in the menuheader when you're done.
VarnirDiffConsensus extends PostProcessEvent
/**
* Voting round: after the social-recovery guard, loads this node's
* volatile for the key and votes yes only when it holds a share and an
* address, the address equals `$i.owner.address`, `$i.owner.hashes` is
* KEY_SHARE_NODES distinct hashes, and the hash of this node's share is
* one of them. A missing volatile or share is refused ("Skip or repair").
* An mpc2 key also needs CVM-B's part in table B and, when gateway-signed,
* a verified signature by Q (voteMpc2). A yes tells the other nodes this
* node's share hash (and part2 hash and signature), for commit.
*
* @returns {Promise<boolean>}
* @memberof VarnirDiffConsensus
*/ public vote(): Promise<boolean> {
return new Promise<boolean>(async (resolve, reject) => {
// Social recovery (spec §4.5): a recovered identity is dead, a frozen one cannot move money.
const recoveryRefusal = this.refuseRecoveredStreams([]);
if (recoveryRefusal) return reject(recoveryRefusal);
const ownerTx = this.transactions.$i.owner as {
address: string;
hashes: string[];
};
// The whole table, one distinct hash per node: commit counts against
// it, so a shorter or repeated table would need fewer nodes.
if (!this.isShareTable(ownerTx.hashes)) {
return reject(`Hash table must be ${KEY_SHARE_NODES} distinct share hashes`);
}
// Load volatile to hash check
let keyVolatile: any;
try {
if (this.transactions.$o?.key) {
this.keyStream = this.getActivityStreams(this.transactions.$o.key);
this.keyId = this.keyStream.getId();
keyVolatile = await this.keyStream.getVolatile();
} else {
this.keyId = this.transactions.$r?.key as string;
keyVolatile = (await HTTP.send(`${this.dbUrl}/${this.keyId}:volatile`, "GET")).data;
}
} catch {
return reject("Missing volatile - Skip or repair");
}
if (!(keyVolatile?.private?.part && keyVolatile?.public?.address)) {
return reject("Missing Part volatile - Skip or repair");
}
// Hash this node's own share: the table is only what the caller says.
const privHash = this.ActiveCrypto.Hash.getHash(keyVolatile.private.part);
if (ownerTx.address != keyVolatile.public.address) {
return reject("Mismatching address");
}
if (ownerTx.hashes.indexOf(privHash) === -1) {
return reject("Matching hash not found");
}
// An Advanced (mpc2) key: CVM-B's part too, and (gateway-signed) the
// signature by Q over this transaction (see the class comment).
let mpc2: { hash2: string; sig: any } | null = null;
try {
const keyState: any = this.keyStream ? this.keyStream.getState() : null;
if (this.isMpc2Key(keyState, keyVolatile)) {
mpc2 = await this.voteMpc2(keyState, keyVolatile, ownerTx.hashes);
}
} catch (e) {
return reject(typeof e === "string" ? e : "DiffConsensus mpc2: refused");
}
// Tell the other nodes this one holds its share (both, for mpc2):
// commit requires one such entry from every node (see the class comment).
this.setThisInterNodeComms({
diffcon: {
key: this.keyId,
address: ownerTx.address,
hash: privHash,
...(mpc2 ? { hash2: mpc2.hash2 } : {}),
...(mpc2 && mpc2.sig ? { sig: mpc2.sig } : {}),
},
});
resolve(true);
});
}/**
* Commit round: refuses unless every node's vote reported its own share
* (KEY_SHARE_NODES distinct nodes covering the whole hash table; for an
* mpc2 key, each of the two tables, and on a gateway-signed round one
* agreed signature by Q that verifies here). Then, with `$o.key`, records
* `diffConfirmed: {at, umid}` (mpc2 signed: `{at, umid, sig,
* digestVersion}`) on the key stream (an existing one is kept, but an
* unsigned one gives way to a signed one) and emits `key-confirmed`.
* Returns "confirmed" to the caller.
*
* @returns {Promise<any>}
* @memberof VarnirDiffConsensus
*/ public commit(): Promise<any> {
return new Promise<any>(async (resolve, reject) => {
const ownerTx = this.transactions.$i.owner as {
address: string;
hashes: string[];
};
if (!this.keyId) {
if (this.transactions.$o?.key) {
this.keyStream = this.getActivityStreams(this.transactions.$o.key);
this.keyId = this.keyStream.getId();
} else {
this.keyId = this.transactions.$r?.key as string;
}
}
const confirmedBy = this.nodesHoldingShares(ownerTx.address, ownerTx.hashes, "hash");
if (confirmedBy < KEY_SHARE_NODES) {
return reject(`DiffConsensus needs all ${KEY_SHARE_NODES} nodes to hold their share; ${confirmedBy} confirmed`);
}
// An Advanced (mpc2) key: table B counted the same way, and the
// signature agreed and verified again (commitMpc2). Decided from the
// key's committed state, not from this node's vote: a node that voted
// no still commits when the network agrees, and must write the same.
const keyState: any = this.keyStream ? this.keyStream.getState() : null;
let proofSig: any = null;
if (keyState && keyState.mpcProtocol !== undefined) {
try {
proofSig = this.commitMpc2(keyState, ownerTx);
} catch (e) {
return reject(typeof e === "string" ? e : "DiffConsensus mpc2: refused");
}
}
if (this.keyStream) {
// The proof minigate's peer sync and backfill read from the ledger
// (a gateway that missed the event still sees it). The first proof
// stays: a lost reply makes the generator run this again. The one
// exception: a signed proof replaces an unsigned one (an mpc2 key
// confirmed by a minigate older than the signature, or before it, is
// upgraded by the backfill), never the other way round.
const existing = keyState.diffConfirmed;
if (!existing || (proofSig && !(existing && existing.sig))) {
keyState.diffConfirmed = proofSig
? { at: this.cDate, umid: this.umid, sig: proofSig, digestVersion: MPC2_DIFFCON_DOMAIN }
: { at: this.cDate, umid: this.umid };
this.keyStream.setState(keyState);
}
const proof = keyState.diffConfirmed;
// Every gateway adds the key to its pool on this (an mpc2 key with
// the signed proof needs nothing more; one without still needs its
// canary). Emitted on a re-run too, for a gateway that missed the
// first. The signed proof travels with it, the one on the ledger
// (perhaps an earlier run's); gateways re-verify it from their own
// ledger read, never from the event.
this.event.emit("key-confirmed", {
stream: this.keyId,
address: keyState.address,
network: keyState.network,
symbol: keyState.symbol,
keyMethod: keyState.keyMethod === "mpc-tss" ? "mpc-tss" : "standard",
...(keyState.mpcProtocol !== undefined ? { mpcProtocol: keyState.mpcProtocol } : {}),
umid: this.umid,
...(proof && proof.sig ? { diffConfirmed: { umid: proof.umid, sig: proof.sig, digestVersion: proof.digestVersion } } : {}),
});
}
this.returnToRemote("confirmed");
resolve(true);
});
} private refuseRecoveredIdentity(state: any, outgoing: boolean): string | null {
if (state && state.recoveredTo) {
// A dead identity may still RECEIVE: the credit lands and is swept to recoveredTo.
return outgoing
? `Identity recovered - new identity is ${state.recoveredTo}; your keys are still valid`
: null;
}
if (outgoing && state && state.recovery && state.recovery.frozen) {
return "Identity frozen - a social recovery is in its 48h waiting period";
}
return null;
} private refuseRecoveredStreams(incomingOnly: string[] | "all-outputs"): string | null {
// Never getActivityStreams(ref): an unloaded ref CREATES a stream. The
// no-argument form returns only the streams this transaction loaded.
const ctx: any = this as any;
const loaded: any = ctx.getActivityStreams() || {};
const outputs: any = (ctx.transactions && ctx.transactions.$o) || {};
const toId = (label: string, ref: any): string | null => {
const raw = ref && typeof ref === "object" ? ref.$stream : typeof ref === "string" ? ref : /^[0-9a-f]{64}$/i.test(label) ? label : null;
return typeof raw === "string" ? raw.split(":")[0].slice(-64) : null;
};
const outputIds: string[] = [];
const incomingIds: string[] = [];
for (const label of Object.keys(outputs)) {
const id = toId(label, outputs[label]);
if (!id) continue;
outputIds.push(id);
if (incomingOnly === "all-outputs" || incomingOnly.indexOf(label) !== -1) incomingIds.push(id);
}
for (const id of Object.keys(loaded)) {
const activity = loaded[id];
if (!activity || typeof activity.getState !== "function") continue;
const signed = typeof activity.hasSignature === "function" && activity.hasSignature();
const incoming = !signed && outputIds.indexOf(id) !== -1 && incomingIds.indexOf(id) !== -1;
const refusal = this.refuseRecoveredIdentity(activity.getState(), !incoming);
if (refusal) return refusal;
}
return null;
}/** True for exactly KEY_SHARE_NODES distinct non-empty strings. */
private isShareTable(hashes: unknown): boolean {
if (!Array.isArray(hashes) || hashes.length !== KEY_SHARE_NODES) return false;
const seen: { [hash: string]: boolean } = {};
for (const hash of hashes) {
if (typeof hash !== "string" || !hash || seen[hash]) return false;
seen[hash] = true;
}
return true;
}/** * How many nodes reported holding a share of this key in `table`: the * inter-node comms entries naming this key and address whose `field` * (`hash` for table A, `hash2` for an mpc2 key's table B) is in the table, * counting each node and each hash once. The smaller of the two counts, so * two nodes reporting the same share count once. Called once per table, so * a node counts for B only with its own part2 hash: a node holding A alone * leaves B one short and commit refuses. */
private nodesHoldingShares(address: string, table: string[], field: "hash" | "hash2"): number {
if (!this.isShareTable(table)) return 0;
const comms: any = this.getInterNodeComms() || {};
const nodes: { [node: string]: boolean } = {};
const hashes: { [hash: string]: boolean } = {};
let nodeCount = 0;
let hashCount = 0;
for (const node of Object.keys(comms)) {
const entry = comms[node]?.diffcon;
if (!entry || entry.key !== this.keyId || entry.address !== address) continue;
const hash = entry[field];
if (typeof hash !== "string" || table.indexOf(hash) === -1) continue;
if (!nodes[node]) {
nodes[node] = true;
nodeCount++;
}
if (!hashes[hash]) {
hashes[hash] = true;
hashCount++;
}
}
return nodeCount < hashCount ? nodeCount : hashCount;
}/** * Whether this key is an Advanced (mpc2) key, so both tables are checked. * The key's state says so (`mpcProtocol`, written by Create). A legacy * `$r.key` round has no state here, so its volatile's second table * (`public.hashes2`, Create writes it only for mpc2 keys) says so instead: * such a key is then refused (voteMpc2), never confirmed on table A alone. * An old (#200) mpc-tss key has neither and keeps the single check: it has * no table B on the ledger to check against. */
private isMpc2Key(state: any, volatile: any): boolean {
if (state && state.mpcProtocol !== undefined) return true;
return !!(volatile && volatile.public && volatile.public.hashes2 !== undefined);
}/** * The mpc2 half of vote(). Returns this node's part2 hash and, on a * gateway-signed round, the signature it verified. Each throw is a no * vote, and why each check is here: * - `$o.key` only: the proof is written on the key stream, and the tables * come from its committed state. * - exactly an mpc2 key (keyMethod and protocol): the CVMs answer for no * other, and an altered record must not pass as one. * - not frozen, retired or purged: such a key is never offered again, and * a frozen key's CVMs refuse to sign it anyway. * - Q compressed and equal under both names: what the signature is * checked against, as CryptoTransfer and the canary require. * - two disjoint tables of four, and the caller's table equal to table A: * the counts in commit are only as strong as the tables they count. * - part2 present and in table B: the gap this closes (CVM-B's part). * - the signature (signed rounds): voteMpc2Signature. */
private async voteMpc2(state: any, volatile: any, callerTable: string[]): Promise<{ hash2: string; sig: any }/**
* Asks this node's egress agent for the DiffConsensus signature and returns
* `{r, s, v}` once it verifies. The order matters: the halt first (a
* signing session with a peer a CVM judged suspect is what the halt stops),
* then one `mpc2/sign` carrying this node's two parts and
* `tx: {diffcon: true}` (the CVMs build the digest from the request's umid
* themselves; the payload names no digest and no umid to sign), then the
* answer checks (mpc2DiffconAnswerRefusal). Nothing here is written.
*/ private async voteMpc2Signature(state: any, part: string, part2: string, tables: string[][], q: string): Promise<any> {
const keyId = this.keyId;
// The CVMs name a key by its stream id (Create's keygen keyId).
if (typeof keyId !== "string" || !/^[0-9a-f]{64}$/.test(keyId)) {
throw "DiffConsensus mpc2: the key id must be 64 lowercase hex";
}
// The CVMs bind the network into every request; only the key's own.
if (typeof state.network !== "string" || !/^[A-Za-z0-9-]{1,32}$/.test(state.network)) {
throw "DiffConsensus mpc2: the key has no network";
}
await this.assertNoMpcHalt();
this.setTimeout(MPC2_VOTE_TIMEOUT_MS);
let response: any;
try {
response = await HTTP.send(
`${MPC2_EGRESS_URL}/mpc2/sign`,
"POST",
[],
{
umid: this.umid,
network: state.network,
keyId,
keyMethod: "mpc-tss",
mpcProtocol: MPC2_PROTOCOL,
// Plaintext parts to loopback only: the agent seals `part` to
// CVM-A's attested key and `part2` to CVM-B's.
part,
part2,
// Exactly {diffcon: true}: the CVMs refuse any other field here,
// so nothing in the request can choose what is signed.
payload: { publicKey: q, partHashes: tables, tx: { diffcon: true } },
},
false,
MPC2_SIGN_HTTP_TIMEOUT_S
);
} catch (e) {
throw "DiffConsensus mpc2: the egress agent did not answer";
}
const both: any = response ? response.data : null;
const refusal = this.mpc2DiffconAnswerRefusal(both, keyId, state.network, q);
if (refusal) {
throw `DiffConsensus mpc2: ${refusal}`;
}
return { r: both.a.signature.r, s: both.a.signature.s, v: both.a.signature.v };
}/**
* Why the agent's `{a, b}` answer is not this transaction's DiffConsensus
* signature by Q, or null. Each check and why:
* - the agent's own refusal names the CVM and a short code (`cvm-a-boot-hold`
* for the 9 minutes after a CVM boots; `cvm-a-diffcon-unsupported` when
* the CVM's image does not support the payload, so the gateway is told
* to deploy the CVM image first; `cvm-a-refused` for an unnamed refusal,
* which an image older than the diffcon rule gives, among others). Only
* the code passes, never free text.
* - both CVMs answered ok, for this umid, each acknowledging under its own
* party exactly this key, network and Q, with one signature: an answer
* for another umid is another run's signature.
* - both acknowledged the same (sid, digest, r, s, v): one signing.
* - the digest is computed HERE from this.umid and the key id
* (mpc2DiffconDigest), and CVM-A's output and both acks must name it: a
* signature over anything else (the raw umid, another umid, a chain
* transaction) is not this evidence.
* - the signature is well formed, low-S, and recovers to Q's address
* (mpc2SignatureRefusal): the whole point, that the parts behind both
* shares sign for Q.
*/ private mpc2DiffconAnswerRefusal(both: any, keyId: string, network: string, q: string): string | null {
const isObject = (x: any) => !!x && typeof x === "object" && !Array.isArray(x);
if (!isObject(both)) {
return "no answer from the egress agent";
}
if (both.status === "error") {
const code = typeof both.error === "string" && /^[a-z0-9-]{1,64}$/.test(both.error) ? both.error : "unknown";
// PR #430 review L4: only the CVM's own bare code says its image does
// not support the payload. A bare `-refused` is any free-text refusal
// (an image older than the diffcon rule gives one, but so can other
// faults), so it is reported as what it is, not as a deploy order.
if (/^cvm-[ab]-diffcon-unsupported$/.test(code)) {
return `egress refused (${code}): the CVM image does not support this diffcon payload: deploy the CVM image first`;
}
if (/^cvm-[ab]-refused$/.test(code)) {
return `egress refused (${code}): a CVM refused the diffcon signature without a code (an image older than the diffcon rule does; check the CVM image)`;
}
return `egress refused (${code})`;
}
const parties: [any, number, string][] = [[both.a, 0, "CVM-A"], [both.b, 1, "CVM-B"]];
for (const [answer, party, who] of parties) {
if (!isObject(answer) || answer.status !== "ok") {
return `${who} refused`;
}
const ack = answer.ack;
if (answer.umid !== this.umid || !isObject(ack) || ack.party !== party || ack.umid !== this.umid || ack.keyId !== keyId ||
ack.network !== network || ack.publicKey !== q || !Array.isArray(ack.signatures) || ack.signatures.length !== 1) {
return `${who}'s acknowledgement is not for this request`;
}
}
if (JSON.stringify(both.a.ack.signatures) !== JSON.stringify(both.b.ack.signatures)) {
return "CVM-A and CVM-B acknowledged different signatures";
}
const digest = this.mpc2DiffconDigest(keyId);
const sig = both.a.signature;
if (!isObject(sig) || sig.diffcon !== digest) {
return "the signature is not over this transaction's diffcon digest";
}
const entry = both.a.ack.signatures[0];
if (!isObject(entry) || entry.inputIndex !== 0 || entry.digest !== digest || entry.r !== sig.r || entry.s !== sig.s || entry.v !== sig.v) {
return "the signature is not the acknowledged one";
}
return this.mpc2SignatureRefusal({ r: sig.r, s: sig.s, v: sig.v }, digest, q);
}/** * SHA-256(MPC2_DIFFCON_DOMAIN ‖ umid (32 bytes) ‖ keyId (32 bytes)), hex: * the same bytes as the CVMs' diffconDigest and minigate's. Over * THIS transaction's umid, so a signature from another run, or for * another key, never verifies here. */
private mpc2DiffconDigest(keyId: string): string {
if (typeof this.umid !== "string" || !/^[0-9a-f]{64}$/.test(this.umid)) {
throw "DiffConsensus mpc2: the umid must be 64 lowercase hex";
}
return utils.sha256(utils.concat([utils.toUtf8Bytes(MPC2_DIFFCON_DOMAIN), "0x" + this.umid, "0x" + keyId])).slice(2);
}/** * Why `sig` is not a low-S signature by Q over `digest`, or null. The * recovery id must give Q: `recoverAddress` is compared with Q's own * address, so no other key's signature passes. */
private mpc2SignatureRefusal(sig: any, digest: string, q: string): string | null {
if (!sig || typeof sig !== "object" || typeof sig.r !== "string" || !/^[0-9a-f]{64}$/.test(sig.r) ||
typeof sig.s !== "string" || !/^[0-9a-f]{64}$/.test(sig.s) || (sig.v !== 0 && sig.v !== 1)) {
return "the signature is malformed";
}
// Same-length lowercase hex compares as numbers do.
if (sig.s > SECP256K1_HALF_N_HEX) {
return "the signature is not low-S";
}
let recovered = "";
try {
recovered = utils.recoverAddress("0x" + digest, "0x" + sig.r + sig.s + (27 + sig.v).toString(16));
} catch (e) {
recovered = "";
}
if (recovered !== utils.computeAddress("0x" + q)) {
return "the signature is not Q's";
}
return null;
}/** * Whether this round is gateway-signed: it names `$r.minigate`, which * assertMinigateSigner proves in vote. Only such a round asks the CVMs to * sign; a minigate older than the signature sends none. */
private signedRound(): boolean {
return !!(this.transactions.$r && this.transactions.$r.minigate);
}/** * Throws unless the `$selfsign` signer is a gateway: `$r.minigate` is a * provisioned minigate (its `:volatile` carries the `minigate` flag only an * operator writes) and `$i.owner.publicKey` is one of its authorities. The * same proof as KeyHealthCheck's and CryptoTransfer's assertMinigateSigner. * Why: the signature round makes all four agents call both CVMs and spends * the key's hourly signing budget; anyone able to start it could keep a * key's payouts waiting for the budget to refill. */
private async assertMinigateSigner(): Promise<void> {
const minigateRef = this.transactions.$r ? this.transactions.$r.minigate : undefined;
if (typeof minigateRef !== "string" || !/^[0-9a-f]{64}$/.test(minigateRef)) {
throw "DiffConsensus mpc2: not authorised - missing minigate reference";
}
let minigateVolatile: any;
let minigateMeta: any;
try {
minigateVolatile = await this.getAnyStreamReadOnly(`${minigateRef}:volatile`);
minigateMeta = await this.getAnyStreamReadOnly(`${minigateRef}:stream`);
} catch (e) {
throw "DiffConsensus mpc2: not authorised - minigate unreadable";
}
if (!minigateVolatile || !minigateVolatile.minigate) {
throw "DiffConsensus mpc2: not authorised - reference is not a minigate";
}
const owner: any = this.transactions.$i.owner;
const signingKey = owner ? owner.publicKey : undefined;
if (!signingKey || !minigateMeta || !Array.isArray(minigateMeta.authorities) ||
!minigateMeta.authorities.some((a: any) => a.public === signingKey)) {
throw "DiffConsensus mpc2: not authorised - signing key is not a minigate authority";
}
}/** The per-tree constant, read in one place (tests pin another value here). */
private mpc2HaltContract(): string {
return MPC2_HALT_CONTRACT;
}/** * Throws while Varnir.CryptoTransfer's ledger halt (`mpc2Halt`, a CVM's * peer lockout kept on the ledger) stands (PR #358 review M2): this * signature is a full signing session with the peer, which is what the * lockout stops. Blank or unreadable refuses: without it no node can say * the peer is trusted. The same rule as KeyHealthCheck's canary. */
private async assertNoMpcHalt(): Promise<void> {
const haltContract = this.mpc2HaltContract();
if (!/^[0-9a-f]{64}$/.test(haltContract)) {
throw "DiffConsensus mpc2: the halt record's contract is not configured on this network";
}
let doc: any;
try {
doc = await this.getAnyStreamReadOnly(`${haltContract}:data`);
} catch (e) {
throw "DiffConsensus mpc2: cannot read the ledger halt record";
}
const data = doc && typeof doc === "object" && doc.data && typeof doc.data === "object" ? doc.data : {};
if (data.mpc2Halt !== undefined && data.mpc2Halt !== null) {
throw "DiffConsensus mpc2: MPC signing is halted on the ledger (peer lockout)";
}
}/** The key's Q, compressed hex, equal under both of Create's names. Throws otherwise. */
private mpc2PublicKey(state: any): string {
const q = state ? state.publicKey : undefined;
if (typeof q !== "string" || !/^0[23][0-9a-f]{64}$/.test(q) || (state.pubkey !== undefined && state.pubkey !== q)) {
throw "DiffConsensus mpc2: the key has no compressed publicKey";
}
return q;
}/** The key's part-hash tables as `[A, B]`: two disjoint tables of KEY_SHARE_NODES distinct SHA-256 hex hashes. Throws otherwise. */
private mpc2Tables(t: any): string[][] {
const table = (x: any) =>
this.isShareTable(x) && x.every((h: any) => /^[0-9a-f]{64}$/.test(h));
if (!Array.isArray(t) || t.length !== 2 || !table(t[0]) || !table(t[1]) || t[0].some((h: string) => t[1].indexOf(h) !== -1)) {
throw `DiffConsensus mpc2: the key's partHashes must be two disjoint tables of ${KEY_SHARE_NODES} distinct hashes`;
}
return [t[0].slice(), t[1].slice()];
}/** True when `a` holds exactly the hashes of `b` (order free; both already share tables). */
private sameTable(a: any, b: string[]): boolean {
if (!this.isShareTable(a) || a.length !== b.length) return false;
return a.every((h: string) => b.indexOf(h) !== -1);
} public postProcess(territoriality: boolean, who: string): Promise<any> {
return new Promise<any>((resolve) => resolve(true));
}