Last modified: Mon Nov 04 2019 16:15:12 GMT+0000 (Coordinated Universal Time)

Overview

We designed the Winding Tree platform with a vision to create a truly decentralized marketplace that anyone (not just travel companies) can use. Our design relies on four key concepts:

  1. Identity
  2. Trust
  3. Aggregation
  4. Direct Connect

On decentralized Winding Tree marketplace, any organization can identify itself to others (identity), prove that they are a trustworthy company (trust), list itself to be discovered by other companies (aggregation), and start communicating with those companies directly (direct connect).

Identity

A marketplace is a group of individuals that are gathering with an intent of buying and selling goods. Since Winding Tree uses Ethereum, these individual actors are represented by Ethereum accounts.

Marketplace 0

Ethereum account is a simple construct; it doesn't have any properties besides its ETH balance, and it can't do anything apart from signing messages and sending transactions to other accounts and smart contracts. But since Winding Tree is a B2B marketplace, we need a way to represent organizations as actors, not individuals.

Marketplace 1

We can represent organizations using smart contracts. Smart contracts, in contrast with Ethereum accounts, don't have private keys, but they can contain data and execute code.

ORG.ID

We call the organization representation ORG.ID and maintain a global decentralized business registry of them. It is analogous to government-maintained registries, except that it doesn't rely on a central party and there is no bureaucracy involved in working with it (you don't have to talk to anyone to use it).

A valid ORG.ID has two parts:

  1. 0xORG smart contract interface
  2. ORG.JSON, a file that contains organization's information (name, address, etc.)

0xORG

The 0xORG functionality is crucial for the Winding Tree platform, it:

  1. provides each organization with a unique identifier (e.g. 0xa13c0e29da46c822045ab0fecde41e1d3d29c11c, this address is also called ORG.ID).
  2. points to the ORG.JSON location (since it's too expensive to store a lot of data on the blockchain, we decided to store it off-chain).
  3. keeps track of ORG.JSON changes (0xORG has to contain a valid ORG.JSON hash, otherwise it means the identity has been compromised).
  4. stores the keys that the organization uses to authenticate itself for other companies on the platform (associatedKeys).
  5. can have complex governance rules that resemble real-life use-cases (e.g. an LLC owned by two equal partners can be represented by an ORG.ID owned by two Ethereum accounts via a multi-signature wallet).

Info

0xORG canonical implementation can be found on our GitHub. Notes on 0xORG interface can be found in the smart contracts section.

ORG.JSON

If 0xORG is a functional piece of an ORG.ID, ORG.JSON is the actual information record. It can be stored anywhere it can be accessed by other marketplace participants (e.g. via HTTP, FTP, Swarm, IPFS, etc.). Here is an ORG.JSON example (full specification):

{
  "dataFormatVersion": "0.0.0",
  "updatedAt": "2019-06-03T13:20:06.398Z",
  "legalEntity": {
    "name": "Awesome Ltd.",
    "address": {
      "road": "5th Avenue",
      "houseNumber": "123",
      "city": "New York",
      "countryCode": "US"
    },
    "contact": {
      "email": "[email protected]"
    }
  }
}

Comment

The philosophy of ORG.JSON is that it should not change often, and when it does change, the partners of the correspondent ORG.ID should be notified. Either by listening for hash changes in Ethereum events or by using something like a publish/subscribe service.

Trust

Now our marketplace looks like this.

Marketplace 2

It has a major flaw, though: anyone with a laptop can create a smart contract and a JSON file and pretend to be the Marriott. In other words, the system has no trust.

As we noted earlier, there is absolutely no proof that for example Delos is a real hotel. Luckily, Winding Tree has a built-in mechanism for building trust which we call trust clues.

A trust clue is a piece of information that an organization can use to prove to other players its good intent. Even though Winding Tree specifies which clues should be taken into account and how they should be interpreted, each organization has to decide on their own what and how they will use for establishing a trust level.

Trust Clues

Warning

Not all of the following trust clues are currently implemented.

Líf Deposit

The first and most obvious trust clue consists in depositing a certain amount of Líf to a dedicated smart contract. This clue is necessary to protect the marketplace against flooding, i.e. malicious actors that could programmatically generate thousands of ORG.IDs and pollute the network.

The Líf deposit can be withdrawn if, for some reason, the organization no longer wants to be a part of the network. To protect the system from momentary deposits and withdrawals, we implemented a delay in the withdrawal process. Organization that initiated the withdrawal process will have to wait for a month (in reality a certain amount of Ethereum blocks) before they will be able to claim their deposit back, while the whole network will be immediately notified of their intent.

Then again, an impostor may have a few hundred dollars to create a few fake organizations on the platform. How to deal with that? Well, there are many more trust clues that an organization can publish to further prove their authenticity.

Domain Verification

If the ORG.JSON record contains a website address, the domain name can be linked to the ORG.ID via DNS or a text file accessible on a well known address.

Extended Validation SSL Certificate

If a domain that was successfully verified with an associated EV SSL certificate belongs to an ORG.ID, then the data from the certificate (legal address, etc.) are proven to be associated with the ORG.ID.

Guarantor

As we described in our blog post, a small organization could also appoint a guarantor with high level of trust and therefore partake in it.

Whitelist

If you want to trade with a very limited number of partners on the Winding Tree network, perhaps partners you already know, then you don't even need to do anything. Just give them your ORG.ID so they can whitelist it in their access control system.

Business history

If API requests and responses between all these players are signed with their private keys, all these companies have proof that they are doing business together.

Info

You should verify signatures on booking and other incoming requests on your APIs to protect yourself from scammers or misbehaving players.

Let's say a small OTA has a collection of messages (API responses) that contain both ORG.IDs, a simple message ("order confirmed"), and a timestamp, signed by a private key that belongs to a trusted ORG.ID. Now the small OTA has unfalsifiable proof they do business with that organization that they can discreetly share with other ORG.IDs to prove their trustworthiness.

Whom Should I Trust?

Ultimately, you have to decide for yourself. Winding Tree only provides clues and libraries for you to determine the level of trust of your potential partners on the platform.

Aggregation

Now we have a marketplace with organizations that can identify each other and build trust. But how can they find each other?

The Entrypoint smart contract is linked to a few Segment Directory smart contracts. In order to be discoverable as a hotel, Dave has to register the Delos' ORG.ID in the Hotels Segment Directory. Once he does that, Acme will be able to find Delos and identify it as a hotel.

Marketplace 3

Before Dave registers Delos as a hotel, though, he should add an additional data block to his ORG.JSON that contains information about his hotel possibly including an API service.

{
  "dataFormatVersion": "1.0.0",
  "updatedAt": "2019-06-03T13:20:06.398Z",
  "legalEntity": {...},
  "hotel": {
    "location": {
      "latitude": 35.89421911,
      "longitude": 139.94637467
    },
    "name": "Delos hotel",
    "website": "https://delos-hotel.com",
    "apis": [
      {
        "entrypoint": "https://api.delos-hotel.com",
        "docs": "https://developers.delos-hotel.com",
        "format": "ota",
        "version": "2.0"
      }
    ]
  }
}

The same principle would apply for other segments, such as airlines or OTAs.

Direct Connect

After you create an ORG.ID for your company and publish a few trust clues about it, proving that your business is in good standing, and that you're a reliable business partner, you will be able to automatically connect to other companies on the platform via their APIs.

In order to communicate safely, securely and reliably, your organization's software should sign all the requests and responses with one of the associatedKeys presented in your 0xORG. This approach gives all Winding Tree organizations a cryptographically-sound out-of-the-box access control system as well as protection from spam and fraud, also unlocking a variety of use cases that companies on Winding Tree can benefit from.

To make the system work, every participant should also publish information about the minimal trust level that others have to match or exceed in order to connect to their APIs. You should also have a minimum trust level for organizations that you want to work with. Avoid companies with no exposed trust clues at all cost.

Note that Winding Tree doesn't act as an intermediary in any of your business affairs in any way, by design. It means you have to connect to your business partners directly. Usually it would mean multiple integrations and going through lengthy vetting processes. Winding Tree solves the problem of trust and vetting, but your company still has to speak the languages (different APIs) of your partners. To solve this, we're working on open-source adapters between different formats, and the unified exchange data format for hotels.

Reading List