Factom API support

Easing the transition from Factom to Accumulate

Introduction

Factom was originally deployed in 2015. Its API has been used on many projects and by many exchanges. This paper looks at the API as it exists and details what we can do to make the Accumulate API match to the extent possible. This paper outlines what we could do to bridge Factom to Accumulate. This will not be fully implemented by Activation, and we may not ever entirely implement the calls described in this document.

Factom API

The API is designed for outside applications to process transactions and interact with the Factom federated servers. The listening port can be configured and runs on 8088 by default. All these APIs use JSON-RPC, a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a handful of data types and commands.

They can be invoked in your terminal as:

curl -X POST --data-binary '{"jsonrpc": "2.0", "id": 0, "method": "METHOD_HERE", "params": {"PARAM_1":"PARAM_DATA_1"}}' -H 'content-type:text/plain;' http://localhost:8088/v2 

The output will also be JSON.

We will go through the Factom API as it exists today and detail what we believe we can provide on Accumulate.

Factom API to Accumulate API mappings

ablock-by-height -- Not supported

ack -- Only requires the transaction hash, however.

Returns Jason for entry and factoid transactions.

Accumulate has no commit transactions, so ack cannot return them Accumulate does have entries, so ack can return the entry reveals Requires a transaction date and a block date for factoid transactions

admin-block -- Not supported

chain-head -- Returns the first entry of a given data account

commit-entry

Commit-entry creates the signature for signing an entry and puts it in the wallet database keyed by the entry hash. Nothing is submitted to Accumulate at this time.

Reveal-entry creates the entry transaction and combines the entry transaction with the signature provided by commit-entry. The transaction is then submitted to Accumulate.

current-minute --

Returns

• Leaderheight -- DVN height /600 (10 minute cadence)

• DirectoryBlockHeight -- DVN height /600 (10 minute cadence)

• Minute -- (DVN height / 60) % 10 (minutes within a 10 minute cadence)

• Currentblockstarttime -- Timestamp of the first DVN minor block in a 10 minute cadence

• Currentminutestarttime -- First DVN minor block of the current minute in a 10 minute cadence

• Directoryblockinseconds -- 600

• Stalldetected -- returns true if Accumulate detects a stall of the node

• Faulttimeout -- returns 0

• Roundtimeout -- returns 0

• dblock-by-height -- Not supported

• directory-block -- Not supported

• directory-block-head -- Not supported

• ecblock-by-height -- Not supported

• Entry -- Given an entry hash, return the entry in JSON form

• Entry-ack -- Deprecated; not supported

• Entry-block -- Not supported

• Entry-credit-balance -- The address specified must be a url to a key page. Returns the credit balance

• Entrycredit-block -- Not supported.

Note that minute times are approximate. Even in Factom, minute times could stretch or compress depending upon how the various leaders synced, or if a leader had to be replaced.

• Entry-credit-rate -- Returns the price of credit in ACME (fixed point)

• Factoid-ack -- Deprecated; not supported

• Factoid-balance -- Returns the number of ACME at a given Lite Data Account (which can be specified with the FA address). If a URL is provided instead of an address, factoid-balance can return the number of ACME at an ADI Token Account.

• Factoid-block -- Not Supported

• Factoid-submit -- Submit a binary transaction as long as it is properly encoded and signed to Accumulate.

• Fblock-by-height Not Supported

• Heights -- Returns the last confirmed Directory Validator Block for all heights

• Multiple-ec-balances -- all addresses must be key page urls. The call is broken up into individual calls for each key page url. Currentheight and lastsavedheight are both the current height of the DVN

• Multiple-fct-balances -- all addresses must be token account urls. The call is broken up into individual calls for each token account. Currentheight and lastsavedheight are both the current height of the DVN

• Pending-entries -- returns 0. Accumulate does not have the commit/reveal exchange with applications and users, so writes do not pend like they do in Factom

• Pending-transactions -- return any pending transactions in the signature chain for a particular transaction account. No changes to the JSON format are required. The “fees” entry on each transaction will be 0. (This is because Accumulate does not require the inputs to be more than the outputs to pay fees but rather uses credits on the signing key page to pay fees.)

• Properties -- will return

{ "jsonrpc": "2.0", "id": 0, "result": { "factomdversion": "0.5.0.0", "factomdapiversion": "3.0" } }

• Raw-data -- Retrieve an entry or transaction in raw format. Data is a hex encoded string.

• Receipt -- Retrieve a receipt for a transaction hash or entry hash. This will be in Accumulate format

• Reveal-chain

Reveal-chain is implemented as a Reveal-entry but creates a new Lite Data Account as well. This may be difficult to implement without a new call to create the Lite Data Account

• Reveal-entry

Commit-entry creates the signature for signing an entry and puts it in the wallet database keyed by the entry hash. Nothing is submitted to Accumulate at this time. Reveal-entry creates the entry transaction and combines the entry transaction with the signature provided by commit-entry. The transaction is then submitted to Accumulate.

• Send-raw -- Supported

Sending a raw transaction allows transactions to be created off-line in secure environments and submitted to the network on a “hot” platform. Also useful for testing and debugging. Any transaction created for the Accumulate protocol should be available in raw form for disconnected construction.

Transaction -- Supported

Caveats include:

• No transaction block,

• directory block can be reported Directoryblockheight will be reported as the DNV minor block height / 600

Factom Wallet API

• Add-ec-output -- Not supported

• Add-fee Noop: we do not charge fees in the same way Factom did)

• Add-input Only allow the addition of one input

• Add-output Supported

• Address Creates a lite token account address

• All-addresses Returns all the key books and token accounts managed by the wallet

• Compose-chain -- Not supported

• Compose-entry -- Not supported

• Compose-transaction Marshals the current transaction into a hex encoded string. Compose-transaction fails if the current transaction is incomplete and/or has not been signed. Returns a hex string that can be inputted into the factomd API factoid-submit to be sent to the network.

• Delete-transaction Delete the current transaction under constructed

• Generate-ec-address -- Not Supported

• Generate-factoid-address Create a lite token account address

• Get-height -- Not supported

• Import-addresses Import Factoid address secret keys into the wallet

• Import-koinify Import a Koinify crowd sale address into the wallet.

• New-transaction Create a new transaction to be built using other calls

• Properties Retrieve current properties of the factom-walletd, including the wallet and wallet API versions

• Sign-transaction Signs the transaction under construction

• Sub-fee Noop. it does nothing because we do not pay fees on Accumulate by a difference between inputs and outputs

• Tmp-transactions Lists all current working transactions in the wallet. None of these transactions have been sent

• Transactions (Retrieving) Return transactions using a range, by TxID, by Address. All Transactions are not supported

• Wallet-backup Return the wallet seed and all addresses in the wallet for backup and offline storage

• Wallet-balances Return balances of all addresses in the wallet