bch-dex/dev-docs/specification.md

Tor-List-API Specification

This document contains a high-level, human-readable specification for the four major architectural areas of the tor-list-api:

• Entities
• Use Cases
• Controllers (inputs)
• Adapters (outputs)

This reflects the Clean Architecture design pattern.

Entities

Entities make up the core business concepts. If these entities change, they fundamentally change the entire app.

Website

The tor-list concept is all about curating deep-web websites that may have unusual or ephemeral address and may exist on different parts of the internet, like IPFS, Tor, or lightly supported TLDs like .eth. These Websites Entities have the following properties:

• url - not restricted to common TLDs. This could have an address to an IPFS gateway, a .onion, .eth, or other type of address.
• address - A blockchain address associated with the website. This address is used to evaluate the merit value of the site. In the future, it can be used by the site owner to communicate additional information using the PS001 specification.
• blockchain - The blockchain the address above belongs to. Default value is BCH
• merit - A merit score for the website. This is used to rank sites within their category. The value is calculated and updated every 24 hours.
• merit timestamp - A timestamp of when the merit of this entity was last calculated.
• mainCategory - A string categorizing the website. (e.g. Tor websites)
• subCategory - A string categorizing the website within the main category. (e.g. 'Email' services, within Tor websites)
• description - A long-form string describing the website.
• isBlacklisted - A Boolean. Set to false by default.

Blacklist

The blacklist entity points at a Website entity. It's purpose is to identify P2WDB entries that should not be displayed on the front-end. It has the following properties:

• hash - The OrbitDB hash of the Website entity, used to identify it in the P2WDB.
• txid - The TXID used as a key to identify the Website entity in the P2WDB.
• reason - A string indicating the reason why an admin chose to blacklist this website.

Category

The Category Entity holds data about entries that fit within a single category. Having an entity reduces the computational load, because data can quickly be looked up in the Category Entity, and the values of that Category Entity can be recalculated asynchrously. e.g. The time information is retrieved and the time information is updated are different.

• websitesAll - An array of Mongo IDs of Website Entities. Every Website Entity assigned to the category should appear in this list.
• websitesTop - An array of Mongo IDs of Website Entities. This contains a sorted list of the top 100 websites, based on merit.

Use Cases

Use cases are verbs or actions that is done to an Entity or between Entities.

• Delete - This is actually not a use case. It's mentioned here to point out that deleting websites is not necessary. Users can instead move their PSF tokens to a different address, and the merit will go to zero. This will cause the website entry to drop to the bottom of the rankings for its category. Entries with zero merit will be ignored, or possibly garbage-collected.
• Add to Blacklist - This is an action that can only be performed by a logged-in user with admin privledges. This allows the admin to prevent entries that violate the ToS from being displayed.
• Get Merit - Read the merit value of the Website Entity.
• Update Merit - Recalculate and update the merit value of the Website Entity.

Controllers

Controllers are inputs to the system. When a controller is activated, it causes the system to react in some way.

• POST Webhook - This POST REST endpoint will be triggered by a webhook generated by the P2WDB. This will notify the tor-list-api that a new entry has been added to the P2WDB that matches the appId of torlist. It's a new entry that should be evaluated for inclusion in the tor-list-api local database.
• GET by Category - Return the 100 top-ranked Website Entities within a specific category, and with a merit above zero.
• POST Blacklist - Creates a new Blacklist Entity. This endpoint is only accessible by an Admin user.
• 24 hour Timer - A timer which triggers every 24 hours, sets off an update of the database. When it triggers, the following actions should take place:
  • All the website entities should be added to a retry-queue. Highest-merit websites are processed first, lowest merit last.
  • The server will recalculate the merit for each Website Entity in the queue.
    • TODO: Figure out a good garbage collection scheme to remove websites that consistently have no merit.
  • The server will update the 'top 100' in each Category Entity.

Adapters

Adapters are output libraries so that the business logic doesn't need to know any specific information about the I/O. They are essentially the output of the application.

• localdb - An adapter for the local database (MongoDB).
• ipfs - An adapter for IPFS and the ipfs-coord library. It allows the app to use the JSON-RPC over IPFS.