@windingtree/wt-contracts

WT Smart Contracts

Smart contracts of the Winding Tree platform.

The smart contracts in the hotel folder and airline folder are representing inventory registered in the Winding Tree platform. The registries themselves are WTHotelIndex and WTAirlineIndex smart contracts.

For interaction with those from your application, you can use the Abstract* smart contracts whose JSON ABIs are significantly smaller (86 kB vs 500 kB in case of WTHotelIndex).

Requirements

Node 10 is required for running the tests and contract compilation.

Installation

npm install @windingtree/wt-contracts

import HotelContractMetadata from '@windingtree/wt-contracts/build/contracts/AbstractHotel.json';
// or
import { AbstractHotelContract, AbstractWTHotelIndexContract } from '@windingtree/wt-contracts';

Development

git clone https://github.com/windingtree/wt-contracts
nvm install
npm install
npm test

You can run a specific test with npm test -- test/WTHotel.js or you can generate a coverage report with npm run coverage.

Flattener

A flattener script is also available, and by running npm run flattener, you cancreate a flattened version of the contracts without imports in one single file for all contracts in the contracts folder. This is needed if you plan to use tools like etherscan verifier or securify.ch.

Deployment

We are using the upgradeability proxy from zos and the deployment pipeline is using their system as well. You can read more about the publishing process and upgrading in zos documentation.

In order to interact with "real" networks such as mainnet, ropsten or others, you need to setup a keys.json file used by truffle that does the heavy lifting for zos.

{
  "mnemonic": "<SEED_PHRASE>",
  "infura_projectid": "<PROJECT_ID>"
}

Local testing

You don't need keys.json file for local testing of deployment and interaction with the contracts.

1. Start a local Ethereum network.

   > npm run testrpc
   

2. Start a zos session.

   > ./node_modules/.bin/zos session --network development --from 0x87265a62c60247f862b9149423061b36b460f4bb --expires 3600
   

3. Deploy your contracts. This only uploads the logic, the contracts are not meant to be directly interacted with.

   > ./node_modules/.bin/zos push --network development
   

4. Create the proxy instances of deployed contracts you can interact with. The args attribute is passed to the initialize function that sets the owner of the Index (it can be an address of a multisig) and a an actual instance of Lif token. You don't Lif token to play with this locally.

   > ./node_modules/.bin/zos create WTHotelIndex --network development --init initialize --args 0x87265a62c60247f862b9149423061b36b460f4bb,0xB6e225194a1C892770c43D4B529841C99b3DA1d7
   > ./node_modules/.bin/zos create WTAirlineIndex --network development --init initialize --args 0x87265a62c60247f862b9149423061b36b460f4bb,0xB6e225194a1C892770c43D4B529841C99b3DA1d7
   

These commands will return a network address where you can actually interact with the contracts. For a quick test, you can use the truffle console.

> ./node_modules/.bin/truffle console --network development
truffle(development)> contract = await WTHotelIndex.at('0x839c960087942a82636e191d9a7ed6145582cfac')
undefined
truffle(development)> contract.getHotels()
[ '0x0000000000000000000000000000000000000000' ]
truffle(development)> contract.registerHotel('http://windingtree.com')
truffle(development)> contract.getHotels()
[ '0x0000000000000000000000000000000000000000',
  '0x4D377b0a8fa386FA118B09947eEE2B1f7f126C76' ]

Documentation

Documentation is in the docs folder and can be generated by running npm run soldoc.

Upgradeability FAQ

What does upgradeability mean?

We can update the logic of WT Index while keeping the public address of WT Index the same.

What happens when you upgrade the WT Index?

The WT Index address stays the same, the client software, has to interact with the Index only with the updated ABI which is distributed via NPM (under the new version number). No data is lost.

Can you change the index data structure?

Yes, we can. If we adhere to zos recommendations, we can extend the data stored in WT Index.

Can you change the hotel/airline data structure?

Yes, we can. But it's not as smooth as with the Index. Until #218 is implemented, we cannot easily migrate all of the existing records at once. That means that if we change the data structure, all newly registered records will have the new data structure, but the old ones will keep the old layout and functionality.

Can I switch to the new hotel/airline version?

Yes, you can. There are multiple options.

1. You can deregister and register your hotel. This will give you a new blockchain address of your hotel. You probably don't want that.
2. We will provide an upgrade method which would allow you to upgrade your record with a single transaction.
3. We will eventually implement #218 and you wouldn't have to do anything.

We suspect that in case of upgrade, the tooling will somehow support both versions for a transitional period.

How do I work with different hotel/airline versions on the client?

That's a tricky one. In case of hotel/airline upgrade, you might need to represent different records with different ABIs. We will provide an easy way to distinguish between versions - or you can use wt-js-libs which will have this built in.