Using IPFS Messaging For Referral Networks

The 2key Referral network is an Ethereum based solution for referral networks, based on a combination of on-chain smart contracts and off-chain link propagation.

A File System — Not so Inter-Plenatary..

2key Network

2key Network is a blockchain-based referral network intended to reward referrers through smart contracts. Referrals progress through the network thanks to people sharing them through their regular browsers. Therefore, 2key generates off-chain cryptographically signed links, which propagate among users without reaching the blockchain. Upon conversion, a user submits the signed link to the smart contract. The smart contract rewards the chain of referrers as represented in the signed link. The smart contract is deployed per referral campaign by the campaign initiator, depositing a referral reward, as an amount of cryptocurrency, from which the smart contract will later pay the referrers.

The Influence Graph

A campaign conducted over the 2key network starts with a source seeding, and proceeds through referrals. The graph of referrals from the source seeding is called the influence graph. Each node in the graph is called a referrer. The node which makes an actual conversion, such as purchasing a product, is called a converter. A referrer leading to conversion is to be rewarded from the campaign budget. Not only is the referral leading to the conversion to be rewarded but also referrals that had some impact on anyone leading to the conversion.

2key is currently working on developing the algorithms for computing rewards which may not be uniform but depend on a reputation model.

At the moment, there are 4 types of incentive models in place:

1. Manual Incentive Model: an upselling model in which each referrer chooses how much of the remaining reward to take, and how much to pay forward
2. Vanilla Equal: which splits the referral reward equally between all referrers on the chain
3. Vanilla Equal + 3X: which splits the referral reward equally, except the last referrer who actually referred the converter, which gets times three the amount of others.
4. Vanialla Power Law: which gives each referrer twice as much as the previous one, the closer they are to the converter.

The Ethereum Implementation

2key is implemented with a smart contracts architecture containing bother ephemeral and singleton contracts. Each campaign deploys a new batch of ephemeral contracts (you can read more about it on our contracts repo at https://github.com/2key/contracts). Rewards are paid through the campaign contracts.

There is nothing in 2key that is inherently Ethereum specific. But we do use the Ethereum capabilities in terms of signing messages and having contracts with no hardwired addresses.

The Missing Direct Connection

A major problem in the referral network is how do you keep the direct connection to the whole network. In traditional referral networks, where everything goes through one central site in which each referral link is generated, it is relatively easy. You must go there if you are in the influence graph.

But a decentralized solution like 2key Network, there is no central hub. Yet, you do not want your influencers to be left in the dark. Especially as our reward model is intended to engage everyone in the referral network that contributed to a conversion. This includes influencers that are on the referral chain leading directly to a conversion, but also other influencers that prior to the actual conversion reached a converter, directly or indirectly, as it is well known that accumulating influence on an individual eventually at some point tilts the balance in favour of conversion.

This need for a global view of the referral graph is important for implementing the reward model, as we want to propagate the information on coming reward distribution to anyone involved. And do this while we only have in hand the information on the conversion and the last referral chain ending in a conversion.

The Rise of IPFS-Based Messaging

There is a rise in platforms building messaging on top of IPFS, possibly with integration to an Ethereum smart contract registry of users.

KeySpace: End-to-End Encryption Using Ethereum and IPFS

AirSwap is a P2P cryptocurrencies exchange that developed a secure P2P messaging protocol KeySpace. KeySpace uses an Ethereum smart contract as a registry of users. Each user address is mapped to an IPFS file storing an encrypted PGP private key and PGP public key.

This is how the system functions during active use between Alice and Bob: On airswap.io, all direct messages need to be encrypted, so when Alice starts a new chat with Bob, the app looks up the IPFS hash of Bob’s PGP public key on the contract. Before sending a message to Bob’s Ethereum address, the app encrypts the message with Bob’s public key. It also attaches a copy of the message encrypted with Alice’s public key so she can decrypt her sent messages at a later date. When Bob receives an encrypted message, the app decrypts it with his PGP private key (after decrypting it with his signed-seed).

Textile Decentralized Chat App

Textile is a forthcoming photo sharing network based on IPFS. As described in Build a Decentralized Chat App with Knockout and IPFS, they have developed a chat app based on IPFS.

IPFS Pubsub room creates a room based on an IPFS pub-sub channel. Emits membership events, listens for messages, broadcast and direct messages to peers.

One connects to IPFS:

const setup = async () => {
  try {
    ipfs = new IPFS({
      // We need to enable pubsub...
      EXPERIMENTAL: {
        pubsub: true
      },
      config: {
        Addresses: {
          // ...And supply swarm address to announce on
          Swarm: [
            '/dns4/ws-star.discovery.libp2p.io/tcp/443/wss/p2p-websocket-star'
          ]
        }
      }
    })
  } catch(err) {
    console.error('Failed to initialize peer', err)
  }
}

One then defines a chat room, with an arbitrary choice of the chat room name:

try {
      ipfs.on('ready', async () => {
        const id = await ipfs.id()

            const roomID = "test-room-" + Math.random()
        // Create basic room for given room id
        const room = Room(ipfs, roomID)
        // Once the peer has subscribed to the room, we enable chat,
        // which is bound to the view model's subscribe
        room.on('subscribed', () => {

  })

Then we send messages:

// Broadcast message to entire room as JSON string
room.broadcast(Buffer.from(JSON.stringify({ name, text })))

When we receive a message:

room.on('message', (msg) => {
  const data = JSON.parse(msg.data) // Parse data
})

2key IPFS Messaging

To make information propagation across the campaign in a one-to-many fashion, let us construct an IFPS chat room for a campaign. The chat room will be created by the 2key backend at the start of the campaign. A user browser will subscribe to the campaign upon generating the signed linked. The user Ethereum address and the signed link would be sent to the chat room. Thereby the campaign will have a complete picture of the influence graph at each moment.

Upon conversion, the 2key backend will send the relevant part of the influence graph to the campaign contract. The relevant part is that part which would be considered for a reward due to the conversion.

The relevant part can be defined as follows:

1. Going backward from the converter to each referrer in the referral chain.
2. Continue walking backward until reaching the source seeding
3. All nodes reached are relevant

The campaign contract will calculate the rewards, and send an event with the list of addresses and assigned rewards.

The 2key backend using the chat room will broadcast the message to the chat room. Each influencer browser upon receiving the message will search for itself in the list to see if it is rewarded. If this is the case, it will send a reward transaction to the smart contract in order to get the reward.

Bringing an Influencer Up to Speed

Naturally, this solution raises the question of what happens if an influencer is not online. It would miss the conversion message in the chat room, and miss its reward unless we have some persistent storage of these reward distributions.

We can achieve this persistent storage through either an on-chain or off-chain storage:

1. Upon computing the reward distribution, it is stored in the smart contract so the influencer can retrieve its reward information from there. This approach is straightforward but requires a call to the blockchain (but with zero gas needed)
2. The 2key chat room stores reward distribution messages in IPFS and upon a user joining the room broadcasts the accumulated list.

The off-chain approach has a shortcoming that one has to know how to retrieve the past messages. A centralized solution with a server and a database would do it. But we are striving to a decentralized solution.

Is the Messaging Decentralized?

Anyone can listen to the campaign events and run a chat room. But we need to decide on a unique name, and the Ethereum address of the campaign is a natural decentralized choice.

So using web3.js, we upon start, we can retrieve past conversion events:

myCampaingContract.events.Converision(
    {
        filter: {...}, 
        fromBlock: 0 // better here the block where the campaign 
                     // was deployed
    }, 
    (error, event) => { console.log(event); }
)
.on('data', (event) => {
    console.log(event); // same results as the 
                        // optional callback above
})
.on('changed', (event) => {
    // remove event from local database
})
.on('error', console.error);

So coming online, one can retrieve the conversion events and just broadcast them to the room.

Conclusion

We have described a significant enhancement of 2key referral networks enabling implementation of our reward model based on decentralized messaging.

Now influencers no longer have to poll the campaign contract, but can be actively informed upon a reward assigned.