Verse-Proxy

This is proxy to control access allow list to verse layer.
Verse-Proxy is made by Nest.

Verse-Proxy can control following items.

• jsonrpc method
• transaction's from, to, value
• address which can deploy smart contract
• transaction access rate

Verse Proxy Build Steps

1. Git clone

git clone git@github.com:oasysgames/verse-proxy.git

2. Set access allow list

Set access allow list at following file.
Details are described later.

• src/config/configuration.ts
• src/config/transactionAllowList.ts

3. Set configuration variables

• Create file .env refer to .env.example
• Update those variables with corrected values from your side

4. Set up redis server

• Verse-Proxy use redis as a database to read and write data, so in order to run this proxy you will need start a redis server and pass url to REDIS_URI
• also Verse-Proxy need to know which database you would use which can be config using DATASTORE For example:

DATASTORE=redis
REDIS_URI=redis://localhost:6379

5. Set up npm

$ npm install
$ npm build

6. Run app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Test

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

Deploy

1. Set Environment Variables

export PORT=[YOUR_PROXY_PORT]
export VERSE_MASTER_NODE_URL=[YOUR_VERSE_HTTP_URL]

2. Set allow list config

You have to download your allow list config to $PWD/src/config.

3. Start container

# chose image version and pull image
docker pull ghcr.io/oasysgames/verse-proxy:v1.0.0

# create container
docker run --name verse-proxy -d -p $PORT:$PORT -v $PWD/src/config:/usr/src/app/src/config verse-proxy

Control items

Set allowed header

You can set whether you inherit proxy request's host header on verse request at src/config/configuration.ts.

inheritHostHeader: true,

Set allowed verse request methods

You can set allowed verse request methods by regex at src/config/configuration.ts.

allowedMethods: [
  /^net_version$/,
  /^web3_clientVersion$/,
  /^eth_get.*$/,
  /^eth_sendRawTransaction$/,
  /^eth_chainId$/,
  /^eth_blockNumber$/,
  /^eth_call$/,
  /^eth_estimateGas$/,
  /^eth_gasPrice$/,
  /^eth_maxPriorityFeePerGas$/,
  /^eth_feeHistory$/,
  /^eth_.*Filter$/,
],

Default allowedMethods feature are following.

• It allows methods that may be requested by users
• It prohibits the methods of executing a transaction with the authority of verse-geth(e.g. eth_sendTransaction)

Set transaction allow list

You can set allowed transaction list at src/config/transactionAllowList.ts.

from, to

You can control the from and to of a transaction.

// elements contained in the array are allowed to be transacted.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['0xaf395754eB6F542742784cE7702940C60465A46a'],
      toList: ['0xaf395754eB6F542742784cE7702940C60465A46a'],
    },
    {
      fromList: ['0xaf395754eB6F542742784cE7702940C60465A46c'],
      toList: ['0xaf395754eB6F542742784cE7702940C60465A46c'],
    },
  ];
};

// '*' is wildcard.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['*'],
      toList: ['*'],
    },
  ];
};

// ! is exception_pattern.

// 0xaf395754eB6F542742784cE7702940C60465A46a are not allowed to be transacted.
// But any address other than 0xaf395754eB6F542742784cE7702940C60465A46a are allowed to be transacted.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['!0xaf395754eB6F542742784cE7702940C60465A46a'],
      toList: ['*'],
    },
  ];
};

// Everyone are not allowed to transact to 0xaf395754eB6F542742784cE7702940C60465A46a.
// everyone are allowed to transact to any address other than 0xaf395754eB6F542742784cE7702940C60465A46a.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['*'],
      toList: ['!0xaf395754eB6F542742784cE7702940C60465A46a'],
    },
  ];
};

// Multiple Setting is enabled.
// Everyone are not allowed to transact to 0xaf395754eB6F542742784cE7702940C60465A46a and 0xaf395754eB6F542742784cE7702940C60465A46c.
// everyone are allowed to transact to any address other than 0xaf395754eB6F542742784cE7702940C60465A46a and 0xaf395754eB6F542742784cE7702940C60465A46c.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['*'],
      toList: [
        '!0xaf395754eB6F542742784cE7702940C60465A46a',
        '!0xaf395754eB6F542742784cE7702940C60465A46c'
      ],
    },
  ];
};

// You can not set setting with normal_address and exception_pattern.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['*'],
      toList: [
        '0xaf395754eB6F542742784cE7702940C60465A46a',
        '!0xaf395754eB6F542742784cE7702940C60465A46c'
      ],
    },
  ];
};

If you want to allow transacting factory and bridge contracts, please set those contract addresses to to.

// Verse-Layer pre-deployed Contracts. Same address for all Verse-Layers.
L2StandardBridge: '0x4200000000000000000000000000000000000010',
L2StandardTokenFactory: '0x4200000000000000000000000000000000000012',
L2ERC721Bridge: '0x6200000000000000000000000000000000000001',

export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: [<FROM_YOU_WANT_TO_SET>],
      toList: [
        '0x4200000000000000000000000000000000000010',
        '0x4200000000000000000000000000000000000012',
        '0x6200000000000000000000000000000000000001',
      ],
    },
    ...
  ];
};

Value(Option)

You can control the token value of a transaction.

// Only transactions with more than 1000000000000000000unit values are allowed.
export const getTxAllowList = (): Array<TransactionAllow> => {
  return [
    {
      fromList: ['*'],
      toList: ['*'],
      value: { gt: '1000000000000000000' },
      },
  ];
};

value's key	Comparison Operation
eq	txValue == condition is allowed
nq	txValue != condition is allowed
gt	txValue > condition is allowed
gte	txValue >= condition is allowed
lt	txValue < condition is allowed
lte	txValue <= condition is allowed

Transaction access rate limit(Option)

If you set transaction access rate limit, follow Transaction access rate limit

Set contract deployer

You can control deployer of a verse at src/config/transactionAllowList.ts.

// Only 0xaf395754eB6F542742784cE7702940C60465A46a can deploy
export const getDeployAllowList = (): Array<string> => {
  return ['0xaf395754eB6F542742784cE7702940C60465A46a'];
};

// wild card
// Everyone can deploy
export const getDeployAllowList = (): Array<string> => {
  return ['*'];
};

// exception_pattern
// any address other than 0xaf395754eB6F542742784cE7702940C60465A46c can deploy.
export const getDeployAllowList = (): Array<string> => {
  return ['!0xaf395754eB6F542742784cE7702940C60465A46c'];
};

Batch Request

You can execute batch requests to the proxy.

If you want to make many transaction batch requests, change the parse limit in the body by environment variable. The default body parse limit is 512kb.

MAX_BODY_BYTE_SIZE=1048576 # 1048576 byte is 1MB.

Multi Processing

If you want to build proxy in multi-process, set worker count to environment variables. The default worker count is 1.

CLUSTER_PROCESS=4

Master-Verse-Node and Read-Verse-node

You can create a verse and its replica to reduce the access load on the verse. A verse can be set on the master-node and a replica on the read-node in a proxy. It will send read-transactions to the read-node and write-transactions to the master-node.

You can set Master-Verse-Node and Read-Verse-node by the environment variable.

VERSE_READ_NODE_URL=[YOUR_VERSE_REPLICA_HTTP_URL]

WebSocket Proxy

The WebSocket proxy is an experimental feature. To enable it, add the WebSocket rpc url of the your Verse node to the following environment variable and then restart the proxy.

VERSE_WS_URL=[YOUR_VERSE_WEBSOCKET_URL]

In the WebSocket proxy feature, only the eth_subscribe and eth_unsubscribe methods are proxied to the Verse node. All other methods are internally routed to the HTTP proxy feature. This means that if the VERSE_READ_NODE_URL environment variable is configured, read-transactions are proxied to the replica node, while write-transactions are proxied to the master node.

For the question of whether to choose a master node or a reader node, please make your selection considering replication latency. Since latency is typically only a few tens of milliseconds, it is generally recommended to use the reader node.

Check Master-Verse-Node

To check the behavior of requests to the Master-Verse-Node, an endpoint named /master is provided.

All transactions sent to /master are sent to the Master-Verse-Node.

Reduce Metamask Access

By returning the cache of blockNumber to the metamask, the number of accesses to the metamask can be reduced. For more detail, check the following doc. Reduce Metamask Access