Unithereum

This UPM package enables Unity projects to interact with Ethereum-like blockchain nodes.

Installation

Your project has to be configured to use the OpenUPM registry for the dependencies. If you have not already done so, you can add the OpenUPM registry by opening the Unity Package Manager, clicking the cog icon located on the left side of the search bar in the top right corner, and selecting Advanced Project Settings. In the window that appears, click the + button on the bottom left of the Scoped Registries section and enter the following information:

• Name: OpenUPM
• URL: https://package.openupm.com
• Scope(s) (add entries with the + button on the bottom right):
  • com.openupm
  • org.nuget.microsoft.extensions.logging.abstractions
  • org.nuget.portable.bouncycastle
  • org.nuget.system.buffers
  • org.nuget.system.memory
  • org.nuget.system.numerics.vectors
  • org.nuget.system.runtime.compilerservices.unsafe

Alternatively, you may use the UnityNuGet registry which provides a curated list of NuGet packages as UPM packages and includes the required dependencies instead of OpenUPM. To add the UnityNuGet registry, follow the same steps as above, but use the following information:

• Name: UnityNuGet
• URL: https://unitynuget-registry.azurewebsites.net
• Scope(s): org.nuget

Also, note that Unithereum requires Newtonsoft.Json as a dependency, but does not list it as a dependency in the package manifest to avoid conflicts in case it is provided in other means. If you do not have other packages that depend on Newtonsoft.Json installed, you may install it by adding the com.unity.nuget.newtonsoft-json package by name in the Unity Package Manager.

Then, open the Unity Package Manager and add a package from a git URL. The URL for this package is:

https://github.com/planetarium/Unithereum.git?path=/Unity/Assets/Plugins/Unithereum

Code Generation

This package contains a code generation script that creates C# classes that can be used to interact with smart contracts from ABI and BIN (optional) artifacts generated by solc. Code is generated whenever .abi and .bin files are added or modified in the Assets/ directory, or any subdirectory therein. To force regeneration, you may reimport the desired files in the Unity Editor. Note that code for preexisting .abi files will not be generated until they are reimported. You may also use the Unithereum > Regenerate All... menu to force import of all .abi and .bin files inside the Assets/ directory and regenerate respective code. Note that this action will clear the contents of the Assets/ContractServices/ directory.

The generated code is placed in the Assets/ContractServices/ directory, and will be under the {ProductName}.ContractServices assembly. Please note that the ProductName will be sanitized to qualify as a C# identifier name.

Configuration

You may override the default configuration with a codegen.config.json file in the Unity project root. Available options are dotnetPath, nsPrefix, outputDir, and contractsDir.

Ensure that nsPrefix conforms to the C# identifier name constraints. Also, note that the outputDir is relative to the Assets/ directory of the Unity project.

Set contractsDir if you want to place .abi files in specific directory or outside Assets/. It consumes relative path to Unity project root directory. However, automatic file detection and generation won't work if you put .abi files outside Assets/ dir. You may need to manually trigger Unithereum > Regenerate All... menu. Use with caution.

Example

{
  "dotnetPath": "/usr/local/bin/dotnet",
  "nsPrefix": "Test.Contracts",
  "outputDir": "generated",
  "contractsDir": "contracts"
}

Building

To build this project, you must have the Unity Editor 2021.3.19f installed. Please make sure that Unity .meta files are generated before updating the built package at Assets/Plugins/Unithereum (e.g. Open Unity project at Unity with the Unity Editor and reimport new assets).

Contribution

Setup pre-commit hook

We use dotnet format and csharpier to keep code formatted consistently. Also, we provide pre-commit config to ensure sources are formatted before each commits. If you are interested in contributing this project, we highly recommend to setup pre-commit git hook using provided .pre-commit-config.yaml.

You can install pre-commit from pip, brew, or conda package managers. Refer https://pre-commit.com/#install to detailed installation steps.

After that, run pre-commit install to set up git hook at this repository. Now the git hook will run each commits, and your changes will be formatted automatically.