Skip to content

Latest commit

 

History

History
158 lines (102 loc) · 4.76 KB

README.md

File metadata and controls

158 lines (102 loc) · 4.76 KB
Raw

Ether.BlazorProvider

This library provides an interface to web3 compatible browser plugins like MetaMask for use within Blazor WebAssembly.

Usage

Configuration

Basic MetaMask configuration

builder.Services.AddEtherProviderRegistry(config => config.AddMetaMaskProvider());

Custom configuration example

builder.Services.AddEtherProviderRegistry( config =>
    {
        // quick metamask configuration with custom name
        config.AddMetaMaskProvider("my-metamask");

        // example of disabling events
        //options.AddMetaMaskProvider("my-metamask").Configure(x => x.EnableEvents = false);

        // custom  configure
        config.AddProvider("ronin")
            .Configure(x =>
            {
                x.ProviderPath = "ronin.provider";
                x.SupportsEip1193 = false;
                x.SupportsEip1102 = false;
            });
    }
);

The ProviderPath property is the global javascript object path to the provider. For MetaMask the global object is "window.ethereum", when configuring the ProviderPath the "window" part should be removed. So for MetaMask is would be x.ProviderPath = "ethereum";

Using the provider

Inject the registry into a Razor page:

@using Ether.BlazorProvider
@inject IEtherProviderRegistry _registry;

Get a single provider (this only applies if one provider has been configured)

var myProvider = await _registry.GetSingleProvider();

Get a provider by name (acquire the provider using the configured name)

var myProvider = await _registry.GetProvider("my-metamask");

Check if the provider is available:

bool isAvailable = await myProvider.IsAvailable();

This checks if the underlying javascript object supplied by the browser extension exists.

Connect to a provider:

string connectedAccount = await myProvider.Connect();

The currently selected account address is returned if the connect is successful, otherwise exceptions can be thrown if access is denied. Connect() should be called before using any of the other methods.

For providers which have been configured with SupportsEip1102 = true; (the default) a "eth_requestAccounts" RPC call is made.

For providers which have been configured with SupportsEip1102 = false; a "eth_accounts" RPC is made.

Connect can take a optional timeout parameter which will results in an exception being thrown if the timeout occurs.

To get the account or chain ID:

string account = await myProvider.GetAccount();
long chainId = await myProvider.GetChainId();

General RPC Calls:

To make general Ethereum RPC calls use Request(). The methods and parameters of the RPC calls must conform to the Ethereum RPC specification.

There are two signatures to the Request() call. One that takes an object and one that takes a JSON string. The JSON string must conform to the Ethereum RPC specification.

var request = new RpcRequestMessage(1, "eth_getBalance", Account, "latest");
RpcResponseMessage response = await myProvider.Request(request);

Events:

The following events are available:

  • AccountChanged - this is fired if the user changes the current account
  • ChainIdChanged - this is fired of the user changes the current network

These events are only available if the configured provider supports EIP 1193, MetaMask does support EIP 1193

// add an event handler
myProvider.AccountChanged += OnAccountChanged;

// remove a event handler (it is good practice to remove handlers when they are no longer required)
myProvider.AccountChanged -= OnAccountChanged;


private void OnAccountChanged(string account)
{
    // todo
}

Signer:

The signer interface can be used to sign messages.

ISigner signer = myProvider.GetSigner();

// this call will first do a RPC call to get the selcted address
string signedMessage = await signer.SignMessage("message to sign");

// use if you are tracking the account address
//string signedMessage = await signer.SignMessage("message to sign",address);

Sample App

See Ether.BlazorProvider.Sample for a simple working example

Acknowledgements

The following projects provided inspiration.

Warning

Executing blockchain transactions are irreversible. Ensure sufficient testing has been done using testnet's before any live transactions are attempted.

This software is provided as is with no warranty of any kind, see the license

Comments / Suggestions

Feel free to suggest any improvements or bug fixes.