Learn more about MCWrapper

A simple .NET Core wrapper for the MultiChain Core blockchain library using JSON-RPC (RPC) and Command Line Interface (CLI) clients.

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 from the NuGet Package Manager or use the Package Manager command Install-Package MCWrapper
  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
    • The JSON-RPC port number (printed to the console when -deamon command is used in step 4),
    • The new MultiChain JSON-RPC username (usually multichainrpc by defaul),
    • The new MultiChain JSON-RPC password
      • The JSON-RPC username and password can be located in the multichain.conf file of the new MultiChain blockchain node.
    • Next we will add MCWrapper to our application's service container pipeline.

MCWrapper was originaly a single project that became fairly large and unwieldy to maintain, so I broke the project into small packages. MCWrapper consists of two projects, MCWrapper.RPC and MCWrapper.CLI, that can each be used together under the MCWrapper package or independent of each other and the main MCWrapper package. When configuring MCWrapper each client must be configured separately, MCWrapper.RPC and MCWrapper.CLI.

Configuration for the MCWrapper.RPC and MCWrapper.CLI clients is handled internally via the IOptions pattern. The options pattern uses classes to represent groups of related settings. Visit the respective GitHub pages to preview the RpcOptions and CliOptions classes.

Configure Services:

Option #1 (preferred): This option is the most secure. Store the MCWrapper RpcOptions and CliOptions as Environment Variables that are automatically loaded on startup. Simply call the AddMultiChainCoreServices 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

		// First option, implement all MCWrapper RPC and CLI clients at once
		services.AddMultiChainCoreServices();

		// Another option is to implement the RPC and CLI clients separately,
		// instead of using the AddMultiChainCoreServices method.
		// Perhaps you only require one set of clients or the other, that is supported as well.
		services.AddMultiChainCoreRpcServices();
		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 RpcOptions and CliOptions as variables on an external configuration file (appsettings.json) that are automatically loaded on startup. Simply call the AddMultiChainCoreServices extension method 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

		// First option, implement all MCWrapper RPC and CLI clients at once
		services.AddMultiChainCoreServices(Configuration);

		// Another option is to implement the RPC and CLI clients separately,
		// instead of using the AddMultiChainCoreServices method.
		// Perhaps you only require one set of clients or the other, that is supported as well.
		services.AddMultiChainCoreRpcServices(Configuration);
		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 RpcOptions and CliOptions as arguments into the AddMultiChainCoreServices 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

		// First option, implement all MCWrapper RPC and CLI clients at once
		services.AddMultiChainCoreServices(rpcOptions => 
		{
			rpcOptions.ChainAdminAddress = "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t";
			rpcOptions.ChainBurnAddress = "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS";
			rpcOptions.ChainPassword = "EmjbtUBfbg2SikAXVnAJSQKmbeZhxbpSopsVKk58zrE";
			rpcOptions.ChainUsername = "multichainrpc";
			// localhost or a remote node's address eg. NewChain@192.168.1.1:7764
			rpcOptions.ChainHostname = "localhost";
			rpcOptions.ChainName = "NewChain";
			rpcOptions.ChainRpcPort = 7764;
			// default is HTTP if this is left empty
			rpcOptions.ChainSslPath = string.Empty;
			rpcOptions.ChainUseSsl = false;
		},
		cliOptions =>
		{
			cliOptions.ChainAdminAddress = "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t";
			cliOptions.ChainBurnAddress = "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS";
			cliOptions.ChainName = "NewChain";
			// if empty default location is used
			cliOptions.ChainDefaultColdNodeLocation = string.Empty;
			cliOptions.ChainDefaultLocation = string.Empty;
			cliOptions.ChainBinaryLocation = string.Empty;
		});

		// Another option is to implement the RPC and CLI clients separately,
		// instead of using the AddMultiChainCoreServices method.
		// Perhaps you only require one set of clients or the other, that is supported as well.
		services.AddMultiChainCoreRpcServices(rpcOptions =>
		{
			rpcOptions.ChainAdminAddress = "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t";
			rpcOptions.ChainBurnAddress = "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS";
			rpcOptions.ChainPassword = "EmjbtUBfbg2SikAXVnAJSQKmbeZhxbpSopsVKk58zrE";
			rpcOptions.ChainUsername = "multichainrpc";
			// localhost or a remote node's address eg. NewChain@192.168.1.1:7764
			rpcOptions.ChainHostname = "localhost";
			rpcOptions.ChainName = "NewChain";
			rpcOptions.ChainRpcPort = 7764;
			// default is HTTP if this is left empty
			rpcOptions.ChainSslPath = string.Empty;
			rpcOptions.ChainUseSsl = false;
		});

		services.AddMultiChainCoreCliServices(cliOptions =>
		{
			cliOptions.ChainAdminAddress = "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t";
			cliOptions.ChainBurnAddress = "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS";
			cliOptions.ChainName = "NewChain";
			// if empty default location is used
			cliOptions.ChainDefaultColdNodeLocation = string.Empty;
			cliOptions.ChainDefaultLocation = string.Empty;
			cliOptions.ChainBinaryLocation = string.Empty;
		});
	}

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

Environment Variables:

When using the parameterless AddMultiChainCoreServices method or the AddMultiChainCoreRpcServices and AddMultiChainCoreCliServices methods MCWrapper 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 both MCWrapper.RPC and MCWrapper.CLI
    • ChainAdminAddress (string)
    • ChainBurnAddress (string)
    • ChainName (string)
  • Variable names required specifically by MCWrapper.RPC clients
    • ChainPassword (string)
    • ChainUsername (string)
    • ChainHostname (string)
    • ChainRpcPort (int)
    • ChainSslPath (string)
    • ChainUseSsl (bool)
  • Variable names required specifically by MCWrapper.CLI clients
    • ChainDefaultColdNodeLocation (string)
    • ChainDefaultLocation (string)
    • ChainBinaryLocation (string)

IConfiguration:

When using the IConfiguration argument along with the AddMultiChainCoreServices method or the AddMultiChainCoreRpcServices and AddMultiChainCoreCliServices methods MCWrapper 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 shared between RpcOptions and CliOptions
  "ChainAdminAddress": "1F5WvCAwc9sX6ZMJKE8GRZA6UQQPnxgB8FbU7t",
  "ChainBurnAddress": "1XXXXXXXDXXXXXXX7bXXXXXXVsXXXXXXXCT2tS",
  "ChainName": "NewChain",

  // RpcOptions start here
  "ChainPassword": "EmjbtUBfbg2SikAXVnAJSQKmbeZhxbpSopsVKk58zrE",
  "ChainUsername": "multichainrpc",
  "ChainHostname": "localhost",
  "ChainRpcPort": 7764,
  "ChainSslPath": "",
  "ChainUseSsl": false,

  // CliOptions start here, we leave them 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)