Protocol

Documentation version 0.22

Introduction

You can use the Rouge protocol (creating campaign, issuing e-tickets, e-coupons, redeeming them, etc) either directly, interacting with the RGE contracts on the POA blockchain (and its Sokol testnet), or using the Javascript library rouge.js.

Using the Javascript library rouge.js is the far simpler and prefered way to use the protocol.

Before using rouge.js, you will need RGE tokens on the ethereum address of the notes issuers. You can get them for Sokol and Ropsten for free using our faucet.


Installing rouge.js

rouge.js was designed to work both in the browser and in Node.js. We have also been been able to use it successfully in nativescript mobile app.

Nodejs

We recommend a recent version of nodejs (>= 10). rouge.js was not tested with earlier versions of nodejs.

npm i web3 rouge.js                # using Npm
yarn add web3 rouge.js             # using Yarn
      

Rouge depends on the web3.js library (1.0 version)


rouge.js API

Rouge.js is actively using Promises and recommend using async/await syntax...

Importing the modules, choosing Ethereum provider

To start using rouge.js you need an instance of web3.js. Please refer to the web3.js documentation to initiate a valid Web3 provider.

// web3 initiation example using the HTTP Sokol provider
import Web3 from 'web3'
const provider = new Web3.providers.HttpProvider('https://sokol.poa.network')
const web3 = new Web3(provider)
      

The second step is to create an instance of the Rouge protocol.

import { RougeProtocol } from 'rouge.js'
const rouge = RougeProtocol(web3)
      

This instance will be able to directly call all read-only & point-of-view-neutral attributs (see below) of the API, but you need to assign an Ethereum address to request information from the point of view of a "notes issuer" or "note bearer" for any campaign.

Assigning the point of view to an Ethereum account

Most methods in the API need an account "point of view". The read-only attribut "canRedeem" will return true or false from the point of view of a specific acount. Similarly, the transaction method "redeem()" can only be used the point of view of a specific acount for which the private key is unlocked.

To assign a point of view, you just need to chain the rouge instance with the method 'as'. This method can accept several types of arguments to point the view to a specific Ethereum account

  • mode 1: a public Ethereum address (*)
  • mode 2: an object with the private key as attribut
  • mode 3: directly a web3.js account object
// mode 1: using a public Ethereum address
const rougeInstance1 = RougeProtocol(web3).as(account_address)

// mode 2: using an account private key
const rougeInstance2 = RougeProtocol(web3).as({pkey: private_key})

// mode 3: using an web3.eth.accounts object
const rougeInstance3 = RougeProtocol(web3).as(web3.eth.account_instance)
      

(*) Using the mode 1, you will only access the read-only API methods of the protocol, and you won't be able to change state on the blockchain (creating campaign, notes acquisition and redemption).

Rouge campaign object

You can instanciate a rouge.js campaign object either by creating a new campaign (issued by the account set as the point of view) or by chaining the method 'campaign$' and passing the campaign contract address as argument.

// creating a new Rouge campaign contract
const campaign = await rougeInstance.createCampaign({
    name: 'your campaign name',
    // How many voucher notes to issue
    issuance: 10,
     // RGE deposit
    tokens: 10 * 0.1 * 1000000,
    // when the campaign will expire (timestamp)
    expiration: (new Date().getTime() / 1000) + 3600 * 24 * 10
  }
)
// loading an existing Rouge contract in a rouge.js campaign object
const campaign = rougeInstance.campaign$(rouge_campaign_contract_address)
      

Methods available on the Rouge campaign object:

Read-only attributs

campaign.address
campaign.version
campaign.info
campaign.expiration
campaign.issuance
campaign.state
campaign.available    // how many notes not yet distributed or acquired
campaign.acquired     // how many notes already distributed or acquired
campaign.redeemed     // how many notes already redeemed
campaign.canDistribute     // is the current actor the issuer or authorized distributor
campaign.canSignRedemtion     // is the current actor the issuer or authorized redemption attestor
campaign.hasNote       // is the current actor a bearer for this camapaign
campaign.hasRedeemed       // is the current actor a bearer for this camapaign & the note has been redeemed
      

For issuer:

campaign.distributeNote(receiver_address)
campaign.addAttestor()
      

For note bearers:

campaign.acquireNote(attestor, signedAuth)
campaign.redeemNote(attestor, signedAuth)
      

Examples

A good starting point is to check examples and tests included in our github repository.

Simple script example

Simple javascript script to create a campaign.

ÐApp

The Coupon Demo is a ÐApp using the protocol to illustrate the use-case of coupons. You can use it with all networks listed below.

The mini POS is a prototype that implement the redemption procedure from the point of view of the issuer and the notes bearer in the context of physical point of sale. It uses a unique QR code linked to the rouge redemption transaction, signed by their respective actors.


Contracts API

Rouge is not implementing its own blockchain but is built on top of other blockchains using smart contracts. The current implementation has been tested and works on Ethereum and POA.

You should read our technical introduction to the Rouge Protocol if you wish to understand the version 0.22 low level implementation of Rouge.

The core smart contracts are on github: https://github.com/TheRougeProject/rouge-protocol-solidity


Utilities

testnet Ropsten (id=3)

Please use the faucet to get RGE tokens

The faucet source code is available on GitHub

POA

testnet Sokol (id=77)

Please use the faucet to get RGE tokens

POA mainnet (id=99)

Please contact us to use the Ethereum/POA RGE bridge