RenJS

RenJS Documentation

See the Tutorial before going the API documentation. Detailed typedoc docs for RenJS can be found at renproject.github.io/ren-js.

The following are for RenJS v1. RenJS v2 API docs can be found here: https://renproject.github.io/ren-js-docs/.

Initialization

Import RenJS in one of the following ways:

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

The RenJS accepts the following parameters:

RenJS Class
RenJS Class

Parameter

Type

Description

network

"mainnet" | "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 renJS = new RenJS("testnet");

renJS.lockAndMint

lockAndMint is the main method used to send cryptocurrencies into Ethereum.

Type definition

New Mint
Resume a Pending Mint
New Mint

Parameter

Type

Description

sendToken

RenJS.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 withRenJS.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.

web3Provider (optional)

provider

A web3 provider must be provided if RenJS is submitting or reading transactions to/from Ethereum.

confirmations (optional)

undefined | number

The number of confirmations to wait before submitting the signature to Ethereum. If this number is less than the default, the RenVM transaction is returned when those confirmations have passed, before the signature is available, and will not be submitted to Ethereum.

tags (optional)

[string]

Provide optional tags which can be used to look up transfers in the lightnodes.

Examples:

const mint = renJS.mint({
sendToken: RenJS.Tokens.BTC.Mint,
nonce: RenJS.utils.randomNonce(),
suggestedAmount: RenJS.utils.value("0.000225", "btc").sats(),
contractCalls: [... see below],
});
Resume a Pending Mint

Parameter

Type

Description

sendToken

RenJS.Tokens.BTC.Mint

The source asset being minted. Replace BTC with ZEC or BCH.

txHash

string

Resume a mint 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.

nonce

(optional)

undefined | string

An option to override the default nonce generated randomly.

deposit (optional)

UTXOIndex

Specify which deposit should be send to RenVM instead of waiting for one to be observed. This deposit must have been sent to the gateway address of the transfer.

gatewayAddress (optional)

undefined | string

Specify a gateway address. Gateway addresses are based on the RenVM shard selected to process the transfer. Currently there is only one RenVM shard, but once sharding is live, this parameter will ensure that the same address can be used to resume the transfer.

Example:

const mint = renJS.mint({
sendToken: RenJS.Tokens.BTC.Mint,
txHash: "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 },
}

Result

Mint

renJS.burnAndRelease

burnAndRelease is the main method used to withdraw cryptocurrencies into Ethereum.

Type definition

Standard Parameters
Provide Ethereum txHash
Provide burn ID
Standard Parameters

Parameter

Type

Description

sendToken

RenJS.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:

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

Parameter

Type

Description

sendToken

RenJS.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:

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

Parameter

Type

Description

sendToken

RenJS.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:

renJS.open({
sendToken: RenJS.Tokens.BTC.Burn,
burnReference: 1234,
});

Result

Burn

renJS.getGatewayAddress

Get the Gateway contract address for a given asset.

Standard Parameters
Standard Parameters

Parameter

Type

Description

web3

Web3

Local instance of web3.

tokenOrContract

ShiftedToken | RenContract | Asset | ("BTC" | "ZEC" | "BCH")

Token or contract to return an address for.

Returns

string

renJS.getTokenAddress

Get the ERC20 token contract address for a given asset.

Standard Parameters
Standard Parameters

Parameter

Type

Description

web3

Web3

Local instance of web3.

tokenOrContract

ShiftedToken | RenContract | Asset | ("BTC" | "ZEC" | "BCH")

Token or contract to return an address for.

Returns

string

renJS.getFees

Get the current RenVM mint, burn and transaction fees.

Returns

Return Type
Example
Return Type
interface ChainFees {
lock: number; // Chain transaction fees for locking (in sats)
release: number; // Chain transaction fees for releasing (in sats)
ethereum: {
mint: number; // Minting fee basis points (10 = 0.1%)
burn: number; // Burning fee basis points (10 = 0.1%)
};
}
interface Fees {
btc: ChainFees;
zec: ChainFees;
bch: ChainFees;
}
Example
const RenJS = require("@renproject/ren");
new RenJS("testnet").getFees().then(console.log);
> {
btc: { lock: 35000, release: 35000, ethereum: { mint: 10, burn: 10 } },
zec: { lock: 35000, release: 35000, ethereum: { mint: 10, burn: 10 } },
bch: { lock: 35000, release: 35000, ethereum: { mint: 10, burn: 10 } }
}