monero-ts

The monero-ts data model follows a hierarchical structure representing the Monero blockchain and wallet state. Understanding this hierarchy is essential for navigating blocks, transactions, and fund movements.

Hierarchy Overview

1. Blocks (MoneroBlock): The top-level container.
2. Transactions (MoneroTxWallet): Contained within blocks. Transactions represent the movement of funds and can be categorized by their direction relative to the wallet.
3. Transfers:
   • Incoming Transfers (MoneroIncomingTransfer): Funds arriving in the wallet. A single transaction can contain multiple incoming transfers.
   • Outgoing Transfers (MoneroOutgoingTransfer): Funds leaving the wallet. A transaction typically has one outgoing transfer object.
4. Outputs (MoneroOutputWallet): The specific Monero outputs received by the wallet as part of a transaction.

Key Relationships

• Transactions can have both incomingTransfers and an outgoingTransfer (e.g., when reallocating funds within the same wallet).
• Outgoing Transfers may include destinations (address and amount pairs). Note: This destination information is stored locally within the wallet file and is not part of the on-chain blockchain data.
• Outputs represent the actual UTXO-like entries received by the wallet.

To maintain high security, you can generate and submit transactions without exposing your private spend key to an internet-connected device by using a combination of view-only and offline wallets.

Core Concepts

• View-only wallet: Uses the privateViewKey to scan for received funds. It cannot determine which funds are spent or sign transactions because it lacks the private spend key.
• Offline wallet: Contains the private spend key to sign transactions and determine spent funds, but is not connected to a daemon, meaning it cannot scan for new funds or broadcast transactions.

Transaction Workflow

To sign and submit a transaction securely, follow these steps:

1. Scan: Use a view-only wallet to scan for received funds.
2. Export Outputs: Export outputs from the view-only wallet to the offline wallet.
3. Export Key Images: Export key images from the offline wallet back to the view-only wallet.
4. Create Unsigned TX: Create an unsigned transaction using the view-only wallet.
5. Sign: Sign the transaction using the offline wallet.
6. Broadcast: Broadcast the signed transaction using the view-only wallet or any daemon.

// 1. View-only wallet scans for funds
let viewOnlyWallet = await moneroTs.createWalletFull({
  path: "my_view_only_wallet",
  networkType: moneroTs.MoneroNetworkType.STAGENET,
  primaryAddress: "55bcxMRhBWea6xxsot8moF1rdPprjJR2x4mfnNnTGgBJFgXa4gWXmWAYdUBKiRcJxy9AUAGJEg28DejvWdJU2VgUDrUvCHG",
  privateViewKey: "03d463f03ae547b11dfdf194a07ff82c14a3c6a3de559bd89c9a5e8dc5e9ae02",
  restoreHeight: 573936,
  server: {uri: "http://localhost:38081", username: "superuser", password: "abctesting123"}
});
await viewOnlyWallet.sync();

// 2. Offline wallet created with seed
let offlineWallet = await moneroTs.createWalletFull({
  path: "my_offline_wallet",
  networkType: moneroTs.MoneroNetworkType.STAGENET,
  seed: "spying swept ashtray going hence jester swagger cease spying unusual..."
});

// 3. Transfer data between wallets
let outputsHex = await viewOnlyWallet.exportOutputs();
await offlineWallet.importOutputs(outputsHex);

let keyImageResult = await offlineWallet.exportKeyImages();
await viewOnlyWallet.importKeyImages(keyImageResult.getKeyImages(), keyImageResult.getOffset());

// 4. Create unsigned transaction
let unsignedTx = await viewOnlyWallet.createTx({
  accountIndex: 0,
  address: "56j5AskbiNeeb2UAnS85qpey93GYs4VWB78hazZKGdsKCGHvEXUD6nuMQqXaiiY8SwMWsmtAEXS9kA2ko7hgNtGHKsEWyhv",
  amount: 250000000000n
});

// 5. Sign transaction offline
let signedTxSet = await offlineWallet.signTxs(unsignedTx.getTxSet().getUnsignedTxHex());

// 6. Broadcast via view-only wallet
let txHashes = await viewOnlyWallet.submitTxs(signedTxSet.getSignedTxHex());

To run a web application over HTTPS using self-signed certificates for local development:

1. Generate Localhost Certificates:

   openssl req -x509 -newkey rsa:4096 -keyout localhost-key.pem -out localhost-cert.pem -days 365

   (Note: Dev certificates are available in src/test/browser with password abctesting123)

2. Configure Server: Modify run_server.py to use the generated certificates by uncommenting the relevant lines.

3. Start Server: Run ./bin/start_browser_test_server.sh and provide the certificate password when prompted.

4. Browser Configuration:

   • Chrome: Navigate to chrome://flags/#allow-insecure-localhost and set "Allow invalid certificates for resources loaded from localhost" to Enabled.
   • Firefox: You must first manually authenticate by visiting the RPC endpoints directly in the browser (https://localhost:38081/json_rpc and https://localhost:38083/json_rpc) before accessing your web app at https://localhost:9100/.

To synchronize the state of a view-only wallet and an offline wallet, you must exchange outputs and key images.

Exporting and Importing Outputs

Use exportOutputs() on the view-only wallet to get the hex representation of outputs, then use importOutputs(outputsHex) on the offline wallet.

Exporting and Importing Key Images

Use exportKeyImages() on the offline wallet to get a result containing key images and an offset. Use importKeyImages(keyImages, offset) on the view-only wallet to complete the synchronization.

// Export from view-only
let outputsHex = await viewOnlyWallet.exportOutputs();
// Import to offline
await offlineWallet.importOutputs(outputsHex);

// Export from offline
let keyImageResult = await offlineWallet.exportKeyImages();
// Import to view-only
await viewOnlyWallet.importKeyImages(keyImageResult.getKeyImages(), keyImageResult.getOffset());