NAV Navbar
html javascript json
  • Introduction
  • Platform Components
  • Architecture
  • Getting started
  • Authentication & Identity
  • Listing Schemas
  • Objects
  • Functions
  • Getting help
  • Contributing
  • Introduction

    Origin provides a simple and powerful javascript library for developers to build decentralized marketplaces, allowing buyers and sellers to meet and transact without requiring any trusted intermediaries.

    Usage

    Visit our Github: https://github.com/OriginProtocol/origin-js

    This API documentation will explain how developers can use the origin.js library to create and manage decentralized marketplaces that are built on top of IPFS and the Ethereum network.

    Origin.js aims to create an easy and flexible abstraction layer that:

    Origin.js will enable developers to create DApps that onboard new users to the Origin platform, add new listings to the listings registry, create booking contracts, close out bookings (transfer funds, write reviews, etc.), and more.

    Notes

    Please note this project is still in heavy development and many of the features described below have not been implemented yet. This library should not be considered as production-ready.

    Origin.js and the entire Origin Protocol project is 100% open-source and we welcome contributions from the community. There are many ways to help, from reporting issues and contributing code to helping us improve and grow our community.

    If you are interested in getting involved, please read our section on contributing. If at any point you get stuck, please reach out and we'll do our best to help.

    Platform Components

    Origin.js provides the interface for developers to interact with the rest of the Origin platform, all without writing Solidity code or managing IPFS instances.

    At a high-level, the Origin platform consists of user, listing, and booking data and logic stored on the decentralized tech stack. Mission-critical data and logic such as booking availability, transaction history, and escrow rules are generally stored on chain in a series of Ethereum smart contracts. Related metadata such as listing descriptions and images are stored on IPFS, with pointers to this data in the form of content hashes being stored on chain.

    User Registry

    The Origin user registry is a datastore of all Origin-enabled users. Origin users are identified by their Ethereum wallet addresses. In addition, the user registry also stores a mapping of all forms of identity verification that the user has successfully undertaken.

    For example, users may want to verify their identity with third-party services like uPort or Civic, or use publicly-auditable proofs to verify their social media profiles. These identity "proofs" are referenced within the user registry so that DApps, and ultimately counter-parties, are able to verify the validity of these users.

    Origin.js enables developers to register users to the shared user registry, as well as query for identity verifications.

    Listing Registry

    The listing registry stores all valid Origin listings, from cars for rent to freelance design services. Developers will be able to create new listings in JSON, then push them to the Origin listing registry. Under the covers, Origin.js handles the creation of new IPFS content files for static metadata and new entries to the Origin listing registry smart contract.

    Note that Origin.js does not support browsing and searching the listing registry directly. It is recommended that developers use our open-source server-side indexing service (or build your own) to efficiently query the blockchain.

    Booking Contracts

    Booking contracts are automatically created when buyers book listings on Origin-powered DApps. These individual smart contract instances are generated and deployed with rules around price, reservation time, and payment rules. For certain listing types, Origin.js will also generate additional contract code for arbitration, escrow, deposits, payment schedules, etc.

    Contract Modularity

    Origin smart contracts are designed to be flexible and modular. We recognize the need for developers and entrepreneurs to have choice in selecting smart contract components that tailor-serve their needs.

    To that end, we will provide default contracts for escrow, arbitration, and insurance that will be inherited by our booking smart contracts. However, developers will be able to specify alternative contracts of their choosing (either their own or approved third-party contracts) in Origin.js function calls to generate custom booking contracts.

    Architecture

    If you're new to the space, it may be helpful to first familiarize yourself with some of the core technologies that we're using to build Origin, such as JSONSchema, IPFS and Ethereum.

    Origin listings can be created using a frontend DApp to publish a JSON data object to any publicly writeable IPFS gateway. This JSON data object must conform to a set of standards and validation rules to be considered valid on the network. Users can optionally sign their listings cryptographically to verify their identity using publicly auditable proofs or trusted third parties. The IPFS gateway will publish the listing to the IPFS network making the listing instantly available via hundreds of distributed computers around the world to anyone who knows the content hash. The content hash of the listing is then sent to a smart contract which formally publishes the listing and stores pricing and availability information along with any specified booking rules and policies.

    Listings can easily be searched, browsed, and booked via a frontend DApp. Since we anticipate having too many listings to reasonably parse in a browser, the frontend DApp connects to an open-source indexing server of the user’s choosing, making it possible to search and filter the entire public corpus of listings. Once a listing has been selected, a user can make a booking by sending payment to the booking smart contract along with the IPFS hash of the chosen listing and the desired interval to book. The smart contract will verify that the booking is valid and handle the transfer of tokens between the buyer and the seller, including the escrow of funds when applicable.

    We anticipate most sellers will prefer to list their prices in fiat currencies which often have less volatility than digital currencies. To solve this challenge, both the booking smart contract and the indexing servers will use a common set of oracles and a shared algorithm to determine the exchange rate to be used. This allows prices to be shown to end users in their preferred fiat currencies while the correct amount of digital tokens are sent during the booking. A diverse set of oracles will be chosen to avoid introducing single points of failure into the system.

    Sellers are responsible for disclosing their preferred messaging channels in their listings through which buyers can contact them before, during, or after a transaction. Buyers can similarly indicate their preferred messaging channels when they complete a booking. Non-transactional communication between buyers and sellers will occur off-chain, and both parties are encouraged to only use secure and verifiable communication channels. For transactions that have a possibility of needing arbitration, a multisignature messaging channel should be chosen that includes the arbitrator in all communications.

    Once a transaction is complete, users are encouraged via economic incentives to leave feedback about the interaction in the form of a rating or review. Once again, the content is stored on IPFS and only the content hash is stored on Ethereum. Users are able to establish their reputations over time with verified transactions, building a unified reputation across multiple listing verticals. Buyers can use different wallets with varying levels of identity attached for sensitive transactions, or choose to only reveal their true identity to the seller while using a throw-away wallet.

    Listing policies around escrow, refunds, required deposits, and cancellations are set by the seller and are strictly enforced by the booking smart contract. Any exceptions to the policies must be handled directly off-chain by the two parties.

    JSONSchema

    Learn more about JSONSchema

    Ethereum

    Learn more about Ethereum

    IPFS

    Learn more about IPFS

    Getting started

    Download Origin

    Origin.js is under active development. Our upcoming 0.1 release will be available at our Github repo soon.

    Use an Ethereum browser

    For testing and interacting with your DApp, you will need to use an Ethereum-enabled browser. Currently, we recommend using Metamask with Chrome.

    Install the Metamask Chrome Browser Extension. This will enable you to connect to the Ethereum network from your browser. Metamask allows you to run Ethereum DApps right in your browser without running a full Ethereum node.

    Alternatively, you can run the official Ethereum browser Mist.

    Acquire Test ETH

    Our smart contracts are currently deployed on the Rinkeby testnet. You will need to have test ETH to use this library. You can request test funds from the Rinkeby faucet. Do not yet send real ETH on the Origin network. Use Rinkeby testnet ETH instead.

    Hello World

    Simply include the downloaded javascript library in your html to get started.

    Sample app

    <html>
    <title>Hello World</title>
    <body>
      <script type="text/javascript" src="origin.js"></script>
    </body>
    </html>
    
    var origin = new Origin();
    
    var user = new User();
    user.name = "Joe"
    
    var listing = new Listing();
    listing.owner = user
    
    listing.save()
    
    

    Authentication & Identity

    Identity verification

    Users identities are tied to Ethereum addresses and your private keys are used as the sole method of authentication on the Origin platform.

    Users can always prove ownership of a wallet without sending funds, simply by signing a message using their private keys.

    Users can assume multiple identities by creating multiple wallets. In this manner, users can choose how much of their off-line identities they wish to reveal to other users while participating on the Origin network.

    Origin allows users to identify themselves using publicly auditable proofs and attestations from trusted third-parties.

    Publicly-Auditable Proofs

    A user can choose to identify themselves on other platforms using publicly auditable proofs. A user can post their public key on Facebook or Twitter and then cryptographically sign their listing using their private key. Users can then include links in their listings to the Facebook post, tweet or website that displays their public key. In this manner, anyone can independently verify the poster’s identity, or at least confirm that they control those accounts or domain. Origin.js simplifies this process for users by making it easy to generate these proofs and verify the proofs of other users. As people share their identity proofs on Facebook and Twitter, it will help create network effects as friends learn about Origin and decide to participate.

    Trusted Third-Parties

    Users can also collect verifications from trusted third-parties like Civic, uPort or the Origin Foundation. These third-party providers can provide identity verification that interfaces with the offline world. For example, a third-party identity provider may help confirm a physical address by sending a postcard with a special code to that address and then having the user enter that code on a website. Similar methods can be used to confirm control of a phone number or email address. Trusted third-parties can also verify government IDs like drivers licenses and passports which are required for certain types of listings like car rentals.

    Listing Schemas

    Since many unrelated developers will be reading and writing to the same data layer, it is essential that everyone adhere to common standards. We will publish and maintain the rules for what constitutes a “valid Origin listing” as well as a library of inheritable JSON schemas for fields commonly used on listings, such as email addresses, URLs, GPS coordinates, international street addresses, international phone numbers and other metadata. These schemas are also easily extensible enabling the creation of new product categories, support for internationalization or other languages as well as other unforeseen use-cases.

    Base Schema

    Every Origin listing must contain some standard fields in order to be considered valid.

    Example Schemas

    Example schemas can be found in the Schemas repository. These need a lot more work.

    Inheritance

    Inherit commonly used fields like:

    Extensibility

    Objects

    User

    Listing

    Booking

    Feedback

    Ratings

    1-5

    Reviews

    String

    Comments

    String

    Functions

    Browse Listings

    Search Listings

    Create Listing

    Update Listing

    Deactivate Listing

    Book Listing

    Leave Feedback

    Messaging

    Getting help

    Slack

    Our team collaboration is done in public and our company Slack is open to all. If you have questions or need help getting started, our Slack channel is a great place to get assistance from our team of engineers and developers.

    Request an invite to join the Origin Protocol Slack

    Once inside, find us in one of the eng channels.

    Email

    You can also reach us by email at support@originprotocol.com.

    Contributing

    Want to hack on Origin? Awesome! Here are instructions to get you started. They are not perfect yet. Please let us know what feels wrong or incomplete.

    Origin is an Open Source project and we welcome contributions of all sorts. There are many ways to help, from reporting issues, contributing code, and helping us improve our community.

    Dive Right In

    If you're ready to start hacking on Origin right now and you just need an issue to focus on, check out this search of all our currently open issues on Github.

    Read our community guidelines first and have fun!

    Protocol Design

    When considering protocol or implementation design proposals, we are looking for:

    Please note that protocol design is hard, and meticulous work. You may need to review existing literature and think through generalized use cases.

    Community Guidelines

    We want to keep the Origin community awesome, growing and collaborative. We need your help to keep it that way. To help with this we've come up with some general guidelines for the community as a whole:

    Reporting Issues

    If you find bugs, mistakes or inconsistencies in the Origin project's code or documents, please let us know by filing an issue at the appropriate issue tracker (we use multiple repositories).

    Security Issues

    The Origin Protocol and its implementations are still in heavy development. This means that there may be problems in our protocols, or there may be mistakes in our implementations. We take security vulnerabilities very seriously. If you discover a security issue, please bring it to our attention right away!

    If you find a vulnerability please send your report privately to security@originprotocol.com or contact Josh Fraser via Keybase. Please DO NOT file a public issue.

    If the issue is a protocol weakness or something not yet deployed, just discuss it openly.

    Community Improvement

    Origin is just as much about community as it is about our technology.

    We need constant help in improving our documentation, building new tools to interface with our platform, spreading the word to new users, helping new users getting setup and much more.

    Please get in touch if you would like to help out. Our community channel on Slack is a great place to share ideas and volunteer to help.

    Full Time Positions

    Origin occasionally hires developers for part time or full time positions.

    We have a strong preference for hiring people who have already started contributing to the project. If you want a full time position on our team, your best shot is to engage with our team and start contributing code. It is very unlikely that we would offer you a full time position on our engineering team unless you've had at least a couple approved pull requests first.

    If you are interested, check out the Origin Protocol job listings. If you'd like to help in other ways, propose your ideas on the Origin Slack.