Skip to content
Paxos protocol framework
Go TLA Shell Python
Branch: master
Clone or download
Latest commit 25d3770 Dec 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin graph Mar 22, 2019
blockchain multicast to quorum Oct 5, 2018
checker client interface Nov 23, 2018
client lazy connection Jun 11, 2019
cmd ack in chain Jun 7, 2019
dynamo read from any replica May 19, 2018
epaxos reply property Apr 5, 2019
hpaxos hpaxos Jul 1, 2019
kpaxos remove comment Jun 7, 2019
m2paxos add m2paxos, remove log dir Feb 21, 2019
master optional quorum as functions Nov 25, 2018
paxos comment Jul 13, 2019
paxos_group multicast to quorum Oct 5, 2018
tla full package name etc. Dec 8, 2017
vpaxos multicast to quorum Oct 5, 2018
wankeeper multicast to quorum Oct 5, 2018
wpaxos graph Mar 22, 2019
.gitignore update logging format Apr 16, 2019
LICENSE socket + REST client Nov 8, 2017
ballot.go clean up log May 13, 2019
ballot_test.go linear checker Jan 15, 2018
benchmark.go update logging format Apr 16, 2019
benchmark_test.go flag transport Mar 12, 2019
checker_test.go Squashed commit of the following: Nov 21, 2018
client.go quorum read Apr 16, 2019
codec.go fast read May 28, 2018
codec_test.go optimise encoding Feb 20, 2018
config.go flag transport Mar 12, 2019
db.go sort id Jun 4, 2019
go.mod Init go modules Dec 7, 2019
http.go update logging format Apr 16, 2019
init.go increase http connection Mar 16, 2018
message.go value format %x Apr 18, 2019
node.go flag transport Mar 12, 2019
operation.go partition nemesis Apr 9, 2018
policy.go client interface Nov 20, 2018
policy_test.go update May 13, 2018
quorum.go add quorum all Jul 1, 2019
rate.go rate limit in total for all workers Mar 14, 2018
rate_test.go limit key generation not client Mar 15, 2018
socket.go lazy connection Jun 11, 2019
socket_test.go flag transport Mar 12, 2019
stat.go update logging format Apr 16, 2019
state_machine.go global config + transport codec Feb 16, 2018
transport.go flag transport Mar 12, 2019
transport_test.go non blocking Feb 24, 2018
util.go dynamo + hash ring Feb 23, 2018

GoDoc Go Report Card Build Status

What is Paxi?

Paxi is the framework that implements WPaxos and other Paxos protocol variants. Paxi provides most of the elements that any Paxos implementation or replication protocol needs, including network communication, state machine of a key-value store, client API and multiple types of quorum systems.

Warning: Paxi project is still under heavy development, with more features and protocols to include. Paxi API may change too.

What is WPaxos?

WPaxos is a multileader Paxos protocol that provides low-latency and high-throughput consensus across wide-area network (WAN) deployments. Unlike statically partitioned multiple Paxos deployments, WPaxos perpetually adapts to the changing access locality through object stealing. Multiple concurrent leaders coinciding in different zones steal ownership of objects from each other using phase-1 of Paxos, and then use phase-2 to commit update-requests on these objects locally until they are stolen by other leaders. To achieve fast phase-2 commits, WPaxos adopts the flexible quorums idea in a novel manner, and appoints phase-2 acceptors to be close to their respective leaders.

WPaxos (WAN Paxos) paper (first version) can be found in

What is included?



  • Benchmarking
  • Linerizability checker
  • Fault injection

How to build

  1. Install Go.
  2. Use go get command or Download Paxi source code from GitHub page.
go get
  1. Compile everything from paxi/bin folder.

After compile, Golang will generate 3 executable files under bin folder.

  • server is one replica instance.
  • client is a simple benchmark that generates read/write reqeust to servers.
  • cmd is a command line tool to test Get/Set requests.

How to run

Each executable file expects some parameters which can be seen by -help flag, e.g. ./server -help.

  1. Generate the configuration file according to the example, then start server with -config FILE_PATH option, default to "config.json" when omit.

  2. Start 9 servers with different ids in format of "ZONE_ID.NODE_ID".

./server -id 1.1 -algorithm=paxos &
./server -id 1.2 -algorithm=paxos &
./server -id 1.3 -algorithm=paxos &
./server -id 2.1 -algorithm=paxos &
./server -id 2.2 -algorithm=paxos &
./server -id 2.3 -algorithm=paxos &
./server -id 3.1 -algorithm=paxos &
./server -id 3.2 -algorithm=paxos &
./server -id 3.3 -algorithm=paxos &
  1. Start benchmarking client that connects to server ID 1.1 and benchmark parameters specified in config.json.
./client -id 1.1 -bconfig benchmark.json

When flag id is absent, client will randomly select any server for each operation.

The algorithms can also be running in simulation mode, where all nodes are running in one process and transport layer is replaced by Go channels. Check script on how to run.

How to implement algorithms in Paxi

Replication algorithm in Paxi follows the message passing model, where several message types and their handle function are registered. We use Paxos as an example for our step-by-step tutorial.

  1. Define messages, register with gob in init() function if using gob codec. As show in msg.go.

  2. Define a Replica structure embeded with paxi.Node interface.

type Replica struct {

Define handle function for each message type. For example, to handle client Request

func (r *Replica) handleRequest(m paxi.Request) {
	if *adaptive {
		if r.Paxos.IsLeader() || r.Paxos.Ballot() == 0 {
		} else {
			go r.Forward(r.Paxos.Leader(), m)
	} else {

  1. Register the messages with their handle function using Node.Register(interface{}, func()) interface in Replica constructor.

Replica use Send(to ID, msg interface{}), Broadcast(msg interface{}) functions in Node.Socket to send messages.

For data-store related functions check db.go file.

For quorum types check quorum.go file.

Client uses a simple RESTful API to submit requests. GET method with URL "http://ip:port/key" will read the value of given key. POST method with URL "http://ip:port/key" and body as the value, will write the value to key.

You can’t perform that action at this time.