GatewayJS
GatewayJS is being deprecated in favor of tightly integrated user flows using RenJS v2. In order to use all assets supported by Multichain, please start migration as soon as possible.
See the Tutorial before going through these docs. See also the generated typedoc docs at renproject.github.io/ren-js.
Import GatewayJS in one of the following ways:
import GatewayJS from "@renproject/gateway";
const GatewayJS = require("@renproject/gateway").default;
<!--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:
The GatewayJS class has two methods, open and getGateways. Continue reading to learn how to call them.
open is the main method used to bridge cryptocurrencies to Ethereum and back.
​Type definition​
Parameter | Type | Description |
|
| The cryptocurrency being shifted. Replace |
| 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. |
|
| A value to guarantee unique Gateway addresses. Initialize with |
|
| 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. |
| ​ | Require a specific amount to be sent to the gateway address. The shift won't continue if the amount is incorrect. |
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-levelgatewayJS.open({sendToken: GatewayJS.Tokens.BTC.Mint,sendTo: "0xD5B5b26521665Cb37623DCA0E49c553b41dbF076",txConfig: { gas: 500000 },});
​
Parameter | Type | Description |
|
| The cryptocurrency being shifted. Replace |
|
| Resume a shift-in by providing the Ren transaction hash. |
| See Contract call types below. | The details for how the mint approval returned from RenVM should be submitted to Ethereum. |
gatewayJS.open({sendToken: GatewayJS.Tokens.BTC.Mint,renTxHash: "0xda5883967b7a79544a12576ce9a606c438b6a19b13c2a9e04178a1b31f27f172",contractCalls: [... see below],});
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.
Parameter | Type | Description |
|
| The address of the contract to be called. |
|
| The name of the function to be called on the contract. |
|
| The parameters to be passed to the contract. See |
| ​TransactionConfig​ | Transaction options to be passed to Web3. |
​ | ​ | ​ |
{sendTo: "0xb2731C04610C10f2eB6A26ad14E607d44309FC10",contractFn: "deposit",contractParams: [{name: "_msg",type: "bytes",value: web3.utils.fromAscii(`Depositing ${amount} BTC`),}],txConfig: { gas: 500000 },}
Parameter | Type | Description |
|
| The Ethereum wallet to receive the shifted funds. |
| ​TransactionConfig​ | Transaction options to be passed to Web3. |
​ | ​ | ​ |
{sendTo: "0xD5B5b26521665Cb37623DCA0E49c553b41dbF076",txConfig: { gas: 500000 },}
​Type definition​
Parameter | Type | Description |
|
| The cryptocurrency being shifted. Replace |
| See Contract call types above, plus a | Provide the details to emit the shift-out request on Ethereum. |
gatewayJS.open({sendToken: GatewayJS.Tokens.BTC.Burn,contractCalls: [... see above],});
// Contract call in top-levelgatewayJS.open({sendToken: GatewayJS.Tokens.BTC.Burn,sendTo: "miMi2VET41YV1j6SDNTeZoPBbmH8B4nEx6",sendAmount: GatewayJS.utils.value(0.001, "btc").sats(),txConfig: { gas: 500000 },});
Parameter | Type | Description |
|
| The cryptocurrency being shifted. Replace |
|
| An Ethereum transaction hash which contains a request to shift-out the relevant asset (as an event/log). |
gatewayJS.open({sendToken: GatewayJS.Tokens.BTC.Burn,renTxHash: "0x8dded30c5bf254f818cd656d639edf85e4bd7a93164a360e0e075be77705401e",});
gatewayJS.open returns a Gateway class, which exposes the following methods:
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 - seegetGatewaysfor resuming it.cancel(): Remove the shift from GatewayJS's storage.getStatus(): Returns the current status. See note forresult()'s status event above.
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.
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-outsshiftIn: boolean;status: ShiftInStatus | ShiftOutStatus;shiftParams: /* parameters passed in from `open` */;}
The HistoryEvent type can be passed directly into gatewayJS.open to resume the 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 shiftconst gateway = gatewayJS.open(gateway);gateway.pause();gateway.result().on("status", (status) => console.log(`[GOT STATUS] ${status}`)).then(console.log).catch(console.error);}
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;}
