token-gas-relayer

Gas relayer mplementation for economic abstraction. This project consists of two elements:

• gas-relayer: nodejs service that listens to whisper on a symmetric key, with specific topics, and processes any transaction.
• test-dapp: DApp created for testing purposes. It allows the easy creation of the messages expected by the service.

Installation

• geth is required for installation
• Install the latest develop version of embark: npm install -g https://github.com/embark-framework/embark.git
• If running a development version of the gas relay

cd test-dapp
chmod a+x setup_dev_env.sh
npm install
embark reset
embark blockchain

• When Embark finishes loading, execute embark run && ./setup_dev_env.sh to create the test account

Node

Before executing this program, config/config.json must be setup and npm install needs to be executed. Important values to verify are related to the node configuration, just like:

• Host, port and protocol to connect to the geth node
• Host, port and protocol Ganache will use when forking the blockchain for gas estimations and other operations
• Wallet account used for processing the transactions
• Symmetric key used to receive the Whisper messages
• Accepted tokens information
• Contract configuration

This program is configured with the default values for a embark installation run from 0

A geth node running whisper (via -shh option) is required. To execute the gas-relayer, you may use any of the following three methods.

npm start
node src/service.js
nodemon src/service.js

Test DApp

To run the test dapp, use embark run and then browse http://localhost:8000/index.html.

The gas relayer service needs to be running, and configured correctly to process the transactions. Things to take in account are: the account used in embark, and the contract addresses.

(TODO: update testnet configuration to guarantee the contract addresses don't change)

The relayer

A node that wants to act as a relayer only needs to have a geth node with whisper enabled, and an account with ether to process the transactions. This account and node need to be configured in ./config/config.js.

The relayer will be subscribed to receive messages in a specific symkey (this will change in the future to use ENS), and will reply back to both availability and transaction requests

Using the gas relayer

The protocol

Sending a message to the gas relayer network (all accounts and privatekeys should be replaced by your own test data)

shh.post({
    symKeyID: SYM_KEY,  // If requesting availability
    pubKey: PUBLIC_KEY_ID,  // If sending a transaction
    sig: WHISPER_KEY_ID, 
    ttl: 1000, 
    powTarget: 1, 
    powTime: 20, 
    topic: TOPIC_NAME, 
    payload: PAYLOAD_BYTES
}).then(......)

• symKeyID: SYM_KEY must contain the whisper symmetric key used. It is shown on the console when running the service with node. With the provided configuration you can use the symmetric key 0xd0d905c1c62b810b787141430417caf2b3f54cffadb395b7bb39fdeb8f17266b. Only used when asking for relayer availability.
• pubKey: PUBLIC_KEY_ID. After asking for availability, once the user decides on a relayer, it needs to set the pubKey attribute with the relayer public key (received in the availability reply in the sig attribute of the message).
• WHISPER_KEY_ID represents a keypair registered on your node, that will be used to sign the message. Can be generated with web3W.shh.newKeyPair()
• TOPIC_NAME must contain one of the topic names generated based on converting the contract name to hex, and taking the first 8 bytes. For the provided configuration the following topics are available:
• • IdentityGasRelay: 0x4964656e
• • SNTController: 0x534e5443
• PAYLOAD_BYTES a hex string that contains details on the operation to perform.

Polling for gas relayers

The first step is asking the relayers for their availability. The message payload needs to be the hex string representation of a JSON object with a specific structure:

const payload = web3.utils.toHex({
        'contract': "0xContractToInvoke",
        'address': web3.eth.defaultAccount,
        'action': 'availability',
        'token': "0xGasTokenAddress",
        'gasPrice': 1234
    });

• contract is the address of the contract that will perform the operation, in this case it can be an Identity, or the SNTController.
• address The address that will sign the transactions. Normally it's web3.eth.defaultAccount
• gasToken: token used for paying the gas cost
• gasPrice: The gas price used for the transaction

This is a example code of how to send an 'availability' message:

const whisperKeyPairID = await web3W.shh.newKeyPair();

const msgObj = { 
    symKeyId: "0xd0d905c1c62b810b787141430417caf2b3f54cffadb395b7bb39fdeb8f17266b", 
    sig: whisperKeyPairID,
    ttl: 1000, 
    powTarget: 1, 
    powTime: 20, 
    topic: "0x4964656e", 
    payload: web3.utils.toHex({
        'contract': "0x692a70d2e424a56d2c6c27aa97d1a86395877b3a",
        'address': web3.eth.defaultAccount
        'action': 'availability',
        'gasToken': "0x744d70fdbe2ba4cf95131626614a1763df805b9e",
        'gasPrice': 40000000000 // 40 gwei equivalent in SNT
    })
};

        
web3.shh.post(msgObj)
.then((err, result) => {
    console.log(result);
    console.log(err);
});

When it replies, you need to extract the sig attribute to obtain the relayer's public key

Sending transaction details

Sending a transaction is similar to the previous operation, except that we send the message to an specific node, we use the action transaction, and also we send a encodedFunctionCall with the details of the transaction to execute.

From the list of relayers received via whisper messages, you need to extract the message.sig to obtain the pubKey. This value is used to send the transaction to that specific relayer.

encodedFunCall is the hex data used obtained from web3.eth.abi.encodeFunctionCall for the specific function we want to invoke.

If we were to execute callGasRelayed(address,uint256,bytes,uint256,uint256,uint256,address,bytes) (part of the IdentityGasRelay) in contract 0x692a70d2e424a56d2c6c27aa97d1a86395877b3a, with these values: "0x11223344556677889900998877665544332211",100,"0x00",1,10,20,"0x1122334455112233445511223344551122334455", "0x1122334455", PAYLOAD_BYTES can be prepared as follows:

// The following values are created obtained when polling for relayers
const whisperKeyPairID = await web3W.shh.newKeyPair();
const relayerPubKey = "0xRELAYER_PUBLIC_KEY_HERE";
// ...
// ...
const jsonAbi = ABIOfIdentityGasRelay.find(x => x.name == "callGasRelayed");

const funCall = web3.eth.abi.encodeFunctionCall(jsonAbi,
                [
                    "0x11223344556677889900998877665544332211", 
                    100, 
                    "0x00",
                    1,
                    10,
                    20,
                    "0x1122334455112233445511223344551122334455",
                    "0x1122334455"
                ]);

const msgObj = { 
    pubKey: relayerPubKey, 
    sig: whisperKeyPairID,
    ttl: 1000, 
    powTarget: 1, 
    powTime: 20, 
    topic: "0x4964656e", 
    payload: web3.utils.toHex({
        'contract': "0x692a70d2e424a56d2c6c27aa97d1a86395877b3a",
        'address': web3.eth.defaultAccount
        'action': 'transaction',
        'encodedFunctionCall': funCall,
    })
};

        
web3.shh.post(msgObj)
.then((err, result) => {
    console.log(result);
    console.log(err);
});

Javascript Library

Using the file status-gas-relayer.js, setup connection to geth, and required keypairs and symkeys

import StatusGasRelayer, {Contracts, Functions, Messages} from 'status-gas-relayer';

// Connecting to web3
const web3 = new Web3('ws://localhost:8546');
const kid = await web3js.shh.newKeyPair()
const skid = await web3.shh.addSymKey("0xd0d905c1c62b810b787141430417caf2b3f54cffadb395b7bb39fdeb8f17266b");

Subscribing to messages

General message subscription. Special handling is needed for relayer availability. The sig property is the relayer's public key that needs to be sent when sending a transaction message. More than 1 relayer can reply, so it's recommended to save these keys in a list/array.

StatusGasRelayer.subscribe(web3js, (error, msgObj) => {
    if(error) {
        console.error(error);
        return;
    }

    if(msgObj.message == Messages.available){
        // Relayer availability message
        console.log("Relayer available: " + msgObj.sig);
    } else {
        // Normal message
        console.log(msgObj);
    }
}, {
    privateKeyID: kid
});

Polling for relayers

const identityAddress = this.props.identityAddress; // Identity contract
const accountAddress = web3.eth.defaultAccount;
const gasToken = SNT.options.address;
const gasPrice = 1000000000000;  // In wei equivalent to the token

const s = new StatusGasRelayer.AvailableRelayers(Contracts.Identity, identityAddress, accountAddress)
                              .setRelayersSymKeyID(skid)
                              .setAsymmetricKeyID(kid)
                              .setGas(gasToken, gasPrice);
await s.post(web3);

Signing a message

Signing a message is similar to invoking a function. Both use mostly the same functions. The difference is that when you invoke a function, you need to specify the relayer and asymmetric key Id.

try {
    const s = new StatusGasRelayer.Identity(identityAddress, accountAddress)
                                  .setContractFunction(Functions.Identity.call)
                                  .setTransaction(to, value, data)
                                  .setGas(gasToken, gasPrice, gasLimit);
                                          
    const signature = await s.sign(web3);
} catch(error){
    console.log(error);
}

Using Identity contract call function

This functionality is used when a Identity will invoke a contract function or transfer ether without paying fees

try {
    const s = new StatusGasRelayer.Identity(identityAddress, accountAddress)
                                  .setContractFunction(Functions.Identity.call)
                                  .setTransaction(to, value, data)  // 'value' is in wei, and 'data' must be a hex string
                                  .setGas(gasToken, gasPrice, gasLimit)
                                  .setRelayer(relayer)
                                  .setAsymmetricKeyID(kid);

    await s.post(signature, web3);
} catch(error){
    console.log(error);
}

Using Identity contract approveAndCall function

This functionality is used when a Identity will invoke a contract function that requires a transfer of Tokens

try {
    const s = new StatusGasRelayer.Identity(identityAddress, accountAddress)
                                  .setContractFunction(Functions.Identity.approveAndCall)
                                  .setTransaction(to, value, data)
                                  .setBaseToken(baseToken)
                                  .setGas(gasToken, gasPrice, gasLimit)
                                  .setRelayer(relayer)
                                  .setAsymmetricKeyID(kid);

    await s.post(signature, web3);
} catch(error){
    console.log(error);
}

Using SNTController transferSNT function

This functionality is used for simple wallets to perform SNT transfers without paying ETH fees

try {
    const accounts = await web3.eth.getAccounts();

    const s = new StatusGasRelayer.SNTController(SNTController.options.address, accounts[2])
                                    .transferSNT(to, amount)
                                    .setGas(gasPrice)
                                    .setRelayer(relayer)
                                    .setAsymmetricKeyID(kid);

    await s.post(signature, web3);
} catch(error){
    console.log(error);
}

Using SNTController execute function

try {
    const accounts = await web3.eth.getAccounts();

    const s = new StatusGasRelayer.SNTController(SNTController.options.address, accounts[2])
                                  .execute(allowedContract, data)
                                  .setGas(gasPrice, gasMinimal)
                                  .setRelayer(relayer)
                                  .setAsymmetricKeyID(kid);

    await s.post(signature, web3);
} catch(error){
    console.log(error);
}

Status Extensions

• TODO