fix: 5 P0 pre-mainnet issues (#11, #1078, #1121, #936, #1098)

packages/agent/src/dkg-agent-lifecycle.ts

@@ -1511,7 +1511,24 @@ export class LifecycleSyncMethods extends DKGAgentBase {
         onKARegisteredToContextGraph: this.vmReconcileEnabled()
           ? async ({ contextGraphId: onChainId, kaId }) => {
               const localCgId = this.resolveLocalCgIdByOnChainId(BigInt(onChainId));
-              if (!localCgId) return; // chain replay hasn't resolved the cleartext CG yet; sweep heals it
+              if (!localCgId) {
+                // GH #1098 — a pre-subscribed PUBLIC member peer may not have
+                // bound this CG's on-chain id yet (only curated CGs bind on the
+                // ContextGraphCreated event; ACK-signers bind via the storage-ACK
+                // hook). Rather than wait up to a full sweep interval, run a
+                // self-priming sweep NOW so any subscribed-but-unbound CG resolves
+                // + binds its on-chain id from the local ontology/_meta and
+                // reconciles immediately. Gated on there actually being an unbound
+                // subscription so a KA registration for an unrelated CG is a no-op.
+                const hasUnbound = [...this.subscribedContextGraphs.values()].some(
+                  (s) => s.subscribed && !s.onChainId,
+                );
+                if (hasUnbound) {
+                  this.log.info(ctx, `Phase B: KACG nudge cg=${onChainId} ka=${kaId} -> self-priming reconcile sweep (unbound pre-subscription)`);
+                  await this.runVmReconcileSweep();
+                }
+                return; // chain replay hasn't resolved the cleartext CG yet; periodic sweep is the safety net
+              }
               const sub = this.subscribedContextGraphs.get(localCgId);
               // Populate VM for CGs we member-subscribe to OR (Phase D) public
               // CGs this Core hosts — a hosted Core fills its own gaps too.

packages/agent/src/dkg-agent-swm-host.ts

@@ -2348,6 +2348,30 @@ export class SwmHostModeMethods extends DKGAgentBase {
   async runVmReconcileSweep(this: DKGAgent): Promise<void> {
     if (!this.vmReconcileEnabled() || !this.reconcileCoalescer) return;
     for (const [localCgId, sub] of this.subscribedContextGraphs) {
+      // GH #1098 — self-prime the on-chain id for a pre-subscribed PUBLIC member
+      // CG. A peer that subscribed BEFORE the CG's first publish has
+      // `sub.onChainId` unset: the chain `ContextGraphCreated` handler only binds
+      // it for CURATED CGs, and the ACK-signer path (`recordCoreHostedPublicCg`)
+      // only fires for cores in that publish's storage-ACK set. Left unbound, the
+      // sweep below skips the CG and the peer is stranded on the unreliable
+      // one-shot finalization gossip (the ~1/3 materialization + kc-not-synced
+      // spam in #1098). As soon as the CG's OnChainId quad is local (publisher
+      // ontology-topic broadcast or durable _meta sync), resolve + bind it so the
+      // reliable chain-driven reconcile/backfill runs for this peer — the same
+      // path the late-subscriber (#886) and ACK-signer cores already converge on.
+      // Best-effort + gated on `!sub.onChainId` so it binds at most once (a later
+      // id CHANGE would reset the cursor; binding from undefined never does).
+      if (sub.subscribed && !sub.onChainId) {
+        try {
+          const resolved = await this.getContextGraphOnChainId(localCgId);
+          if (resolved && resolved !== localCgId) {
+            this.bindSubscriptionOnChainId(localCgId, sub, resolved);
+            this.persistContextGraphSubscription(localCgId);
+          }
+        } catch {
+          /* a store/RPC hiccup on one CG must not abort the whole sweep */
+        }
+      }
       // Member subscriptions AND Phase D core-hosted public CGs get swept.
       if ((!sub.subscribed && !sub.coreHosted) || !sub.onChainId) continue;
       void this.reconcileCoalescer.trigger(localCgId);

packages/agent/src/finalization-handler.ts

@@ -1066,8 +1066,18 @@ export class FinalizationHandler {
     }
     const kaMetadata: KAMetadata[] = [];
 
-    for (let tokenIdx = 0; tokenIdx < rootEntities.length; tokenIdx++) {
-      const rootEntity = rootEntities[tokenIdx];
+    // GH #936 — assign per-root tokenIds over a CANONICAL (lexicographic) root
+    // order, NOT the SPARQL/gossip binding order. oxigraph binding order is
+    // store-history-dependent, so two replicas reconciling the same KC from
+    // chain would otherwise mint divergent root→tokenId maps. These tokenIds are
+    // local compatibility labels (the on-chain KA count is 1, no on-chain
+    // dependency — see dkg-publisher.ts), so a content-derived sort makes the
+    // map a pure function of the root SET: identical on every replica and on
+    // both the gossip and chain-reconcile promotion paths.
+    const orderedRoots = [...rootEntities].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+
+    for (let tokenIdx = 0; tokenIdx < orderedRoots.length; tokenIdx++) {
+      const rootEntity = orderedRoots[tokenIdx];
       const entityQuads = partitioned.get(rootEntity) ?? [];
       if (entityQuads.length === 0) continue;
       kaMetadata.push({
@@ -1159,6 +1169,35 @@ export class FinalizationHandler {
     } catch { /* tentative status may not exist */ }
 
     let metaQuads = generateConfirmedFullMetadata(kcMeta, kaMetadata, provenance);
+
+    // GH #936 — emit an EXPLICIT, deterministic per-root token map
+    // (`<ual>/<tokenId>` dkg:tokenId / dkg:entity) for multi-root KCs so two
+    // replicas reconciling the same KC expose an IDENTICAL, queryable
+    // rootEntity→tokenId mapping (the tokenId now derives from the canonical
+    // root sort above). Emitted here rather than in generateKCMetadata, which
+    // metadata.test.ts pins to forbid these predicates. graph = the default
+    // `<cg>/_meta` so the ctxGraphId remap below routes them to the per-cgId
+    // `_meta` (and dual-writes a root copy when keepRootCopyOnLabel).
+    if (kaMetadata.length > 1) {
+      const defaultMetaGraph = `did:dkg:context-graph:${contextGraphId}/_meta`;
+      for (const ka of kaMetadata) {
+        const labelSubject = `${ual}/${ka.tokenId}`;
+        metaQuads.push(
+          {
+            subject: labelSubject,
+            predicate: `${DKG_NS}tokenId`,
+            object: `"${ka.tokenId}"^^<http://www.w3.org/2001/XMLSchema#integer>`,
+            graph: defaultMetaGraph,
+          },
+          {
+            subject: labelSubject,
+            predicate: DKG_ENTITY,
+            object: ka.rootEntity,
+            graph: defaultMetaGraph,
+          },
+        );
+      }
+    }
     if (ctxGraphId) {
       const defaultMeta = `did:dkg:context-graph:${contextGraphId}/_meta`;
       const targetMeta = contextGraphMetaUri(contextGraphId, ctxGraphId);

packages/agent/src/op-wallets.ts

@@ -1,6 +1,7 @@
 import { ethers } from 'ethers';
 import { chmod, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from 'node:crypto';
 
 export interface WalletEntry {
   address: string;
@@ -16,6 +17,31 @@ export interface OpWalletsConfig {
 
 const DEFAULT_WALLET_COUNT = 3;
 
+// GH #11 — operational wallet private keys are encrypted at rest (AES-256-GCM)
+// so `wallets.json` never carries a plaintext key. The key is derived from a
+// machine-local 32-byte secret in `wallets.key` (zero operator interaction);
+// when `DKG_WALLETS_PASSPHRASE` is set it is mixed in via scrypt for an extra
+// factor against host-FS compromise. `address` stays plaintext so every
+// address-only reader (faucet, openclaw setup, status) keeps working, and
+// `loadOpWallets` still returns decrypted keys in memory for the chain config.
+const WALLET_SECRET_FILE = 'wallets.key';
+const PASSPHRASE_ENV = 'DKG_WALLETS_PASSPHRASE';
+
+interface EncryptedKeystore {
+  v: number;
+  alg: 'aes-256-gcm';
+  kdf: 'raw' | 'scrypt';
+  iv: string;
+  ct: string;
+  tag: string;
+}
+
+interface StoredWalletEntry {
+  address: string;
+  privateKey?: string;
+  keystore?: EncryptedKeystore;
+}
+
 /**
  * Load admin + operational wallets from `wallets.json` in the data directory.
  * Legacy files without `adminWallet` remain readable, but profile
@@ -34,7 +60,7 @@ export async function loadOpWallets(
 
   try {
     const raw = await readFile(filePath, 'utf-8');
-    const parsed = JSON.parse(raw) as Partial<OpWalletsConfig> | WalletEntry[];
+    const parsed = JSON.parse(raw) as { adminWallet?: StoredWalletEntry; wallets?: StoredWalletEntry[] } | StoredWalletEntry[];
     const existingWallets = Array.isArray(parsed) ? parsed : parsed.wallets;
     if (!Array.isArray(existingWallets)) {
       throw new Error('wallets.json must contain a wallets array');
@@ -44,12 +70,37 @@ export async function loadOpWallets(
     }
 
     {
-      const wallets = existingWallets.map((w, index) =>
-        validateWalletEntry(w, `wallets[${index}]`),
-      );
-      const adminWallet = !Array.isArray(parsed) && parsed.adminWallet
-        ? validateWalletEntry(parsed.adminWallet, 'adminWallet')
-        : undefined;
+      const adminStored = !Array.isArray(parsed) ? parsed.adminWallet : undefined;
+      // Decrypt any keystore entries before validating addresses. The secret is
+      // only required when at least one entry is encrypted; legacy plaintext
+      // files load with no secret and are opportunistically re-encrypted below.
+      const hasEncrypted = existingWallets.some(isEncryptedEntry)
+        || (adminStored ? isEncryptedEntry(adminStored) : false);
+      const secret = hasEncrypted ? await loadWalletSecret(dataDir) : undefined;
+      if (hasEncrypted && !secret) {
+        throw new Error(
+          `wallets.json holds encrypted wallet keystores but ${WALLET_SECRET_FILE} is missing — cannot decrypt. ` +
+            `Restore ${WALLET_SECRET_FILE} (or set ${PASSPHRASE_ENV} if it was passphrase-protected) from backup.`,
+        );
+      }
+
+      const resolve = (stored: StoredWalletEntry, path: string): WalletEntry => {
+        if (isEncryptedEntry(stored)) {
+          const privateKey = decryptKey(stored.keystore!, secret!);
+          return validateWalletEntry({ address: stored.address, privateKey }, path);
+        }
+        // Legacy plaintext entry — load as-is. We deliberately do NOT rewrite
+        // the file: a hand-provisioned / tooling-written plaintext wallets.json
+        // (devnet provisioning, the live-daemon test fixture, operators who
+        // manage the file directly) must stay byte-compatible with external
+        // readers. New nodes generate encrypted wallets (see saveOpWallets), so
+        // a fresh install is encrypted at rest; existing plaintext files are
+        // honoured unchanged.
+        return validateWalletEntry({ address: stored.address, privateKey: stored.privateKey as string }, path);
+      };
+
+      const wallets = existingWallets.map((w, index) => resolve(w, `wallets[${index}]`));
+      const adminWallet = adminStored ? resolve(adminStored, 'adminWallet') : undefined;
 
       if (adminWallet) {
         const adminKey = adminWallet.address.toLowerCase();
@@ -85,8 +136,18 @@ export function generateWallets(count: number): OpWalletsConfig {
 
 async function saveOpWallets(dataDir: string, config: OpWalletsConfig): Promise<void> {
   await mkdir(dataDir, { recursive: true });
+  const secret = await loadOrCreateWalletSecret(dataDir);
+  const passphrase = process.env[PASSPHRASE_ENV];
+  const encEntry = (w: WalletEntry): StoredWalletEntry => ({
+    address: w.address,
+    keystore: encryptKey(w.privateKey, secret, passphrase),
+  });
+  const stored: { adminWallet?: StoredWalletEntry; wallets: StoredWalletEntry[] } = {
+    ...(config.adminWallet ? { adminWallet: encEntry(config.adminWallet) } : {}),
+    wallets: config.wallets.map(encEntry),
+  };
   const filePath = join(dataDir, 'wallets.json');
-  await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  await writeFile(filePath, JSON.stringify(stored, null, 2) + '\n', { mode: 0o600 });
   await chmod(filePath, 0o600);
 }
 
@@ -104,3 +165,80 @@ function validateWalletEntry(entry: WalletEntry, path: string): WalletEntry {
   }
   return { address: derived.address, privateKey: derived.privateKey };
 }
+
+// ── GH #11 — at-rest encryption helpers ────────────────────────────────────
+
+function isEncryptedEntry(entry: StoredWalletEntry): boolean {
+  return !!entry && typeof entry === 'object' && !!entry.keystore;
+}
+
+/** Derive the 32-byte AES key: the raw machine-local secret, optionally
+ *  strengthened with a scrypt pass over an operator passphrase. */
+function deriveAtRestKey(secret: Buffer, kdf: 'raw' | 'scrypt', passphrase?: string): Buffer {
+  if (kdf === 'scrypt') {
+    if (!passphrase) {
+      throw new Error(`${PASSPHRASE_ENV} is required to derive the wallet key for a passphrase-protected keystore`);
+    }
+    return scryptSync(passphrase, secret, 32, { N: 16384, r: 8, p: 1 });
+  }
+  return secret;
+}
+
+function encryptKey(privateKey: string, secret: Buffer, passphrase?: string): EncryptedKeystore {
+  const kdf: 'raw' | 'scrypt' = passphrase ? 'scrypt' : 'raw';
+  const key = deriveAtRestKey(secret, kdf, passphrase);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(privateKey, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    v: 1,
+    alg: 'aes-256-gcm',
+    kdf,
+    iv: iv.toString('base64'),
+    ct: ct.toString('base64'),
+    tag: tag.toString('base64'),
+  };
+}
+
+function decryptKey(keystore: EncryptedKeystore, secret: Buffer): string {
+  const passphrase = process.env[PASSPHRASE_ENV];
+  if (keystore.kdf === 'scrypt' && !passphrase) {
+    throw new Error(
+      `wallet keystore was encrypted with ${PASSPHRASE_ENV} which is not currently set — refusing to decrypt`,
+    );
+  }
+  const key = deriveAtRestKey(secret, keystore.kdf, passphrase);
+  const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(keystore.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(keystore.tag, 'base64'));
+  const pt = Buffer.concat([decipher.update(Buffer.from(keystore.ct, 'base64')), decipher.final()]);
+  return pt.toString('utf8');
+}
+
+/** Read the machine-local wallet secret, or undefined if it doesn't exist. */
+async function loadWalletSecret(dataDir: string): Promise<Buffer | undefined> {
+  try {
+    const raw = await readFile(join(dataDir, WALLET_SECRET_FILE), 'utf-8');
+    const buf = Buffer.from(raw.trim(), 'base64');
+    if (buf.length !== 32) {
+      throw new Error(`${WALLET_SECRET_FILE} is malformed (expected a 32-byte base64 secret)`);
+    }
+    return buf;
+  } catch (err: any) {
+    if (err.code === 'ENOENT') return undefined;
+    throw err;
+  }
+}
+
+/** Read or create the machine-local wallet secret (32 random bytes, mode 0600).
+ *  The secret is independent of any wallet key, so it never leaks a private key. */
+async function loadOrCreateWalletSecret(dataDir: string): Promise<Buffer> {
+  const existing = await loadWalletSecret(dataDir);
+  if (existing) return existing;
+  await mkdir(dataDir, { recursive: true });
+  const secret = randomBytes(32);
+  const secretPath = join(dataDir, WALLET_SECRET_FILE);
+  await writeFile(secretPath, secret.toString('base64') + '\n', { mode: 0o600 });
+  await chmod(secretPath, 0o600);
+  return secret;
+}