Tari Release Notes – v5.0.0

Compatibility

Version 4.9.x wallets remain compatbile with v5.0.0, but upgrading is recommended. Version 5.0.0 wallets are not compabile with nodes prior to version 4.9.

Breaking Changes

Cuckaroo (C29) PoW Algorithm

• The addition of the Cuckaroo (C29) proof-of-work algorithm affects consensus rules; a hard fork is required to activate it on the network.
• The fork block height for Cuckaroo (C29) has been scheduled to block height 95,000 (effective_from_height = 95_000). Node operators and exchanges must upgrade to v5.0.0 before block 95,000 to remain on the correct chain.
• The estimated date of the hard fork is expected to be the 16th Sept, 2025
• Cuckaroo (C29) can now be configured using identifiers cuckaroo, cuckaroo29, c29, or numeric value 3 in configuration or CLI options.

Contact Service Removed

• As of v5.0.0, the entire contacts service (address book, contact liveness/status, invitations) has been removed. All related public APIs, gRPC methods, and configuration options (contacts_auto_ping_interval, contacts_online_ping_window) are deprecated and non-functional.
• Remove or refactor any integration that relies on contacts features to avoid errors. For full details, see PR 7423.

Updated gRPC .proto Bindings

• The block.proto file now includes the POW_ALGOS_CUCKAROO enum variant and removes deprecated structs HistoricalBlocks.
• A new streaming method GetAllCompletedTransactionsStream has been added to wallet.proto, replacing the now-deprecated GetAllCompletedTransactions.
• All client projects consuming gRPC services must regenerate bindings and update references accordingly.

HTTP Wallet Transport Only

• Wallets now connect exclusively via HTTP to base nodes. Legacy Tari comms transports have been removed.
• Legacy CLI configuration (-p "wallet.custom_base_node=...") and related peer configs are no longer supported. Use the following configuration:

  # The URL of the HTTP client to use for base node service requests
  http_server_url="http://127.0.0.1:9000"
  # The fallback url address to use if the base node at http_server_url does not respond
  #fallback_http_server_url = "https://rpc.tari.com"             # MainNet
  #fallback_http_server_url = "https://rpc.stagenet.tari.com"    # StageNet
  #fallback_http_server_url = "https://rpc.nextnet.tari.com"     # NextNet
  #fallback_http_server_url = "https://rpc.localnet.tari.com"    # LocalNet
  #fallback_http_server_url = "https://rpc.igor.tari.com"        # Igor
  #fallback_http_server_url = "https://rpc.esmeralda.tari.com"   # Esmeralda
  
  # For setting the port and external service on the node:
  [base_node.http_wallet_query_service]
  port = 9000
  #external_address = "http://127.0.0.1:9000"

FFI Transport Configuration Removed

• All FFI wallet transport functions for memory, TCP, and Tor are removed. The FFI wallet no longer supports Tor transport. Use HTTP transport instead.
• The wallet_create function now requires a wallet_birthday_offset parameter. Update integrations and bindings accordingly.

gRPC API Renames

• The gRPC API replaces has_done_initial_validation with initial_validation_done. The underlying protocol number remains the same.

Features

Cuckaroo (C29) Implementation

• Full support for the Cuckaroo algorithm (C29) has been added, including siphash-based difficulty, versioned block/header support (V1/V2), mining templates, difficulty estimation, hash-rate tracking, and PoW selection via RPC and miner configuration.

Application Enhancements

Console Wallet:

• Improved wallet connectivity detection with periodic background checks for reliable online/offline status reporting.
• Wallet status reporting now prioritizes wallet-specific connectivity.
• UX enhancements for background sync and status feedback.

Base Node:

• Monitoring loop now checks for the last updated block to avoid redundant updates, with enhanced logging for block height, sync status, and latency.

Network Behaviour

• Proactive peer dialing now excludes seed peers post-bootstrap, improving network reliability and liveness checks.
• Network discovery timeouts for bad or hung RPC connections prevent stalling on discovery.
• Peer sync filters out internal/local addresses, improving peer database accuracy.

Transaction Features & Cancellation

• Mined transactions are now protected from cancellation.
• Checks are performed on pending transactions to unlock encumbered inputs before cancellation.
• CancelTransaction gRPC method extended to support one-sided transactions, improving offline signing workflows.

gRPC Improvements

• New streaming method GetAllCompletedTransactionsStream with filtering and pagination, deprecating GetAllCompletedTransactions. It supports pagination and filtering by status, with improved performance and memory usage.

Wallet and Node Configuration

• New HTTP wallet interface; all queries to base nodes now use HTTP.
• Wallet’s own query service can be configured via [base_node.http_wallet_query_service].
• New CLI utility minotari_utils for inspecting and diagnosing Base Node and Wallet databases.
• CLI and config options for granular UTXO selection, fee estimation (GetFeePerGramStats, GetFeeEstimate), and Replace-by-Fee (RBF) support.

Peer Discovery & Reliability

• Concurrent seed peer discovery for improved performance and reliability.
• Seed peer exclusion in liveness checks for fairer network distribution.

Transaction Lookup

• New minotari_node CLI flag --payref-search allows searching transactions by payment reference.

UTXO Scanning & Sync

• Enhanced sync efficiency and caching with dynamic pagination.
• Global 4 MiB request size limit for input syncing.
• Added syncing of spent output hashes and improved formatting in search_utxo output.

EDNS0 & DNS Reliability

• Added EDNS0, TCP fallback, and shorter DNS timeouts for improved name resolution.

Bug Fixes

• Fixed console wallet crash due to synchronous is_online call blocking on async lock.
• Increased /json_rpc endpoint max request size from 4 KiB to 4 MiB.
• Memo field logic now correctly references payment_id; added debug logging for get_payment_id_address in the gRPC calls.
• Peer DB corruption fix: updates now affect only intended peer; tables (multi_addresses, peers, sqlite_sequence) are cleaned automatically on upgrade.
• UTXO scanning efficiency improved: resolved multiple saves of the same scanned block.
• Esmeralda testnet now correctly accepts V2 blockchain version, resolving node startup and validation issues.
• Network discovery process now transitions out of "Waiting" on "Ready" events, improving reliability.
• TariAddress now supports base58 serialization in human-readable formats, with backward-compatible deserialization for legacy wallet data.

Refactors

• scan_utxos now returns a structured ScanUtxosResult for observability.
• Removed legacy base node config from wallet and base node config files.

Deployment

1. Back up your data — including the Console Wallet and Base Node data directories and configurations.

2. Stop all running services — Console Wallet, Base Node, and any FFI-integrated wallets.

3. Remove or refactor contact-related code and configuration — the Contact Service has been completely removed. Any usage of contact APIs, invitations, or liveness/status checks will now fail. Delete or disable deprecated configuration options:

   • contacts_auto_ping_interval
   • contacts_online_ping_window
     Review and update any integrations (e.g. exchanges or external wallets) that rely on contact features.

4. Update node configuration and CLI usage:

   • You can now configure the mining algorithm using cuckaroo, cuckaroo29, c29, or 3. Example:
     ./minotari_node -p mining.pow_algo=cuckaroo
   • Use the new --payref-search flag to search transactions by payment reference. Example:
     ./minotari_node --payref-search <PAYMENT_REFERENCE>
   • Update wallet configuration to use new HTTP interface and remove legacy CLI flags such as -p "wallet.custom_base_node=...".
   • Ensure your configuration uses:

     http_server_url = "http://127.0.0.1:9000"
     fallback_http_server_url = "https://rpc.esmeralda.tari.com"
     
     [base_node.http_wallet_query_service]
     #port = 9000
     #external_address = "http://127.0.0.1:9000"

5. Update gRPC clients and .proto files:

   • Regenerate bindings using updated .proto files.
   • The block.proto includes the new POW_ALGOS_CUCKAROO enum variant and removes the deprecated HistoricalBlocks field.
   • The wallet.proto adds GetAllCompletedTransactionsStream, a streaming alternative to the deprecated GetAllCompletedTransactions.
   • Ensure all references to the HistoricalBlocks field are removed or updated accordingly.
   • The GetAllCompletedTransactionsStream method enables paginated access to completed transactions.

6. FFI integrations:

   • Update calls to wallet_create to include the new wallet_birthday_offset parameter.
   • Remove any use of deprecated transport configuration functions (memory, TCP, or Tor).
   • Ensure the Tor transport is no longer in use.
   • Recompile or regenerate FFI bindings as needed.

7. Upgrade before block height 95,000 — a breaking consensus change will activate at this height to enable the Cuckaroo (C29) fork. Nodes running older versions will fail to validate blocks beyond this point and fall off the mainnet chain.

8. Install the latest binaries for both the Base Node and Console Wallet.

9. Restart all services — Base Node, Console Wallet, and FFI-integrated wallets.

10. Verify operation — Check logs, confirm wallet synchronization, and validate gRPC/FFI functionality.