5. Start the RAILGUN Privacy Engine

Please first see Getting Started for installation instructions.

The RAILGUN Engine SDK is a dependency of Wallet SDK. It contains complex scanning technologies, cryptography, transaction wrappers, and contract interfaces. Wallet SDK, in turn, simplifies and abstracts the intricate functionalities provided by this library.

The Engine requires a LevelDOWN compatible database for storing encrypted wallets, like level-js.

yarn add level-js @types/level-js

Initialize Engine

The initializeEngine function is responsible for setting up the engine with parameters related to wallet management, database storage, artifact handling, and Private Proof of Innocence (POI) verification.

Key Components

• Wallet Source: Specifies a name for your wallet implementation, which is encrypted and visible in the private transaction history. It defaults to "quickstart demo".

• Database Storage: Uses a LevelDOWN compatible database (./engine.db by default) for storing encrypted wallets. The createNodeDatabase function sets up this database.

• Artifact Storage: Manages persistent storage for downloading large artifact files, utilizing createArtifactStore.

• POI Nodes: An array of node URLs used to verify that funds are not from undesirable sources, with a default test aggregator node provided.

• Engine Debugging: Optionally forwards debug logs to a logger for development purposes.

• Shutdown Handling: Sets up a handler to properly stop the engine when the process is terminated, ensuring resources are cleanly released.

These configurations are adjustable by providing arguments when calling initializeEngine, tailoring it to specific application requirements.

// main.ts
import {
  startRailgunEngine,
  stopRailgunEngine,
} from "@railgun-community/wallet";
import { createNodeDatabase } from "./1_database";
import { createArtifactStore } from "./2_artifact-storage"; // We'll get to this in Step 2: Build a persistent store
import type { POIList } from "@railgun-community/shared-models";
import Level from "level-js";

/**
 * Initializes the RAILGUN engine with the specified configuration.
 *
 * This function sets up the RAILGUN privacy engine with necessary configurations for wallet management,
 * database storage, artifact handling, and Private Proof of Innocence (POI) verification.
 *
 * @remarks
 * - The engine requires a database for storing encrypted wallets
 * - Artifact files are downloaded and stored in a specified directory
 * - POI node URLs are used for verifying that funds are not from undesirable sources
 *
 * @returns A Promise that resolves when the engine is successfully initialized
 *
 * @example
 * ```typescript
 * await initializeEngine();
 * ```
 *
 * @see https://docs.railgun.org for more information about RAILGUN privacy system
 */
/**
 * Initializes the RAILGUN Engine with provided configuration.
 *
 * @param args - Optional initialization parameters
 * @param args.walletSource - Name for your wallet implementation. Maximum of 16 characters, lowercase.
 * @param args.dbPath - Path to LevelDOWN compatible database for storing encrypted wallets
 * @param args.artifactsPath - Persistent storage path for required Engine artifact files
 * @param args.ppoiNodes - Array of Private POI aggregator node URLs
 *
 * @remarks
 * - The engine requires a database for storing encrypted wallets
 * - Artifact files are downloaded and stored in a specified directory
 * - POI node URLs are used for verifying that funds are not from undesirable sources
 *
 * This function configures and starts the RAILGUN Engine with appropriate settings for
 * wallet identification, database storage, artifact management, and Private POI verification.
 * It also sets up a shutdown handler to properly stop the engine when the process is terminated.
 *
 * Private POI (Private Proof of Innocence) provides cryptographic assurance that funds
 * entering the RAILGUN smart contract are not from known undesirable sources. For more
 * information see: https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence
 *
 * @returns Promise that resolves when the engine is initialized
 *
 * @example
 * ```typescript
 * await initializeEngine();
 * ```
 *
 * @see https://docs.railgun.org for more information about RAILGUN privacy system
 */
export const initializeEngine = async (args?: {
  walletSource?: string;
  dbPath?: string;
  artifactsPath?: string;
  ppoiNodes?: string[];
}): Promise<void> => {
  // Name for your wallet implementation.
  // Encrypted and viewable in private transaction history.
  // Maximum of 16 characters, lowercase.
  const walletSource = args?.walletSource ?? "quickstart demo";

  // LevelDOWN compatible database for storing encrypted wallets.
  const dbPath = args?.dbPath ?? "./engine.db";

  //   const db = new Level(dbPath);
  const db = createNodeDatabase(dbPath);

  // Whether to forward Engine debug logs to Logger.
  const shouldDebug = true;

  // Persistent store for downloading large artifact files required by Engine.
  const artifactPath = args?.artifactsPath ?? "artifacts-directory";
  const artifactStore = createArtifactStore(artifactPath);

  // Whether to download native C++ or web-assembly artifacts.
  // True for mobile. False for nodejs and browser.
  const useNativeArtifacts = false;

  // Whether to skip merkletree syncs and private balance scans.
  // Only set to TRUE in shield-only applications that don't
  // load private wallets or balances.
  const skipMerkletreeScans = false;

  // Array of aggregator node urls for Private Proof of Innocence (Private POI), in order of priority.
  // Only one is required. If multiple urls are provided, requests will fall back to lower priority aggregator nodes if primary request fails.
  // Please reach out in the RAILGUN builders groups for information on the public aggregator nodes run by the community.
  //
  // Private POI is a tool to give cryptographic assurance that funds
  // entering the RAILGUN smart contract are not from a known list
  // of transactions or actors considered undesirable by respective wallet providers.
  // For more information: https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence
  // (additional developer information coming soon).

  // LEAVE THIS OUT IN PRODUCTION. This is a public aggregator node for testing purposes.
  const poiNodeURLs: string[] = args?.ppoiNodes ?? [
    "https://ppoi-agg.horsewithsixlegs.xyz",
  ];

  // Add a custom list to check Proof of Innocence against.
  // Leave blank to use the default list for the aggregator node provided.
  const customPOILists: POIList[] = [];

  // Set to true if you would like to view verbose logs for private balance and TXID scans
  const verboseScanLogging = true;

  await startRailgunEngine(
    walletSource,
    db,
    shouldDebug,
    artifactStore,
    useNativeArtifacts,
    skipMerkletreeScans,
    poiNodeURLs,
    customPOILists,
    verboseScanLogging
  );
  process.on("SIGINT", async (sigint) => {
    console.log("EXIT DETECTED", sigint);
    await stopRailgunEngine();
    process.exit(0);
  });
};