Overview

MetaMask is a browser extension wallet used by over 30M users to interact for web3 applications (dApps). Historically, it only supported interactions with EVM-based chains, but now also supports the FIO Protocol utilizing Snaps, which extend the MetaMask functionality.

FIO Wallet Snap enables MetaMask users to securely host FIO Private Key in the MetaMask wallet and sign any transaction to the FIO Chain. The FIO Wallet Snap has been whitelisted by Consensys and is available in production version of MetaMask.

This allows any web-based dApp (Snaps are not yet available in mobile version of MetaMask) to very easily add support for FIO Protocol, without having to worry about private key management or signing/packing of transactions.

The following guide shows how easy it is to interact with FIO Wallet Snap from withing your dApp.

Interacting with MetaMask

If you are not familiar with how your dApp interacts with MetaMask, checkout these Developer Resources for an in-depth description.

Install

For Typescript install @metamask/providers package to the project.

npm install @metamask/providers

If you want to use the signNonce method you will also need @fioprotocol/fiojs.

npm install @fioprotocol/fiojs

Snap interaction

Connect to Snap

wallet_requestSnaps RPC method is invoked through the [window.ethereum.request](https://docs.metamask.io/wallet/reference/provider-api/#request) method to communicate with MetaMask and to connect to the user's FIO Wallet Snap. If the Snap is not installed, the user will be prompted to install it.

Request Parameters

Parameter	Description	Value
`snapId`	Id of the snap	`npm:@fioprotocol/fio-wallet-snap`
`method`	Method	`wallet_requestSnaps`
`params`	Object with parameters	`version`:`1.0.2` - For latest version check https://www.npmjs.com/package/@fioprotocol/fio-wallet-snap

Response Parameters

Parameter	Description	Value
`version`	Version of Snap, should match request.	`1.0.2`
`id`	Id of the snap, should match request.	`npm:@fioprotocol/fio-wallet-snap`
`enabled`	Is Snap is enabled by user.	`true`
`blocked`	Is Snap blocked by user.	`false`

FIO Wallet Snap RPC methods

showPublicKey

Returns FIO Public Key stored at requested derivation index.

Request Parameters

Parameter	Description	Value
`derivationIndex`	Derivation index for FIO Public Key path.	0

Response

Promise, e.g. FIO5WRaZ4jtVMzoNPEYPYSy4qCByJJ75x9BwznayDhnLhZnYcrgK5.

signTransaction

Returns a signed and packed transaction.

Request Parameters

Group	Parameter	Required	Type	Description
`params`	`apiUrl`	Yes	String	Url of the FIO API server, e.g. `https://fio.blockpane.com/v1/`
`params` => `actionParams`	`account`	Yes	String	Account name for contract matching the specific action on FIO Chain, e.g. for registering FIO Handle: `fio.address`. For more details see FIO Chain Action API.
`params` => `actionParams`	`action`	Yes	String	Action name of the specific action on FIO Chain, e.g. for registering FIO Handle: `regaddress`. For more details see FIO Chain Action API .
`params` => `actionParams`	`authActor`	No	String	The actor that will be used for authorization. Typically it's the actor which is a hash of the FIO Public Key of the user.
`params` => `actionParams`	`contentType`	No	String	Required when `action` is: `newfundsreq` or `recordobt` and set as follows: `newfundsreq`: `new_funds_content` `recordobt`: `record_obt_data_content`
`params` => `actionParams`	`content`	No	Object	Required when `action` is: `newfundsreq` or `recordobt` and set to `content` fields as described in `[newfundsreq](/reference/new_funds_request)` and `[recordobt](/reference/record_obt_data)`
`params` => `actionParams`	`payeeFioPublicKey`	No	String	Required when `action` is: `recordobt`. FIO Public key of the wallet who will receive an OBT data record. This is used for encryption.
`params` => `actionParams`	`payerFioPublicKey`	No	String	Required when `action` is: `newfundsreq`. FIO Public key of the wallet who will receive a FIO Request. This is used for encryption .
`params` => `actionParams`	`data`	Yes	Object	Object with action parameters as defined in FIO Chain Action API. `actor` may be omitted and will be added automatically to match the actor associated with the signing key.
`params` => `actionParams`	`dataActor`	No	String	The actor that will passed in `data`. Typically it's the actor which is a hash of the FIO Public Key of the user.
`params` => `actionParams`	`derivationIndex`	Yes	Number	Derivation index of the wallet. Should be positive integer. Typically 0.
`params` => `actionParams`	`id`	No	String	Transaction ID that you want to sign. This is helpful for error handling.
`params` => `actionParams`	`timeoutOffset`	No	String	Time offset for transaction expiration in milliseconds. By default, this is set to 60000 milliseconds, equivalent to 1 minute.

Response

Return successed and failed to indicate which transactions were signed and packed successfully and which failed. The transactions will be signed and packed so that they can be pushed directly to the chain using /push_transaction.

Response Example

{
  "successed":[
    {
      "signatures":["SIG_K1_KXgtavUZS9zHsawnVDebi1kTDQDrcp9v573E7SdBudBTZZZVwR3fKbp6YQ8PXnnAC9KesLViZK7KhDvUCrzaZzXthN6g2T"],
      "compression":0,
      "packed_context_free_data":"",
      "packed_trx":"1f651466e314e2f94b2f00000000010000980ad20ca85be0e1d195ba85e7cd01c0c54e0d35c1884800000000a8ed32325f3546494f36713361537444335968744b56367662367a657a764275786b5951446e6735523274656259454354566755654343685a594b00e40b5402000000a506a25b00000000c0c54e0d35c188481064617368626f6172644066696f75617400"
   }
  ],
  "failed":[]
}

signNonce

Returns a signature of a supplied nonce. This can be used to confirm that the user is holding the associated FIO Private key and can be used as for example as a way to log-in.

Request Parameters

Parameter	Required		Type	Description
`nonce`	Yes		String	Nonce to sign.
`derivationIndex`	Yes		String	Derivation index of the wallet. Should be positive integer. Typically 0.

Response

Returns promise with signature.

Response Example

SIG_K1_K2RmeXdf5AUReHvJRv1vAS49Ng7Z7Dg1e2GTLRraADj7zvuCNtes9M4wPWbk1iiL4QeVoF3ywMQa8kLzegyb8zQ29Luzze

decryptContent

Returns decrypted content from FIO Request or FIO Data.

Request Parameters

Parameter	Required	Type	Description
`content`	Yes	String	Encrypted blob. The `content` field from FIO Request or FIO Data.
`encryptionPublicKey`	Yes	String	FIO Public key of the other wallet that was used for encryption. This is returned by /get_pending_fio_requests and /get_obt_data. This is used for decryption.
`contentType`	Yes	Striring	Set as follows: `newfundsreq`: `new_funds_content` `recordobt`: `record_obt_data_content`

Response

Return decrypted content object as defined in FIO Request or FIO Data.

Examples

Connect and get FIO Public Key

This is a simple HTML/JavaScript example that will connect to the Snap and display the FIO Public Key. Click Result to run it right here.

Sign Transaction

This example will trigger a request to MetaMask to sign a Map Public Address transaction and upon user approval, it will broadcast it to the FIO Chain.

Please note that in this example the FIO Private Key in MetaMask must own the supplied FIO Handle for this call to work.