oasisprotocol / oasis-rosetta-gateway

The official Rosetta server implementation for the Oasis Network.

Oasis Rosetta Gateway

This repository implements the Rosetta server for the Oasis Network. See the Rosetta API docs for information on how to use the API.

Oasis-specific Rosetta API information is given in the Oasis-specific Information subsection below.

Building and Testing

To build the server:

make

To run tests:

make test

To clean-up:

make clean

make test will automatically download the Oasis Node and Rosetta CLI, set up a test Oasis network, make some sample transactions, then run the gateway and validate it using rosetta-cli.

Contributing

Versioning

See our Versioning document.

Release Process

See our Release Process document.

Running the Gateway

The gateway connects to an Oasis Node, so make sure you have a running node first. For more details, see the Run a Non-validator Node doc of the Run Node Oasis Docs.

Set the OASIS_NODE_GRPC_ADDR environment variable to the node's gRPC socket address (e.g. unix:/path/to/node/internal.sock).

Optionally, set the OASIS_ROSETTA_GATEWAY_PORT environment variable to the port that you want the gateway to listen on (default is 8080).

Start the gateway simply by running the executable oasis-rosetta-gateway.

Offline Mode

The gateway supports an "offline" mode, which enables only a subset of the Construction API and nothing else, but doesn't require a connection to an Oasis Node.

To enable it, set the environment variable OASIS_ROSETTA_GATEWAY_OFFLINE_MODE to a non-empty value. You must also set the environment variable OASIS_ROSETTA_GATEWAY_OFFLINE_MODE_CHAIN_ID to the genesis document's hash of the network that you wish to construct transactions for. In online mode, the genesis document's hash is fetched from the Oasis Node, but in offline mode there is no connection to an Oasis Node, so it has to be specified manually.

The only supported endpoints in offline mode are:

/construction/{combine,derive,hash,parse,payloads,preprocess}

Oasis-specific Information

This section describes how Oasis fits into the Rosetta APIs.

Network Identifier

Rosetta API documentation

For Amber (at time of writing):

{
    "blockchain": "Oasis",
    "network": "c014bda208f670539e8f03016b0dcfe16e0c2ad9a060419d1aad580f5c7ff447"
    /* no sub_network_identifier */
}

In general (e.g., for other testnets), the .network string is the lowercase hex encoded SHA-512/256 hash of the CBOR encoded genesis document.

Account Identifier

Rosetta API documentation

General Account

For an account account_addr's (e.g. oasis1qzzd6khm3acqskpxlk9vd5044cmmcce78y5l6000) general account:

{
    "address": account_addr
    /* no sub_account */
    /* no metadata */
}

Escrow Account

For an account account_addr's (e.g. oasis1qzzd6khm3acqskpxlk9vd5044cmmcce78y5l6000) escrow account:

{
    "address": account_addr,
    "sub_account": {
        "address": "escrow"
        /* no metadata */
    }
    /* no metadata */
}

Common Pool

For the common pool:

{
    "address": "oasis1qrmufhkkyyf79s5za2r8yga9gnk4t446dcy3a5zm"
    /* no sub_account */
    /* no metadata */
}

Fee Accumulator

For the fee accumulator:

{
    "address": "oasis1qqnv3peudzvekhulf8v3ht29z4cthkhy7gkxmph5"
    /* no sub_account */
    /* no metadata */
}

Currency

Rosetta API documentation

ROSE

For ROSE:

{
    "symbol": "ROSE",
    "decimals": 9
    /* no metadata */
}

Transaction Intents

Rosetta API documentation on /construction/preprocess and /construction/payloads.

The first two operations in the listings are the gas fee payment. For zero-fee transactions, omit them and decrease the remaining operation identifier indices.

Staking Transfer

For transfer, amount_bu base units from signer_addr to to_addr with gas limit gas_limit and fee fee_bu base units:

[
    {
        "operation_identifier": {
            "index": 0
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        },
        /* no coin_change */
        "metadata": {
            "fee_gas": gas_limit
        }
    },
    {
        "operation_identifier": {
            "index": 1
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": "oasis1qqnv3peudzvekhulf8v3ht29z4cthkhy7gkxmph5" /* fee accumulator */
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 2
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + amount_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 3
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": to_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": amount_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    }
]

Staking Burn

For burn, amount_bu base units from signer_addr with gas limit gas_limit and fee fee_bu base units:

[
    {
        "operation_identifier": {
            "index": 0
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        },
        /* no coin_change */
        "metadata": {
            "fee_gas": gas_limit
        }
    },
    {
        "operation_identifier": {
            "index": 1
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": "oasis1qqnv3peudzvekhulf8v3ht29z4cthkhy7gkxmph5" /* fee accumulator */
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 2
            /* no network_index */
        },
        /* no related_operations */
        "type": "Burn",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + amount_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    }
]

Staking Add Escrow

For add escrow, amount_bu base units from signer_addr to escrow_addr with gas limit gas_limit and fee fee_bu base units:

[
    {
        "operation_identifier": {
            "index": 0
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        },
        /* no coin_change */
        "metadata": {
            "fee_gas": gas_limit
        }
    },
    {
        "operation_identifier": {
            "index": 1
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": "oasis1qqnv3peudzvekhulf8v3ht29z4cthkhy7gkxmph5" /* fee accumulator */
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 2
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + amount_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 3
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": escrow_addr,
            "sub_account": {
                "address": "escrow"
                /* no metadata */
            }
            /* no metadata */
        },
        "amount": {
            "value": amount_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    }
]

Staking Reclaim Escrow

For transfer, amount_sh shares to signer_addr from escrow_addr with gas limit gas_limit and fee fee_bu base units:

[
    {
        "operation_identifier": {
            "index": 0
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": "-" + fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        },
        /* no coin_change */
        "metadata": {
            "fee_gas": gas_limit
        }
    },
    {
        "operation_identifier": {
            "index": 1
            /* no network_index */
        },
        /* no related_operations */
        "type": "Transfer",
        /* no status */
        "account": {
            "address": "oasis1qqnv3peudzvekhulf8v3ht29z4cthkhy7gkxmph5" /* fee accumulator */
            /* no sub_account */
            /* no metadata */
        },
        "amount": {
            "value": fee_bu.toString(),
            "currency": {
                "symbol": "ROSE",
                "decimals": 9
                /* no metadata */
            }
            /* no metadata */
        }
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 2
            /* no network_index */
        },
        /* no related_operations */
        "type": "ReclaimEscrow",
        /* no status */
        "account": {
            "address": signer_addr
            /* no sub_account */
            /* no metadata */
        },
        /* no amount */
        /* no coin_change */
        /* no metadata */
    },
    {
        "operation_identifier": {
            "index": 3
            /* no network_index */
        },
        /* no related_operations */
        "type": "ReclaimEscrow",
        /* no status */
        "account": {
            "address": escrow_addr,
            "sub_account": {
                "address": "escrow"
                /* no metadata */
            }
            /* no metadata */
        },
        /* no amount */
        /* no coin_change */
        "metadata": {
            "reclaim_escrow_shares": amount_sh.toString()
        }
    }
]

Block API

Rosetta API documentation

In a partial block identifier:

• Set only the index field to the block height.

In a block response:

• The other_transactions field is absent.

In a block:

• Block identifier index fields contain the height of the block.
• Block identifier hash fields are lowercase hex encoded.
• The parent_block_identifier field contains the block identifier of the previous block, except when querying for first block.
• The metadata field is absent.

In a transaction:

• The transaction identifier hash field is lowercase hex encoded.
• The operations field contains the transaction intent with some modifications.
• The metadata field is absent.

In an operation as compared to the corresponding operation from the transaction's intent:

• The related_operations field may be set.
• The status field is set to OK for successful transactions and Failed for failed transactions.
• The metadata field is absent.