💠 mosaic.js

Mosaic is a parallelization schema for decentralized applications. It composes heterogeneous blockchain systems into one another. Decentralized applications can use Mosaic to compute over a composed network of multiple blockchain systems in parallel.

Mosaic enables building scalable blockchain token economies through the bidirectional transposition of ERC20 tokens on one blockchain, the origin chain, and a utility token representation on another blockchain, the auxiliary chain.

The protocol defines a set of actions that together perform atomic token transfers across two blockchains using gateway contracts. A gateway for a given EIP20 token is comprised of a EIP20Gateway contract on origin, a corresponding EIP20CoGateway contract on auxiliary, and an EIP20 utility token contract on auxiliary that mints and burns utility tokens to atomically mirror tokens staked and unstaked on the origin chain.

Atomicity is achieved using a 2-phase message passing architecture between the chains. Messages are declared on the source chain, and confirmed on the target chain with Merkle Patricia proofs once the source chain is finalized. Once messages are confirmed on the target chain, they can efficiently progressed with a hashlock. Messages can also be reverted if they are not yet completed on the target chain.

⚠️ Reverting is not yet supported in mosaic.js and will be supported in a future version. In the meantime you can revert by accessing the contracts directly.

You can read the draft of the mosaic whitepaper or the original OpenST whitepaper.

Instructions

Installation

npm install @openst/mosaic.js web3 web3-eth-accounts

ℹ️ Note that web3 and web3-eth-accounts are peer-dependencies.

Usage

Mosaic

const Web3 = require('web3');
const Mosaic = require('@openst/mosaic.js');

const originWeb3 = new Web3('http://localhost:8546');
const auxiliaryWeb3 = new Web3('http://localhost:8547');

const originContractAddresses = {
  EIP20Gateway: '0x0000000000000eip20gatewaycontractaddress',
  ...,
};
const auxiliaryContractAddresses = {
  EIP20CoGateway: '0x00000000000eip20cogatewaycontractaddress',
  ...,
};

const originChain = new Mosaic.Chain(originWeb3, originContractAddresses);
const auxiliaryChain = new Mosaic.Chain(auxiliaryWeb3, auxiliaryContractAddresses);

const mosaic = new Mosaic(originChain, auxiliaryChain);

Facilitator

Creating a new facilitator:

const facilitator = new Mosaic.Facilitator(mosaic);

Staking:

const staker = '0x00000000000000000000stakeraccountaddress';
const amount = '1000000000000';
const beneficiary = '0x000000000000000beneficiaryaccountaddress';
const gasPrice = '5';
const gasLimit = '150000000';
const hashLock = '0x00000000000000000000000000000000000000000000000000000000hashlock';
const txOptions = { from: staker };

const stakeResponse = facilitator
  .stake(
    staker,
    amount,
    beneficiary,
    gasPrice,
    gasLimit,
    hashLock,
    txOptions,
  )
  .then(console.log)
  .catch(console.log);

Progressing the stake after the state root has been transferred:

const unlockSecret = '0x0000000000000000000000000000000000000000000000000000unlocksecret';
const txOptionOrigin = { from: '0x0000000000000000originfacilitatoraddress' };
const txOptionAuxiliary = { from: '0x0000000000000auxiliaryfacilitatoraddress' };

// stakeResponse.blockNumber: Block height at which stake was done.
facilitator
  .progressStake(
    staker,
    amount,
    beneficiary,
    gasPrice,
    gasLimit,
    nonce,
    hashLock,
    unlockSecret,
    stakeResponse.blockNumber,
    txOptionOrigin,
    txOptionAuxiliary,
  )
  .then(console.log)
  .catch(console.log);

Redeeming:

const redeemer = '0x0000000000000000000000000redeemeraddress';
const redeemAmount = '1000000000000';
const beneficiary = '0x000000000000000beneficiaryaccountaddress';
const gasPrice = '4';
const gasLimit = '150000000';
const hashLock = '00000000000000000000000000000000000000000000000000000000hashlock';
const txOptionRedeem = {
  from: redeemer,
  value: '100', // This must be equal to the bounty amount!
};

const redeemResponse = facilitator
  .redeem(
    redeemer,
    redeemAmount,
    beneficiary,
    gasPrice,
    gasLimit,
    hashLock,
    txOptionRedeem,
  )
  .then(console.log)
  .catch(console.log);

Progressing the redemption after the state root has been transferred:

const unlockSecret = '0x0000000000000000000000000000000000000000000000000000unlocksecret';
const txOptionOriginRedeem = { from: '0x000000000facilitatoraddressonoriginchain' };
const txOptionAuxiliaryRedeem = { from: '0x000000facilitatoraddressonauxiliarychain' };

// redeemResponse.blockNumber: Block height at which redeem was done.
facilitator
  .progressRedeem(
    redeemer,
    nonce,
    beneficiary,
    redeemAmount,
    gasPrice,
    gasLimit,
    hashLock,
    unlockSecret,
    redeemResponse.blockNumber,
    txOptionOriginRedeem,
    txOptionAuxiliaryRedeem,
  )
  .then(console.log)
  .catch(console.log);

General Contract Interaction

EIP20Gateway example:

// Expecting Mosaic import and an instance of `mosaic`:
const {
  Anchor,
  EIP20CoGateway,
  EIP20Gateway,
  EIP20Token,
  OSTPrime,
} = Mosaic.Contracts;

// Afterwards, ou can call methods directly on the contract instance:
const eip20Gateway = new EIP20Gateway(
  mosaic.origin.web3,
  mosaic.origin.contractAddresses.EIP20Gateway,
);

const staker = '0x00000000000000000000stakeraccountaddress';

const amount = '1000000000000';
const beneficiary = '0x000000000000000beneficiaryaccountaddress';
const gasPrice = '5';
const gasLimit = '150000000';
const hashLock = '0x00000000000000000000000000000000000000000000000000000000hashlock';
const txOptions = { from: staker };

const nonce = await eip20Gateway.getNonce(staker);

eip20Gateway
  .stake(
    amount,
    beneficiary,
    gasPrice,
    gasLimit,
    nonce,
    hashLock,
    txOptions,
  )
  .then(console.log)
  .catch(console.log);

OSTPrime

On the auxiliary chain OST is the base token. The gas price on auxiliary is paid in OST (like Ether pays for gas on Ethereum mainnet). To obtain the base token, you need to stake OST on origin.

On auxiliary, the OSTPrime contract will convert the EIP20 token to base tokens for the beneficiary.

Create an OSTPrime object:

const ostPrime = new Mosaic.ContractInteract.OSTPrime(
  mosaic.auxiliary.web3,
  mosaic.auxiliary.contractAddresses.OSTPrime,
);

Wrap:

const amountToWrap = '1000';
const fromAddress = '0x00000000000000000000000000000fromaddress';
let txOptions = {
  value: amountToWrap,
  from: fromAddress,
};

ostPrime
  .wrap(txOptions)
  .then(console.log)
  .catch(console.log);

Unwrap:

const amountToUnwrap = '1000';
txOptions = {
  from: fromAddress,
};

ostPrime
  .unwrap(amountToUnwrap, txOptions)
  .then(console.log)
  .catch(console.log);

Related Work

mosaic-contracts provides the EVM smart contracts implementations. You can use mosaic-contracts directly to deploy a new mosaic chain.

Contributing

Set-up

git clone git@github.com:openst/mosaic.js.git
cd mosaic.js
npm install
npm run test

# Requires docker:
npm run test:integration

Guidelines

There are multiple ways to contribute to this project. However, before contributing, please first review the Code of Conduct.

We track our issues on GitHub.

To contribute code, please ensure that your submissions adhere to the Style Guide; please also be aware that this project is under active development and we have not yet established firm contribution guidelines or acceptance criteria.

Community

• Forum
• Gitter