tim

Trust in Motion (TiM)

TiM is Tradle's SDK that provides real-time messaging with an option for messages to be sealed on the blockchain. Mesages can be plain or structured messages. TiM is designed to work on mobiles, desktops and servers. Having one code base is important to minimize security reviews.

TiM is designed to work with intermittent connections, common on mobile devices. For that it keeps an internal log of all actions and events, and resumes operations as soon as network connection is restored.

TiM's operations are covered by a patent. The tatent is filed only for defensive purposes, so you are welcome to use it in your open source projects.

this module is used by Tradle
this npm module's name was graciously donated by Sean Robertson

TiM provides a higher level API to a number of low level Tradle components. A UI is developed separately. Currently we focus on React Native based UI (on iOS, the Android version of TiM is in works), see the preview video and the screenshots.

Prior to React Native, we developed the UI for Tim as a Chrome App, see this Identity verification video and a work completion video. And prior to that we developed a very cool node-webkit-based craigslist on-chain concept app on TiM, but it is very much behind now. We plan work on desktop version of TiM soon, let us know if you are interested in these environments and we will prioritize this work for you.

TiM uses the following Tradle components:

zlorp

Zlorp is just the core chat module. It uses OTR for secure sessions (later will add support for Axolotl, used in TextSecure and Pond). Peer discovery today is done via bittorrent-dht. But DHT's regular announce messages leak IP/Port, so we will see if we can use BEP 44 to encrypt them. Zlorp provides UDP NAT traversal (firewall hole-punching), and a direct connection via rUDP (later via uTP). We plan to further investigate anonymous packet delivery, possibly via I2P (TOR does not support UDP).

bitkeeper-js

Bitkeeper module uses WebTorrent for storing and ensuring replication of arbitrary files. In Tradle, bitkeeper is used to store the original (encrypted) versions of on-chain objects (structured messages).

chained-obj

Chained-obj is object builder and parser. Currently uses multipart to store arbitrary JSON data + attachments. These objects are later encrypted and put on-chain.

bitjoe-js (to be renamed to: chainwriter)

A collection of requests that can be used to put an object "on chain": encrypt an object for its recipients, store/seed it from a bitkeeper node and put private links on blockchain.

tradle-constants

Wait for it...a bunch of constants

tradle-utils

A small set of crypto and torrent-related functions used by a number of Tradle components

Identity

Identity is wrapper around an OpenName-compatible Identity schema. Used for building/parsing/validating identity objects.

kiki

kiki Wrappers for DSA, EC, Bitcoin and other keys to provide a common API for signing/verifying/importing/exporting.

chainloader

Parses bitcoin transactions, attempts to process embedded links, loads intermediate files and original files from a bitkeeper node, decrypts and returns files and metadata. Implements stream.Transform.

simple-wallet

One-key common blockchain based wallet.

tradle-tx-data

For building/parsing bitcoin-transaction-embedded data

tradle-verifier

Plugin-based verifier for on-chain objects. Implements several default plugins:
Signature Check
Identity verification
Previous Version verification

Exports

Datalog

This module uses a datalog, a log-based database of experienced activity that you can write to and use to bootstrap your own databases from.

Messaging API

Details to follow

Usage

Identity Identifiers

When you want to communicate with someone else on the network, you need to identify them uniquely. You can identify them by a fingerprint of one of their public keys, a public key string, or by their identity's root hash:

// if this is the identity of your friend Bill:
{
  "_t": "tradle.Identity",
  "pubkeys": [
    {
      "fingerprint": "mvDNdZFbCCmnAPCBmLY91LnfKWoMH39Q2c",
      "networkName": "testnet",
      "purpose": "payment",
      "type": "bitcoin",
      "value": "03a45ede4be12a812e6e2ef1650ecbd8900152b1c6e3fe47f427ee5d9323759fe3"
    }
  ]
}

// the following are equivalent identifiers for Bill:
{
  fingerprint: 'mvDNdZFbCCmnAPCBmLY91LnfKWoMH39Q2c' 
}

{
  _r: 'whatever the infoHash of the above JSON object is'
}

Initialization

var path = require('path')
var levelup = require('levelup')
var leveldown = require('leveldown') // or asyncstorage-down or whatever you're using
var Blockchain = require('cb-blockr') // use tradle/cb-blockr fork
var Identity = require('@tradle/identity').Identity
var defaultKeySet = require('@tradle/identity').defaultKeySet
var Keeper = require('@tradle/http-keeper')
var Tim = require('tim')

// Setup components:
var networkName = 'testnet'
var blockchain = new Blockchain(networkName)
//   Create an identity or load an existing one (see tradle/identity readme):
var jack = new Identity()
var jackPrivKeys = defaultKeySet({ networkName: networkName })
jackPrivKeys.forEach(jack.addKey, jack)
//   to export private keys:    jackPrivKeys.forEach(k => k.exportPrivate())
//   to export public identity: jack.toJSON()

var myDir = path.join(process.env.HOME, 'myTradle')
//   content-address storage for your encrypted messages
var keeper = new Keeper({
  db: levelup(path.resolve(myDir, 'keeper'), { db: leveldown, valueEncoding: 'binary' }),
  fallbacks: ['http://tradle.io:25667']
})

// the API
var tim = new Tim({
  pathPrefix: path.join(myDir, 'tim'), // for playing nice with other levelup-based storage
  leveldown: leveldown,
  networkName: networkName,
  identity: jack,
  keys: jackPrivKeys, 
  keeper: keeper,
  blockchain: blockchain,
  // optional
  syncInterval: 600000 // how often to bother cb-blockr
})

// define a _send function that will determine the transport to use
// to deliver a message to a particular recipient
tim._send = function (recipientRootHash, msg, recipientInfo) {
  // return a Promise that resolves when the message is delivered
  // e.g. tim2.receiveMsg(msg, { _r: recipientRootHash })
  // 
  // tradle has several network-adapters for message delivery that you can use here. 
  // They are all open source on Github:
  //   tradle/zlorp - pure p2p messaging with OTR over UDP
  //   tradle/http-client & tradle/http-server
  //   tradle/ws-client & tradle/ws-relay - OTR over websockets
  //   
  //   latest, but unstable:
  //   tradle/sendy, tradle/sendy-otr
  //     reliable delivery over network of choice. 
  //     websockets implementation: tradle/sendy-ws, tradle/sendy-ws-relay
}

tim.send({
  to: [{ fingerprint: 'one of their fingerprints' }],
  msg: { hey: 'ho' },
  deliver: true,  
  chain: false
})

Publishing your identity

tim.publishMyIdentity()

Sending messages

tim.send({
  msg: Object|Buffer,
  // record message on chain
  chain: true,
  // send message p2p
  deliver: true,
  to: [
    identityIdentitifier // see Identity Identifiers
  ]
})

Sharing existing messages (via the blockchain)

var constants = require('@tradle/constants')
var curHash = '...' // the infoHash of the existing message, see tradle/utils `getStorageKeyFor`
var shareOpts = {
  // record message on chain
  chain: true,
  // send message p2p
  deliver: true,
  to: [
    identityIdentitifier // see Identity Identifiers  
  ]
}

shareOpts[constants.CUR_HASH] = curHash
tim.share(shareOpts)

Publishing on chain

Same as sending a message, but use tim.publish instead of tim.send

tim.publish({
  msg: Object|Buffer,
  to: [
    identityIdentitifier // see Identity Identifiers
  ]
})

Messages

var db = tim.messages() // read-only levelup instance

// e.g.
db.createValueStream()
  .on('data', function (err, msg) {
    // issue tim.lookupObject(msg) to get decrypted metadata and contents
  })

Identities (loaded from chain)

var db = tim.identities() // read-only levelup instance

// e.g.
db.createValueStream()
  .on('data', function (err, identityJSON) {
    // do something with "identity"
    // console.log('yo', identityJSON.name.firstName)
  })

// additional convenience methods
db.byRootHash(identityRootHash, callback)
db.byFingerprint(fingerprint, callback)

Events

tim.on('ready', function () {...})

Tim's ready to do stuff

tim.on('chained', function (info) {...}

An object was successfully put on chain¹

tim.on('unchained', function (info) {...}

An object was read off chain¹

tim.on('message', function (info) {...}

A message was received peer-to-peer¹

tim.on('sent', function (info) {...}

A message was delivered¹

tim.on('resolved', function (info) {...}

An object was both received peer-to-peer and read from the chain¹

¹ Note: does NOT contain chained-object contents. Use tim.lookupObject(info) to obtain those.