GatewayJS

GatewayJS documentation

See the Tutorial before going through these docs.

Initialization

Import GatewayJS in one of the following ways:

Import
Require
Script Tag
Import
import GatewayJS from "@renproject/gateway-js";
Require
const GatewayJS = require("@renproject/gateway-js").default;
Script Tag
<!--
GatewayJS can't yet be imported with a script tag.
This will be fixed soon.
-->
<script src="https://unpkg.com/@renproject/gateway-js/build/main/index.js">
</script>

The GatewayJS accepts the following parameters:

GatewayJS Class
GatewayJS Class

Parameter

Type

Description

network

"chaosnet" | "testnet"

Specify what RenVM network you are talking to.

options (optional)

{ endpoint?: string }

endpoint: Specify a different endpoint to the default https://gateway.renproject.io as a URL or "staging".

Example:

const gatewayJS = new GatewayJS("testnet");

The GatewayJS class has two methods, open and getGateways. Continue reading to learn how to call them.

gatewayJS.open

open is the main method used to bridge cryptocurrencies to Ethereum and back.

Parameters: Shifting to Ethereum

Type definitions - shiftIn.ts

Standard Parameters
Recover from Ren Transaction Hash
Standard Parameters

Parameter

Type

Description

sendToken

GatewayJS.Tokens.BTC.Mint

The cryptocurrency being shifted. Replace BTC with ZEC or BCH.

contractCalls

See Contract call types below. A single contract call can be included in the top level parameters (see 2nd example).

The details for how the mint approval returned from RenVM should be submitted to Ethereum.

nonce (optional)

string

A value to guarantee unique Gateway addresses. Initialize withGatewayJS.utils.randomNonce()

suggestedAmount (optional)

NumberInput

Display in the Gateway popup an amount that should be sent to the gateways address. The shift will continue even if the user sends a different amount.

requiredAmount (optional)

NumberInput or { min?: NumberInput, max?: NumberInput}

Require a specific amount to be sent to the gateway address. The shift won't continue if the amount is incorrect.

Examples:

gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Mint,
nonce: GatewayJS.utils.randomNonce(),
suggestedAmount: GatewayJS.utils.value("0.000225", "btc").sats(),
contractCalls: [... see below],
});
// Contract call in top-level
gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Mint,
sendTo: "0xD5B5b26521665Cb37623DCA0E49c553b41dbF076",
txConfig: { gas: 500000 },
});
Recover from Ren Transaction Hash

Parameter

Type

Description

sendToken

GatewayJS.Tokens.BTC.Mint

The cryptocurrency being shifted. Replace BTC with ZEC or BCH.

renTxHash

string

Resume a shift-in by providing the Ren transaction hash.

contractCalls

See Contract call types below.

The details for how the mint approval returned from RenVM should be submitted to Ethereum.

Example:

gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Mint,
renTxHash: "0xda5883967b7a79544a12576ce9a606c438b6a19b13c2a9e04178a1b31f27f172",
contractCalls: [... see below],
});

Contract call types

The contractCall parameter is an array of contract calls, which can be detailed or simple. The last contract call is augmented with the parameters returned from RenVM (see the tutorial for details). On the last contract call can be simple. Providing multiple contract calls should only be used for calls which are required for the last call, e.g. approving token transfers.

Detailed: Call smart contract
Simple: Send directly to address
Detailed: Call smart contract

Parameter

Type

Description

sendTo

string

The address of the contract to be called.

contractFn

string

The name of the function to be called on the contract.

contractParams (optional)

Array<{ name: string, type: string, value: any }>

The parameters to be passed to the contract. See abiToParams for providing an ABI object instead of specifying the types of each parameter. Defaults to [].

txConfig (optional)

TransactionConfig

Transaction options to be passed to Web3.

Example:

{
sendTo: "0xb2731C04610C10f2eB6A26ad14E607d44309FC10",
contractFn: "deposit",
contractParams: [{
name: "_msg",
type: "bytes",
value: web3.utils.fromAscii(`Depositing ${amount} BTC`),
}],
txConfig: { gas: 500000 },
}
Simple: Send directly to address

Parameter

Type

Description

sendTo

string

The Ethereum wallet to receive the shifted funds.

txConfig (optional)

TransactionConfig

Transaction options to be passed to Web3.

Example:

{
sendTo: "0xD5B5b26521665Cb37623DCA0E49c553b41dbF076",
txConfig: { gas: 500000 },
}

Parameters: Shifting out from Ethereum

Type definitions - shiftOut.ts

Standard Parameters
Provide Ethereum txHash
Provide burn ID
Standard Parameters

Parameter

Type

Description

sendToken

GatewayJS.Tokens.BTC.Burn

The cryptocurrency being shifted. Replace BTC with ZEC or BCH.

contractCalls

See Contract call types above, plus a sendAmount if using a simple contract call. A single contract call can be included in the top level parameters (see 2nd example).

Provide the details to emit the shift-out request on Ethereum.

Examples:

gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Burn,
contractCalls: [... see above],
});
// Contract call in top-level
gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Burn,
sendTo: "miMi2VET41YV1j6SDNTeZoPBbmH8B4nEx6",
sendAmount: GatewayJS.utils.value(0.001, "btc").sats(),
txConfig: { gas: 500000 },
});
Provide Ethereum txHash

Parameter

Type

Description

sendToken

GatewayJS.Tokens.BTC.Burn

The cryptocurrency being shifted. Replace BTC with ZEC or BCH.

ethTxHash

string

An Ethereum transaction hash which contains a request to shift-out the relevant asset (as an event/log).

Examples:

gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Burn,
renTxHash: "0x8dded30c5bf254f818cd656d639edf85e4bd7a93164a360e0e075be77705401e",
});
Provide burn ID

Parameter

Type

Description

sendToken

GatewayJS.Tokens.BTC.Burn

The cryptocurrency being shifted. Replace BTC with ZEC or BCH.

burnReference

string | number

The reference ID of the shift-out event/log.

Examples:

gatewayJS.open({
sendToken: GatewayJS.Tokens.BTC.Burn,
burnReference: 1234,
});

Result

gatewayJS.open returns a Gateway class, which exposes the following methods:

Gateway class
Gateway class
  • result(): A PromiEvent which resolves when the shift is complete, which emits the following events:

    • "status" - used to follow the progress of the shift. See ShiftInStatus and ShiftOutStatus. Example: await gatewayJS.open(...).result().on("status", console.log)

  • pause(): Minimize the popup to the top-right corner. (See Misc. on positioning)

  • resume(): Resuming a shift that has been paused.

  • close(): Close the window all together - see getGateways for resuming it.

  • cancel(): Remove the shift from GatewayJS's storage.

  • getStatus(): Returns the current status. See note for result()'s status event above.

gatewaysJS.getGateways

getGateways is a way of retrieving previous and current shifts from GatewayJS. It returns a Promise to a map linking shift nonces to the shift details.

Shift Details type
Shift Details type

Each shift has the following fields:

interface HistoryEvent {
id: string;
time: number;
inTx: Tx | null;
outTx: Tx | null;
renTxHash: string | null;
renVMStatus: TxStatus | null;
// Different for shift-ins and shift-outs
shiftIn: boolean;
status: ShiftInStatus | ShiftOutStatus;
shiftParams: /* parameters passed in from `open` */;
}

The HistoryEvent type can be passed directly into gatewayJS.open to resume the shifts:

Recover shifts
Recover shifts
const previousGateways = await gatewayJS.getGateways();
for (const gateway of Array.from(previousGateways.values())) {
// Ignore complete gateways.
if (
gateway.status === ShiftInStatus.ConfirmedOnEthereum ||
gateway.status === ShiftOutStatus.ReturnedFromRenVM
) { continue; }
// Resume shift
const gateway = gatewayJS.open(gateway);
gateway.pause();
gateway.result()
.on("status", (status) => console.log(`[GOT STATUS] ${status}`))
.then(console.log)
.catch(console.error);
}

Misc.

Control position of minimized Gateway popup
Control position of minimized Gateway popup

When the Gateway is minimized, a smaller popup will be shown in the top-right corner of the page. This can be moved using CSS:

._ren_gateway-minified>._ren_iframeShadow {
margin-top: 60px;
}