Learn more about MCWrapper.CLI

A simple .NET Core wrapper for the MultiChain Core blockchain library using Command Line Interface (CLI) clients that interact directly with the MultiChain Core executable files.

Quick Start Notes:

  1. Start a new .NET Core project in Visual Studio 2019
    • Using a Web App or Web API project is easiest since the Dependency Injection (DI) pipeline is already built.
  2. Install the latest stable version of MCWrapper.CLI from the NuGet Package Manager or use the Package Manager command Install-Package MCWrapper.CLI
  3. Follow the steps to download and install the most recent stable version of MultiChain Community according to your operating system.
  4. Complete step one of Getting Started with MultiChain.
  5. We will need the following information from the new MultiChain node.
    • The name of the new blockchain node.
    • The new blockchain node admin's wallet address
      • Run command > multichain-cli {blockchain name} listaddresses
      • There should only be one address listed at this point.
    • The new blockchain node's burn address
      • Run command > multichain-cli {blockchain name} getinfo
    • Next we will add MCWrapper.CLI to our application's service container pipeline.

Configuration for MCWrapper.CLI clients is handled internally via the IOptions pattern. The options pattern uses classes to represent groups of related settings. Visit the GitHub page to preview the CliOptions class.

Configure Services:

Option #1 (preferred): This option is the most secure. Store the MCWrapper.CLI CliOptions as Environment Variables that are automatically loaded on startup. Simply call the AddMultiChainCoreCliServices extension method after configuring the environment. More information is available at our help page for this topic. 

// Startup class of the Web App or Web API
public class Startup
{
  public Startup(IConfiguration configuration)
  {
    Configuration = configuration;
  }

  public IConfiguration Configuration { get; }

  public void ConfigureServices(IServiceCollection services)
  {
    // ... previous code removed for brevity

    services.AddMultiChainCoreCliServices();
  }

  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
    // ... remaining code removed for brevity
  }
}

Option #2: This option is the still somewhat secure, depending on the production environment. Store the MCWrapper.CLI CliOptions as variables on an external configuration file (appsettings.json) that are automatically loaded on startup. Simply call the AddMultiChainCoreCliServices extension method and pass in the IConfiguration Configuration property after configuring the file. More information is available at our help page for this topic. 

// Startup class of the Web App or Web API
public class Startup
{
  public Startup(IConfiguration configuration)
  {
    Configuration = configuration;
  }

  public IConfiguration Configuration { get; }

  public void ConfigureServices(IServiceCollection services)
  {
    // ... previous code removed for brevity

    services.AddMultiChainCoreCliServices(Configuration);
  }

  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
    // ... remaining code removed for brevity
  }
}

Option #3: This option is not secure and should only be used in non-production environments. Explicitly pass the MCWrapper.CLI CliOptions as arguments into the AddMultiChainCoreCliServices extension method and they will be loaded during startup. More information is available at our help page for this topic.

Your values will differ from ours, the values listed below are just an example.

// Startup class of the Web App or Web API
public class Startup
{
  public Startup(IConfiguration configuration)
  {
    Configuration = configuration;
  }

  public IConfiguration Configuration { get; }

  public void ConfigureServices(IServiceCollection services)
  {
    // ... previous code removed for brevity

    services.AddMultiChainCoreCliServices(cliOptions =>
    {
      cliOptions.ChainAdminAddress = "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t";
      cliOptions.ChainBurnAddress = "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS";
      cliOptions.ChainName = "NewChain";
      // if any of the next 3 properties are left null/empty default locations are used
      cliOptions.ChainDefaultColdNodeLocation = string.Empty; // location for cold nodes
      cliOptions.ChainDefaultLocation = string.Empty; // location for hot nodes
      cliOptions.ChainBinaryLocation = string.Empty; // location of MultiChain Core executables
    });
  }

  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
    // ... remaining code removed for brevity
  }
}

Environment Variables:

When using the parameterless AddMultiChainCoreCliServices method MCWrapper.CLI will depend on the local machine's Environment Variable store.

While depending on the Environment Variable store the following variable names are used.

  • Environment variable names required by MCWrapper.CLI
    • ChainAdminAddress (string)
    • ChainBurnAddress (string)
    • ChainName (string)
    • ChainDefaultColdNodeLocation (string)
    • ChainDefaultLocation (string)
    • ChainBinaryLocation (string)

IConfiguration:

When using the IConfiguration argument along with the AddMultiChainCoreCliServices method MCWrapper.CLI will depend on an external JSON Configuration file, generally named appsettings.json.

The external JSON configration file should contain the following variable names along with their values.

Your values will differ from ours, the values listed below are just an example.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*",

  // values required by MCWrapper.CLI's CliOptions class
  "ChainAdminAddress": "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t",
  "ChainBurnAddress": "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS",
  "ChainName": "NewChain",
  // we leave these properties empty to indicate default locations should be used
  "ChainDefaultColdNodeLocation": "",
  "ChainDefaultLocation": "",
  "ChainBinaryLocation": ""
}

Default Locations:

When using the MCWrapper.CLI clients if no value is assigned to the ChainDefaultColdNodeLocation, ChainDefaultLocation, or the ChainBinaryLocation then default values are used within MCWrapper.CLI.

The default locations are as follows.

For Windows Environments

  • The default ChainBinaryLocation is auto-detected at either C:\ or C:\multichain
    • The ChainBinaryLocation is where multichaind.exe, multichain-cli.exe, multichaind-cold.exe, and multichain-util.exe will be stored.
    • MCWrapper.CLI requires access to this location due to not using JSON-RPC HTTP connections. Instead MCWrapper.CLI interacts directly with the MultiChain Core binary files, passing arguments directly to the executables.
    • While MCWrapper.CLI is much slower than MCWrapper.RPC, due to interacting with the executables, MCWrapper.CLI is much more secure since we are not broadcasting JSON-RPC calls via HTTP/HTTPS connections.
  • The default ChainDefaultLocation is auto-detected at C:\Users\<Current Local User>\AppData\Roaming\MultiChain
    • The ChainDefaultLocation is where existing hot nodes are located on the local machine and where new hot nodes can be created by MCWrapper.CLI.
    • Note: MCWrapper.CLI does support creation of new hot or cold nodes and has the ability to start a node since we interact directly with the MultiChain Core executables.MCWrapper.RPC does not support these features since it is limited to the blockchain methods available over JSON-RPC.
  • The default ChainDefaultColdNodeLocation is auto-detected at C:\Users\<Current Local User>\AppData\Roaming\MultiChainCold
    • The ChainDefaultColdNodeLocation more or less serves the same function as the ChainDefaultLocation, except the ChainDefaultColdNodeLocation is for cold nodes instead of hot nodes.

For Linux Environments

Disclaimer: We haven't fully tested or implemented MCWrapper.CLI to work with Linux, we are hoping to accomplish this very soon.

  • The default ChainBinaryLocation is auto-detected at /usr/local/bin
    • The ChainBinaryLocation is where multichaind, multichain-cli, multichaind-cold, and multichain-util will be stored.
    • MCWrapper.CLI requires access to this location due to not using JSON-RPC HTTP connections. Instead MCWrapper.CLI interacts directly with the MultiChain Core binary files, passing arguments directly to the executables.
    • While MCWrapper.CLI is much slower than MCWrapper.RPC, due to interacting with the executables, MCWrapper.CLI is much more secure since we are not broadcasting JSON-RPC calls via HTTP/HTTPS connections.
  • The default ChainDefaultLocation is auto-detected at ./multichain
    • The ChainDefaultLocation is where existing hot nodes are located on the local machine and where new hot nodes can be created by MCWrapper.CLI.
    • Note: MCWrapper.CLI does support creation of new hot or cold nodesand has the ability to start a node since we interact directly with the MultiChain Core executables. MCWrapper.RPC does not support these features since it is limited to the blockchain methods available over JSON-RPC.
  • The default ChainDefaultColdNodeLocation is auto-detected at ./multichain-cold
    • The ChainDefaultColdNodeLocation more or less serves the same function as the ChainDefaultLocation, except the ChainDefaultColdNodeLocation is for cold nodes instead of hot nodes.

For MacOS Environments

No! (maybe someday, perhaps)