Global Variables and State History

Introduction

Global Variables in MultiChain allow users to store and update a single “state” value. While you can always retrieve the most recent value, the blockchain also maintains a complete historical record of every previous value the variable has held, along with the timestamp and the address that performed the update.

library(multichainr)

# Set the path to your MultiChain binaries
mc_set_path(Sys.getenv("MULTICHAIN_PATH"))

1. Node Initialization

We start by setting up a local testing environment.

chain_name <- "vars_demo_chain"

# Create and start the node
mc_node_init(chain_name)
mc_node_start(chain_name)

# Wait for the node to initialize
Sys.sleep(3) 

# Connect to the local node
config <- mc_get_config(chain_name)
conn <- mc_connect(config)

2. Creating a Global Variable

When creating a variable, you can decide if it is open (can be updated by anyone with create permissions) or restricted to admins.

var_name <- "system_config"

# Create a variable that is open for updates
# We can also provide an optional initial value
initial_val <- list(version = "1.0.0", status = "initializing")

mc_create_variable(conn, var_name, open = TRUE, value = initial_val)

# Retrieve basic info about the variable
info <- mc_get_variable_info(conn, var_name)
print(info)

3. Updating State

Updating a variable is as simple as providing a new value. This value can be a string, a number, or a complex nested list (which is automatically converted to JSON).

# Update 1: Change status to 'active'
mc_set_variable_value(conn, var_name, list(version = "1.0.0", status = "active"))

Sys.sleep(1) # Brief pause to simulate time passing

# Update 2: Upgrade version and add new fields
new_config <- list(
  version = "1.1.0",
  status = "active",
  last_maintenance = "2025-04-02",
  threshold = 85
)

mc_set_variable_value(conn, var_name, new_config)

4. Retrieving the Current Value

The mc_get_variable_value function always returns the most recent state of the variable.

current_val <- mc_get_variable_value(conn, var_name)

cat("Current System Version:", current_val$version, "\n")
cat("Current Status:", current_val$status, "\n")

5. Auditing State History

The true power of Global Variables lies in the mc_get_variable_history function. This returns a data frame containing every version of the variable ever published.

# Retrieve the full history of changes
history_df <- mc_get_variable_history(conn, var_name, verbose = TRUE)

# The data frame includes the value, the blocktime, and the transaction ID
print(history_df[, c("blocktime", "value")])

# You can see exactly how the 'threshold' or 'status' changed over time
# for auditing or debugging purposes.

6. Cleanup

Always shut down the node and clean up the environment after testing.

# Stop the node
mc_node_stop(conn)
Sys.sleep(2)

# Determine data directory
if (.Platform$OS.type == "windows") {
  base_dir <- file.path(Sys.getenv("APPDATA"), "MultiChain")
} else if (Sys.info()["sysname"] == "Darwin") {
  base_dir <- file.path(Sys.getenv("HOME"), "Library/Application Support/MultiChain")
} else {
  base_dir <- file.path(Sys.getenv("HOME"), ".multichain")
}

chain_dir <- file.path(base_dir, chain_name)
if (dir.exists(chain_dir)) {
  unlink(chain_dir, recursive = TRUE)
}

Summary

In this vignette, we demonstrated how to:

1. Initialize State: Using mc_create_variable to define a new on-chain data point.
2. Modify State: Using mc_set_variable_value to push updates (JSON-compatible).
3. Access State: Using mc_get_variable_value for high-speed retrieval of the current “truth”.
4. Audit State: Using mc_get_variable_history to reconstruct the timeline of changes for a specific variable.