GatewayJS

GatewayJS documentation

See the Tutorial before going through these docs.
See also the generated typedoc docs at renproject.github.io/ren-js.
Initialization
Import GatewayJS in one of the following ways:
Import
Require
Script Tag
Import
import GatewayJS from "@renproject/gateway";
Require
const GatewayJS = require("@renproject/gateway").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/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: Minting on Ethereum
​Type definition​
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: Releasing from Ethereum
​Type definition​
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;
}

Examples - Previous

Conf-less UX

Next - APIS

RenJS

Last updated 2 months ago

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"`.

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 with`GatewayJS.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.

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.

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.

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).

GatewayJS

Initialization

Example:

`gatewayJS.open`

Parameters: Minting on Ethereum

Examples:

Example:

Contract call types

Example:

Example:

Parameters: Releasing from Ethereum

Examples:

Examples:

Examples:

Result

`gatewaysJS.getGateways`

Misc.