You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Ethan Buchman 8374785c1d update glide, grpc to v4 8 years ago
client client: safe error handling 8 years ago
cmd codegangsta => urfave 8 years ago
example fix tests 8 years ago
server fixes from review 8 years ago
tests test: more verbosity 8 years ago
testutil Add testutil; Clean gov return codes 9 years ago
types update glide, grpc to v4 8 years ago
.gitignore Add .pyc to gitignore; Fix js example 9 years ago
LICENSE Change license format 9 years ago
Makefile update glide, grpc to v4 8 years ago
README.md update glide, grpc to v4 8 years ago
circle.yml add glide 8 years ago
glide.lock update glide, grpc to v4 8 years ago
glide.yaml add glide 8 years ago

README.md

Tendermint Socket Protocol (TMSP)

CircleCI

Blockchains are a system for creating shared multi-master application state. TMSP is a socket protocol enabling a blockchain consensus engine, running in one process, to manage a blockchain application state, running in another.

For more information on TMSP, motivations, and tutorials, please visit our blog post.

Other implementations:

Contents

This repository holds a number of important pieces:

  • types/types.proto

    • the protobuf file defining TMSP message types, and the optional grpc interface.
      • to build, run make protoc
    • see protoc --help and the grpc docs for examples and details of other languages
  • golang implementation of TMSP client and server

    • two implementations:
      • asynchronous, ordered message passing over unix or tcp;
        • messages are serialized using protobuf and length prefixed
      • grpc
    • TendermintCore runs a client, and the application runs a server
  • cmd/tmsp-cli

    • command line tool wrapping the client for probing/testing a TMSP application
    • use tmsp-cli --version to get the TMSP version
  • examples:

    • the cmd/counter application, which illustrates nonce checking in txs
    • the cmd/dummy application, which illustrates a simple key-value merkle tree

Message format

Since this is a streaming protocol, all messages are encoded with a length-prefix followed by the message encoded in Protobuf3. Protobuf3 doesn't have an official length-prefix standard, so we use our own. The first byte represents the length of the big-endian encoded length.

For example, if the Protobuf3 encoded TMSP message is 0xDEADBEEF (4 bytes), the length-prefixed message is 0x0104DEADBEEF. If the Protobuf3 encoded TMSP message is 65535 bytes long, the length-prefixed message would be like 0x02FFFF....

Note this prefixing does not apply for grpc.

Message types

TMSP requests/responses are simple Protobuf messages. Check out the schema file.

AppendTx

  • Arguments:
    • Data ([]byte): The request transaction bytes
  • Returns:
    • Code (uint32): Response code
    • Data ([]byte): Result bytes, if any
    • Log (string): Debug or error message
  • Usage:
    Append and run a transaction. If the transaction is valid, returns CodeType.OK

CheckTx

  • Arguments:
    • Data ([]byte): The request transaction bytes
  • Returns:
    • Code (uint32): Response code
    • Data ([]byte): Result bytes, if any
    • Log (string): Debug or error message
  • Usage:
    Validate a transaction. This message should not mutate the state. Transactions are first run through CheckTx before broadcast to peers in the mempool layer. You can make CheckTx semi-stateful and clear the state upon Commit or BeginBlock, to allow for dependent sequences of transactions in the same block.

Commit

  • Returns:
    • Data ([]byte): The Merkle root hash
    • Log (string): Debug or error message
  • Usage:
    Return a Merkle root hash of the application state.

Query

  • Arguments:
    • Data ([]byte): The query request bytes
  • Returns:
    • Code (uint32): Response code
    • Data ([]byte): The query response bytes
    • Log (string): Debug or error message

Flush

  • Usage:
    Flush the response queue. Applications that implement types.Application need not implement this message -- it's handled by the project.

Info

  • Returns:
    • Data ([]byte): The info bytes
  • Usage:
    Return information about the application state. Application specific.

SetOption

  • Arguments:
    • Key (string): Key to set
    • Value (string): Value to set for key
  • Returns:
    • Log (string): Debug or error message
  • Usage:
    Set application options. E.g. Key="mode", Value="mempool" for a mempool connection, or Key="mode", Value="consensus" for a consensus connection. Other options are application specific.

InitChain

  • Arguments:
    • Validators ([]Validator): Initial genesis validators
  • Usage:
    Called once upon genesis

BeginBlock

  • Arguments:
    • Height (uint64): The block height that is starting
  • Usage:
    Signals the beginning of a new block. Called prior to any AppendTxs.

EndBlock

  • Arguments:
    • Height (uint64): The block height that ended
  • Returns:
    • Validators ([]Validator): Changed validators with new voting powers (0 to remove)
  • Usage:
    Signals the end of a block. Called prior to each Commit after all transactions

Changelog

Mar 26h, 2016
  • Introduce BeginBlock
Mar 6th, 2016
  • Added InitChain, EndBlock
Feb 14th, 2016
  • s/GetHash/Commit/g
  • Document Protobuf request/response fields
Jan 23th, 2016
  • Added CheckTx/Query TMSP message types
  • Added Result/Log fields to AppendTx/CheckTx/SetOption
  • Removed Listener messages
  • Removed Code from ResponseSetOption and ResponseGetHash
  • Made examples BigEndian
Jan 12th, 2016
  • Added "RetCodeBadNonce = 0x06" return code
Jan 8th, 2016
  • Tendermint/TMSP now comes to consensus on the order first before AppendTx.