Factbar Documentation


Introduction

Factbar is a markets-based system for ranking and organizing facts about our world. It allows for the generation and claiming of "Factbars," which are unique digital collectibles and instruments designed to bring contested facts into public view, where they can be fact-checked by a formal process of issues, comments, and revisions.


How It Works

Every available Factbar corresponds to one unique fact. In turn, each Factbar is a unique cryptographic token in our smart contract. If you claim it, you own it, and your ownership is noted on a three-dimensional simulation of the Factbar, as well as on the Factbar Leaderboard.

Factbars are visible on the Ethereum Blockchain as units in a smart contract. Just like any ERC721 token, Factbars may be traded by market participants, but they may also be "claimed" by a special process encoded in our smart contract. To claim one, you need to use Ether, the common currency of the Ethereum Network. Each Factbar works similarly to a token or coin and can only be claimed by one Ethereum address at a time. Typically each address will be controlled by one individual, however that implementation is left up to the claimant.

Once registered, you may claim any available Factbar on the leaderboard. Anyone else can subsequently claim your owned Factbar by paying you the new price that was calculated in the smart contract upon your acquisition of the Factbar.

The price increase per additional claim is pre-determined, and follows this progression:

Progression Tier Price Range Price Increase Claim Fee
Tier 1 0.001 ETH - 0.02 ETH 100% 5%
Tier 2 0.02 ETH - 0.5 ETH 35% 4%
Tier 3 0.5 ETH - 2.0 ETH 25% 3%
Tier 4 2.0 ETH - 5.0 ETH 17% 3%
Tier 5 5.0 ETH - 15% 3%

When a market participant claims a Factbar, the current claimant is automatically compensated by the smart contract. The full amount of the Price Increase combined with the previous purchase price of the Factbar, less the Claim Fee, is made available for withdrawal by the current claimant, and the Factbar is assigned to the new claimant. The Claim Fee is retained by the Factbar system itself, to be used to finance the maintenance of the application.


About Our Smart Contract

The source code of the contract is publicly available here, or at: 0x7da47CA0dE0797fFeDfEa9194cAc9A8A5d0cD0CC. The public functions of the contract can be performed from any client or scripting tool, such as remix, web3, or truffle, but we recommend that non-technical users make all transactions directly from the leaderboard.


ERC721 Compliance

Factbar's smart contract is compliant with the ERC721 Token Standard as it existed in January of 2018. Our contract is based on OpenZeppelin's February 2018 ERC721 template. Factbars may be transferred using the ERC721 transfer functions which were standard at the inception of our smart contract; however, these transfers are not tracked by our application and will not trigger a rewrite of the claimant name data on the asset. Additionally, the price points of any transactions made using standard ERC721 functions will not be recorded in our smart contract, as this data may not be publicly available at all. If you purchase a Factbar on the secondary market, the asset remains "claimable" at the next price as written into the blockchain, regardless of the price at which you acquired it. Therefore, although it is possible to gain ownership of a Factbar via any means, and you may freely do so, note that only claimants using our smart contract have the ability to write a new claimant name into the asset, and this only happens once per claim, at the moment of claiming. Our website currently will only reflect the most recent claimant data, however, as there is demand, we may also track and publish other ownership data associated with Factbar transactions on the secondary market.


Withdrawal

For security reasons, Factbar uses the withdrawal pattern, which requires all users to make their own withdrawals over the Ethereum network. If you claim a Factbar, and someone claims it from you, you need to affirmatively withdraw the fees payable to you. When our application connects with your Ethereum client (such as Metamask), if it sees that you have more than 0.00005 Ether to withdraw from the smart contract, it raises an alert. Within 15 seconds of the Ethereum network forming a consensus on the existence of a new claim on a factbar, the previous claimant should see this alert raised above the leaderboard on the home page.


Bulk Approval Protection

To help protect claimants from attacks intended to trick them into transferring all of their Factbars to a third party in one transaction, Factbar's smart contract does not implement any of these ERC721 functions: authorizeOperator, approveAll, disapproveAll, deauthorizeOperator and setOperatorAuthorization.


The Factbar Lifecycle


Fact Submission

Facts may be submitted to factbar using this link. No login is necessary to submit a fact, and Factbar does not currently collect any personally identifiable information associated with these submissions. Fact submissions must include text of no more than 130 characters, and a link to a credible Reference on the web, defined as a published, persistent and authentic source of information about a fact. All submitted facts must currently be written in English.


The Editorial Process

Facts submitted to Factbar which meet minimal sanity checks for seriousness, grammar and punctuation are added to the Factbar leaderboard. Following this, any registered user of the website may raise an Issue, either on the text of the Factbar itself, or on the reference(s) used as support to the Fact. These issues in turn may have many comments, which again may be created by any registered user. Users may submit additional references, either negative references which would serve to disprove a fact, or positive references, which serve to support a fact. These references may, in turn, also have comments. In order that Factbar can prevent DDOS attacks and spam, users are required to log into our website to submit issues, references and comments. Users are not required to claim any Factbars to participate in the editorial process.


Amendments

Facts can and do change over time, or may be contested. Factbar's algorithm will surface facts that are the most contested, both with textual analysis and by analyzing other ranking factors including the quality, quantity, and disposition of issues, comments, and both negative and positive references. When a determination is made by our editors that the body of evidence is overwhelming, an amendment will be issued, consisting of a formal, dated change to the text of a Factbar, where both the previous and new text are documented, to be permanently recorded in our the history of the token. Amendments have no effect on claims or any other ownership status of a Factbar, to ensure that the editorial process is decoupled from the ownership and claimant status of the underlying asset.


Claims And The Editorial Process

The Factbar system loosely couples the ownership of an asset to a formal, public, and chronologically tracked editorial process on that same asset. Importantly, claimants of Factbars have no particular power with regard to the textual content of the asset, but, do have the power to publicly associate a chosen claimant name with an asset that they control, thereby bringing attention to the editorial process which is in progress. In turn, when the editorial process results in a public amendment, that amendment's changes to the Factbar's textual payload may affect market prices for the underlying asset. This loose coupling of price and semantics is an intentional feature of the Factbar system.


Editorial Standards


References

When submitting a reference to accompany a new fact, or proposing a new reference for an existing fact, users are required to link to an authoritative external source. These sources must adhere to strict editorial standards. Acceptable references:

  1. Must come from a reliable source with a reputation for fact-checking and accuracy
  2. Must directly engage with the Fact
  3. Must not have been superseded by newer information
  4. Must not exist primarily to sell products or services
  5. Must not be a self-published source
  6. Must not point to another Factbar

Issues, Comments, and Claimant Names

Members of the public may raise issues and make comments on existing Factbars, and may register a claimant name associated with an ethereum address. Anyone may do this, and the ability to do so is not in any way linked to ownership or claimant status on any Factbar assets. We do enforce the following community guidelines on comments, issues, and claimant names. User-contributed content:

  1. Must not be pornographic or sexually explicit.
  2. Must not encourage others to do things that might be dangerous.
  3. Must not promote or condone violence or descrimination against individuals or groups based on race or ethnic origin, religion, disability, gender, age, nationality, veteran status, or sexual orientation/gender identity, or whose primary purpose is inciting hatred on the basis of these core characteristics.
  4. Must not constitute harassment, abuse, defamatio, or libel against a private individual.
  5. Must not be misleading, spam, or commercial in nature.
  6. Must not infringe any existing copyrights.
  7. Must not be posted such as to impersonate any person or organization.

The Factbar Asset


Durability

Claimants to Factbars, or any other digital asset, should understand that they are purchasing a claim on a cryptographic token, whose security is only as good as the network on which it is encoded. Because of the severe scaling challenges that the Ethereum network currently faces, at this time, much of the metadata associated with each Factbar -- including all comments, issues, and revisions -- are stored off of the blockchain, in a Postgres 10.2 database, following industry standards set by cryptokities and cryptocountries. Factbar does make publicly available a data feed which includes a complete catalog of all existing Factbars. For personal archiving purposes, you are granted a licence to download and save this data in JSON format, using this link. Institutions and for-profit entities should contact us for a license to redistribute this data.


Simulations

Factbars are represented by rendered three-dimensional simulations. Claimants to Factbars should understand that these simulations are computer-generated and are not photographs or likenesses of any physical object. A Factbar may have many simulations, and simulations may change in the event of an amendment to the Factbar's text payload, or after an upgrade to our simulation rendering system. The "Claimed by" area of the most recently rendered simulation of a Factbar will always identify the registered name of the current claimant to the Factbar.

Technical Notes


The Ethereum Network

Currently, Factbars are tracked on the Ethereum network. A full explanation of this network is beyond the scope of this documentation, however we would like to point interested parties toward this book and this documentation. The more you understand about the network, the better you will understand how Factbar works.


Claim & Withdrawal Latency

As you claim Factbars or withdraw payments when Factbars are claimed from you, you will note that after a successful claim (or withdrawal), our system asks you to wait about thirty seconds, but you might find that your action is confirmed sooner than this. This is because the Ethereum network has a "heartbeat" of about fifteen seconds, so the network can generally be expected to only confirm an action after this time has passed. We pad this time by an additional fifteen seconds to allow our system time to query the network and provide the data to the end user.


Withdrawal Transactions

Our system does not charge any fees for withdrawal of payments to you which have accrued from claims on Factbars; however, you will have to spend a very small amount of Ethereum to withdraw proceeds from Factbar -- typically not more than a couple of pennies in US currency per withdrawal, regardless of the amount of the withdrawal. This is because every transaction on the network has a cost, payable in gas. This cost will vary over time depending on conditions on the Ethereum network.

Additionally, when you make a withdrawal using Metamask, Metamask will show an "Amount" of 0 (zero). Technically, this is correct, because you are sending zero Ether with your withdrawal transaction. Metamask does not "know" your existing balance in the contract, and therefore cannot show you the amount of your actual withdrawal. However, after you submit the transaction, you will be able to see the amount of your withdrawal in the Etherscan transaction log.


Off-Website Withdrawal

Our system will prompt you with a notice when you have a pending withdrawal exceeding 0.00005 Ether, and you may make your withdrawal at that time. You may also check for, and make, withdrawals at any time without using our website. By using a client such as remix, you may call the withdraw() function at any time to make your withdrawal.


Login And User Accounts

Factbar has two separate user account and login processes, in order to ensure that our editorial and claiming processes do not become entangled.

To claim a Factbar, you don't have to provide an email address - you need only to provide an Ethereum address via Metamask or another web3 browser. You do however have to provide a "claimant name" -- this name will be written into any Factbar asset that you claim. Note that this claimant name cannot be changed, and if you would like to claim a Factbar under a different name, you'll have to switch to a different Ethereum address. After you successfuly claim a Factbar, the website will then request that you provide an email address, which we will use to alert you when a bar is claimed from you.

An entirely separate user workflow is accessed via the "sign up" and "sign in" links at the bottom of each Factbar page. There you can establish an account that is only for editorial use: For adding and editing references, issues, and comments to Factbars. This account is unrelated to any claimant accounts you may have set up.



Developers

We encourage developers to interact directly with Factbar assets on the blockchain. Here we provide sample code for iterating over and listening for claim events, which in the contract are called appropriation events. You can use similar code to monitor other contract activity.

node.js / web3
 
// this example uses web3 1.0.0-beta.34
// note that web3 > 1.0 has made significant
// changes to the events API when compared with previous versions
var Web3 = require('web3');

// you will need to generate the contract's ABI and put it in a JSON file
// do this by getting our published contract code
// and creating the ABI file with truffle, remix, or other Solidity tool
const factBarContractJson = require('./FactbarDeed.json');

// you should pick your own back-end Ethereum node provider
// please be sure your provider does handle events
const backEndEthNodeUrl = 'https://mainnet.infura.io/YOUR-API-KEY'

// get the web3 variable
const web3 = new Web3(new Web3.providers.HttpProvider(backEndEthNodeUrl));

// get the contract instance
var contractInstance = new web3.eth.Contract(factBarContractJson.abi,
  '0x7da47CA0dE0797fFeDfEa9194cAc9A8A5d0cD0CC', {});

// now we can call the contract to get the contract's name
contractInstance.methods.name().call()
    .then(console.log);

// this our handler for appropriation (claim) events
// it will print information about the event 
// to the console
function handleEvent(event) {
    console.log(event.blockNumber)
    console.log(event.transactionHash)
    console.log(event.transactionIndex)
    console.log(event.returnValues.id)
    console.log(event.returnValues.oldOwner)
    console.log(event.returnValues.newOwner)
    console.log(event.returnValues.oldPrice)
    console.log(event.returnValues.newPrice)
    console.log(event.returnValues.transferFeeAmount)
    console.log(event.returnValues.excess)
    console.log(event.returnValues.oldOwnerPaymentAmount)
};


// let's query the blockchain for all past appropriation (claim) events
function getAllPastClaims() {
    console.log("running get all past claims")
    contractInstance.getPastEvents('Appropriation', {
            fromBlock: 0,
            toBlock: 'latest'
        }, function(error, events) {
            console.log(events);
        })
        .then(function(events) {
            _.forEach(events, function(event) {
                handleEvent(event)
            })
        });
}

// let's run the query every 15 seconds
setInterval(getAllPastClaims, 15000);

// let's also react to appropriation (claim) events immediately
// to do this, we'll need to listen to our ethereum node
// using websockets. 
const backEndEthNodeWebsocketsUrl = "wss://infura-or-some-other-provider.io/YOUR-API-KEY"
const ws_provider = backEndEthNodeWebsocketsUrl
const socketWeb3 = new Web3(new Web3.providers.WebsocketProvider(ws_provider));

// note we have to make a new contract instance
// since we are going to use it with websockets instead of http
var socketContractInstance = new socketWeb3.eth.Contract(factBarContractJson.abi,
'0x7da47CA0dE0797fFeDfEa9194cAc9A8A5d0cD0CC', {
});

// let's listen for new appropriation (claim) events
socketContractInstance.events.Appropriation({
        fromBlock: 0
    }, function(error, event) {
        console.log("new watcher event")
    })
    .on('data', function(event) {
        console.log('websocket watcher found new event')
        handleEvent(event); //
    })
    .on('changed', function(event) {
        // remove event from local database
    })
    .on('error', console.error);