Web App User Guide - notatestuser/chainline-webapp GitHub Wiki

Introduction

Thanks for being among the first to try Chain Line!

Chain Line is a trustless peer-to-peer shipping network powered by a smart contract.

There are three main journeys to try in the web app interface. This guide will touch upon what those are in order to provide a brief overview of what you can do with Chain Line and its smart contract.

Concepts

  • Demand - A request for a shipment to be made. This could be for a product, a package from a friend, or similar. The courier is well within their rights to reject a shipment if they do not agree to carry it, so only legal and reasonable demands can go through the entire lifecycle of the system to become complete transactions.

  • Travel - A record of travel for a courier or shipping company. This essentially records information such as dates, their maximum carry space for items and the user reputation required of the demand owner in order to make a match.

  • Match - The association of a Demand to a Travel, performed automatically by the contract.

  • Tracking - You can track either the Demand or Travel mentioned above using the tracking ID given to you upon creating a Demand or Travel.

  • Reserved Funds - A portion of a wallet's balance that cannot be spent for a certain period of time unless sent to their intended recipient. Permission to make any withdrawal of funds is either granted or denied by the central "hub" contract which each verification script "calls home" to upon processing a withdrawal from a user's wallet. If there are actively reserved funds held on the account and the withdrawal amount exceeds the available balance ("effective balance") the request is rejected and the transaction cannot proceed.

  • Reputation - A user's reputation score, incremented automatically each time they participate in a successful transaction.

Shortcuts (Demo Links)

If you don't have TestNet GAS or want to quickly take a look at some various matching states, check out these links:

User Journeys

  • You are a "demand owner" looking to ship a product from elsewhere to your location.
  • You are a courier / traveller who has the capacity to transport those items (they could be an individual or a shipping company).
  • You are someone who wants to track one of the above, either a third party or the original creator.

It is recommended that you find a partner to do each journey (one demand, one travel) so that you can get a match and see the progression through the states from both ends. Just make sure that your parameters match up (these are described in step #6 in each of the journeys below).

Journey 1 - Creating a Demand

  1. First you'll want to log into or create a wallet. Click the button in the far top right corner and use the options to create one. The wallet is not sent to a server and all processing happens on the front-end.

  2. Send enough GAS to this wallet to create a demand. Click "Receive" at the top to see your address. GAS needed: [item value] + 4 GAS fee + invocation GAS cost. You can leave this until after step 4 if you would like to know exactly how much you need - the form will tell you.

  3. Use the dropdown box on the home page to select the first option, which will take you to the demand creation page.

  4. Fill in all of the details on the form. It should be pretty self-explanatory. Any GAS you have to pay to make the creation process go through are explained to you in the UI.

  5. When you have created your demand you will be taken to the tracking page for that demand. The tracking page will tell you its status and whether it has been matched. Be sure to write down the "tracking ID" so that you can visit later if you have not been matched with a courier yet.

Note: The value of the item and the reward fee (4 GAS) will now show as "reserved" in your wallet and cannot be transferred out until completion or expiry of the transaction.

  1. To get your demand matched with a travel the following conditions must be met:
  • There must be a travel that expires within the expiry time of your demand with the same cities set.
  • The maximum carry space of the travel must be greater than or equal to the "item size" you selected in your demand.
  • Your "user reputation" score must be greater than or equal to the minimum requirement set in the travel.

Note: You should collaborate with someone else to create a travel that satisfies these conditions, and then you will see the matched status on the tracking page. Alternatively, do it in another browser tab.

  1. Follow the instructions on the tracking page to complete the exchange after a match. You will send the funds to the traveller from the tracking page when the transaction is complete. This will "unlock" the reserved funds held on your wallet and increase each participant's reputation scores.

Journey 2 - Creating a Travel

  1. Log into or create a wallet, same as before.

  2. Send enough GAS to this wallet to create a travel. Click "Receive" at the top to see your address. GAS needed: 2 GAS deposit + invocation GAS cost. You can leave this until after step 4 if you would like to know exactly how much you need - the form will tell you.

  3. Use the dropdown box on the home page to select the second option OR scroll to the bottom of the page and click the link that reads "Register your travel", which will take you to the travel creation page.

  4. Fill out the form shown on that page. Please use Chrome or a Chromium-based browser for this form. Other browsers do not seem to adequately support the datetime-local input control used on this page.

  5. You will be taken to the tracking status page after the blockchain invocation has been performed.

Note: The deposit (2 GAS) will now show as "reserved" in your wallet and cannot be transferred out until completion or expiry of the transaction.

  1. To get your travel matched a demand the following conditions must be met:
  • There must be a demand that expires after the expiry time of your travel.
  • The demand must be present with the same cities that you chose in your travel.
  • The "carry space" you selected must be able to accommodate the item size of a matchable demand.
  • Your "user reputation" score must be greater than or equal to the minimum requirement selected in the demand.

Note: It is recommended that you collaborate with someone else to create a demand that satisfies these conditions, and then you will see the matched status on the tracking page. Alternatively, do it in another browser tab.

  1. Follow the instructions on the tracking page to complete the exchange after a match. You will receive funds from the demand owner from the tracking page when the transaction is complete, and this will increase your reputation score.

Tracking Journey

  1. Click "Tracking" in the top header bar. You will have to enter the tracking ID given to you when you created your Demand or Travel, and input the same cities you used before again in the popup.

Alternatively, you can save the URL that it takes you to when the demand or travel is created, and going back to that will take you to the same tracking page you saw before.

Funds and Withdrawals

You can see the funds you have reserved in the top header after you have logged in. The reserved funds are deducted from your address's actual balance. You can expand that menu to see a readout of the reserved funds and also your reputation score.

Any funds that are reserved by the Chain Line hub contract are still present in your wallet and remain under the control of your private key. They are not transferred to any contract or wallet.

Learn more about the Smart Wallet and Reserved Funds

Other Links