Balance and Sync Callbacks

RAILGUN private balances update continuously as new merkle tree commitments are received.

This process involves two callback events: onMerkletreeScanCallback and onBalanceUpdateCallback. You can set these callbacks right after the Engine initialization from Step 1 of the Getting Started section.

Example: Set callbacks for scan progress and balance updates

// main.js
...
import {
  ...
  setOnUTXOMerkletreeScanCallback,
  setOnTXIDMerkletreeScanCallback,
  setOnBalanceUpdateCallback,
} from '@railgun-community/wallet';
import {
  MerkletreeScanUpdateEvent,
  RailgunBalancesEvent,
} from '@railgun-community/shared-models';

...

const onUTXOMerkletreeScanCallback = (eventData: MerkletreeScanUpdateEvent) => {
  // Will get called throughout a private balance scan.
  
  // Handle updates on scan progress and status here, i.e. progress bar or loading indicator in the UI.
};

const onTXIDMerkletreeScanCallback = (eventData: MerkletreeScanUpdateEvent) => {
  // Will get called throughout a private balance scan.
  
  // Handle updates on scan progress and status here, i.e. progress bar or loading indicator in the UI.
};

const onBalanceUpdateCallback = (balancesFormatted: RailgunBalancesEvent) => {
  // Will get called at the end of a private balance scan for a RAILGUN wallet
  // for each txidVersion and balanceBucket (explained below).
  
  // RailgunBalancesEvent includes:
  // *txidVersion: TXIDVersion;
  // chain: Chain;
  // railgunWalletID: string;
  // *balanceBucket: RailgunWalletBalanceBucket;
  // erc20Amounts: RailgunERC20Amount[];
  // nftAmounts: RailgunNFTAmount[];
  
  // *txidVersion: Currently, there is only the V2_PoseidonMerkle txidVersion. In the future,
  // with the launch of V3_PoseidonMerkle, there will be options to migrate balances
  // from V2 to V3.
  
  // *balanceBucket: With the Private Proof of Innocence system, balances are categorized
  // into "Spendable", "ShieldBlocked", "ShieldPending", "ProofSubmitted", "MissingInternalPOI",
  // "MissingExternalPOI", and "Spent". As funds move through the Private POI system, as
  // explained here: https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence,
  // they will automatically end up in the "Spendable" category, which is when they are
  // able to be used in private DeFi interactions.
  
  // Handle updates on the private token balances of each available RAILGUN wallet here.
};

// App launch
try {
  initializeEngine();
  ...
  setOnBalanceUpdateCallback(onBalanceUpdateCallback);
  setOnUTXOMerkletreeScanCallback(onUTXOMerkletreeScanCallback);
  setOnTXIDMerkletreeScanCallback(onTXIDMerkletreeScanCallback);
  ...
} catch (err) {
  // Handle err
}