Integration

To illustrate how apps can be decentralized with the Zellular Sequencer, let’s look at a basic order book created using Python with Flask for handling user orders and SQLite for data storage. This example is streamlined, focusing solely on demonstrating the practical integration with the Zellular Sequencer, and does not include the extensive features of a full-scale implementation.

Python Code for a Simple Order-Book

The complete code for the sample order book is available at this link. Below is a brief overview of the code structure:

Setting up the Environment

This section sets up the basic Flask application and the database:

from flask import Flask, request, session, jsonify
from flask_sqlalchemy import SQLAlchemy
from werkzeug.security import check_password_hash

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///orders.db'
app.config['SECRET_KEY'] = 'your_secret_key'
db = SQLAlchemy(app)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    password_hash = db.Column(db.String(120), nullable=False)

class Balance(db.Model):
    user_id = db.Column(db.Integer, db.ForeignKey('user.id'), primary_key=True)
    token = db.Column(db.String(50), primary_key=True)
    amount = db.Column(db.Float, nullable=False)

class Order(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False)
    base_token = db.Column(db.String(50), nullable=False)
    quote_token = db.Column(db.String(50), nullable=False)
    order_type = db.Column(db.String(10), nullable=False)
    quantity = db.Column(db.Float, nullable=False)
    price = db.Column(db.Float, nullable=False)
    matched = db.Column(db.Boolean, default=False, nullable=False)

@app.before_first_request
def create_tables():
    db.create_all()

User Authentication

This section adds a login route to authenticate users:

@app.route('/login', methods=['POST'])
def login():
    username = request.form['username']
    password = request.form['password']
    user = User.query.filter_by(username=username).first()
    if user and check_password_hash(user.password_hash, password):
        session['user_id'] = user.id
        return jsonify({"message": "Logged in successfully"}), 200
    return jsonify({"message": "Invalid username or password"}), 401

Order Submission

place_order adds a route to the server to enable users submitting buy and sell orders if they have logged in and have a session:

@app.route('/order', methods=['POST'])
def place_order():
    if 'user_id' not in session:
        return jsonify({"message": "Please log in"}), 401

    order_type = request.form['order_type']
    base_token = request.form['base_token']
    quote_token = request.form['quote_token']
    quantity = float(request.form['quantity'])
    price = float(request.form['price'])

    ...

Order Matching

match_order and update_balances implement the core logic of matching orders and updating users balances:

def match_order(new_order):
    # Logic to find and process matching orders
    ...


def update_balances(new_order, matched_order, trade_quantity):
    # Logic to update balances after matching orders
    ...

Applying Signature-based Authentication

To decentralize an app like the order-book using the Zellular Sequencer, start by switching to a signature-based authentication system. Here’s how to do it:

Identifying Users by their Public Keys

Since username and password are no longer needed for authentication, the User table can be eliminated. Additionally, update the user_id field in the Order and Balance table to reference the user’s public_key, which serves as the user identifier in the new version.

class Balance(db.Model):
    public_key = db.Column(db.String(500), primary_key=True)
    ...

class Order(db.Model):
    ...
    public_key = db.Column(db.String(500), nullable=False)
    ...

Authorising Users by their Signatures

Remove the login function, as session-based authentication is no longer used, and users sign every request. Add a signature parameter to the place_order function, using this signature to verify access authorization instead of relying on user sessions.

from ecdsa import VerifyingKey, SECP256k1, BadSignatureError
...

def verify_order(order):
    # Serialize the data from the form fields
    keys = ['order_type', 'base_token', 'quote_token', 'quantity', 'price']
    message = ','.join([order[key] for key in keys]).encode('utf-8')

    # Verify the signature
    try:
        public_key = base64.b64decode(order['public_key'])
        signature = base64.b64decode(order['signature'])
        vk = VerifyingKey.from_string(public_key, curve=SECP256k1)
        vk.verify(signature, message)
    except (BadSignatureError, ValueError):
        return False
    return True

@app.route('/order', methods=['POST'])
def place_order():
    if not verify_order(request.form):
        return jsonify({"message": "Invalid signature"}), 403

    ...

Sequencing orders before applying them

The next step in decentralizing the app is to send user-signed orders to the Zellular Sequencer before applying them to the database and update the database after receiving them back from the sequencer. This helps all the nodes running the app apply the requests in a consistent order. Here’s how it should be done:

Sending orders to the Sequencer

After signature verification, the place_order function uses the POST /node/{app}/batches endpoint of the Zellular Sequencer service to send the orders to the sequencer before applying them into the database.

zsequencer_url = 'http://5.161.230.186:6001/node/orderbook/batches'
...

@app.route('/order', methods=['POST'])
def place_order():
    if not verify_order(request.form):
        return jsonify({"message": "Invalid signature"}), 403

    keys = ['order_type', 'base_token', 'quote_token', 'quantity', 'price', 'signature']
    txs = [{key: request.form[key] for key in keys}]
    requests.put(zsequencer_url, json=txs)
    return { 'success': True }

Receiving sequenced orders from the sequencer

Add a thread to continuously retrieve finalized, sequenced orders and apply the same routine used in the place_order function to process these orders. Zellular SDK can be used to pull the finalized sequence of transaction batches from the Zellular network.

import zellular

def process_loop():
    verifier = zellular.Verifier("orderbook", "http://5.161.230.186:6001")
    for batch, index in verifier.batches():
        txs = json.loads(batch)
        for i, tx in enumerate(txs):
            place_order(tx)

def __place_order(order):
    if not verify_order(order):
        print("Invalid signature:", order)
        return
    ...

if __name__ == '__main__':
    Thread(target=process_loop).start()
    app.run(debug=True)

The complete code for the decentralized version of the sample order book can be accessed here. Additionally, you can view the GitHub comparison between the centralized and decentralized versions here. As demonstrated, integrating the Zellular Sequencer into your apps is straightforward and accessible for any Python developer, without requiring deep expertise in blockchain or smart contracts.