YCabal Design

Posted on map[Count:January 11, 2021] in Spec · Tagged with Documentation, Proposal

sam bacha <sam@freighttrust.com> Version {0.3.0}

title = "YBackbone Cabal Introduction" date = "2021-01-11" categories = ["Spec"] tags = ["Documentation", "Proposal"] :idprefix: :idseparator: - :!example-caption: :!table-caption: :page-pagination:

Introduction and Goals

Relevant requirements and the driving forces we must consider. These include

  • underlying business goals, essential features and functional requirements for the system

  • quality goals for the architecture

  • relevant stakeholders and their expectations

Requirements Overview


Monopolizing transaction flow for arbitrage batching with miner support.


From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality. YCabal’s key result will be the enabling of gas-free transactons while also reducing arbitrage externalities.

How to decompose an application into microservices - as described below the application consists of several services. For example, bank accounts are managed by one service, money transfers by another service.

Using an event-driven architecture to achieve data consistency - rather than using traditional distributed transaction to maintain database consistency this application uses an eventually consistent, event-driven approach.
Using event sourcing to implement the event-driven architecture - the domain logic consists of Domain-Driven Design (DDD) aggregates that using event sourcing.
How event sourcing enables deployment flexibility - the application can either be deployed as a monolith or as microservices.
Using Command Query Responsibility Segregation (CQRS) - update requests (HTTP POSTs and PUTs) and view requests (HTTP GETs) are handled by separate services.

There are two services running - The Product Offering and the Product Offering Service

  • JSON RPC 2.0 Service Provider

  • Archival / Sync’d Ethereum Nodes

  • Websocket Access for end users as well as RPC

  • Message Queue management

  • API spec for miners and end users to utilize

Quality Goals


The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.


You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged …


A table with quality goals and concrete scenarios, ordered by priorities



Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

  • have to come up with decisions about the system or its development


All parties involved in development of the YCabal or affected by this system.


Table with role names, person names, and their expectations with respect to the architecture and its documentation. Some Roles are 'undefined' (i.e. Community engagement / liasion )

Role/Name Contact Expectations

_Front End UI/UX



_Protocol Engineering _



_Backend Operations


Yearn Finance

Community Liasion


SushiSwap (undefined)




title = "Architecture Constraints" date = "2021-01-11" categories = ["Spec", "Design"] tags = ["Documentation", "Architecture", "Design"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

Architecture Constraints


Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process.

Constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.


A Allow List / White List of approved contract interactions only. All transactions not involving predefined approved contracts in a 'registry' are dropped > Need clarification for this part as it relates to the incoming transaction handler/load balancer

User Authentication must be minimal, if any.

Network State and Concensus

A successful reward scheme has to posses several properties. First, it has to incentivize information propagation and no duplication. That is, it will be in a node’s best interest to distribute the transaction to all its children without duplicating itself, as well as never duplicating when it authorizes. Second, at the end of the distribution phase most of the nodes have to be aware of the transaction.

Changing the order of transactions impacts state. This would substantially increase the effective confirmation time leading to instability and a higher rate of reverted transactions.

General Constraints
  • Downtime. If for any reason node has to be taken down for maintenance there will be no node left. There will be downtime when for example there is a need to upgrade a version of ParityGeth.

  • Falling out of sync. Parity is great but not flaweless. It may occasionally fall out of sync for various reasons. Having multiple nodes allows us to temporarly re-route traffic from nodes which have fallen behind and query nodes which are in-sync.

  • Distributing load. There is only a certain level of requests/second on json-rpc that a single Parity node can sustain. Json-rpc interface becomes slow over this level and Parity node falls out of sync. This is especially important if node(s) is used from web dapp interface and number, and you can observe daily spikes in user engagement.


Data written to kernel buffers using the write(2) system call (or equivalent) that gives us data safety against process failure.

Data committed to the disk using the fsync(2) system call (or equivalent) that gives us, virtually, data safety against complete system failure like a power outage. We actually know that there is no guarantee because of the possible disk controller caching, but we’ll not consider this aspect because this is an invariant among all the common database systems. Also system administrators often can use specialized tools in order to control the exact behavior of the physical device.

  • Persistance Procedures at the system call level

1: The client sends a write command to the database (data is in client’s memory). 2: The database receives the write (data is in server’s memory). 3: The database calls the system call that writes the data on disk (data is in the kernel’s buffer). 4: The operating system transfers the write buffer to the disk controller (data is in the disk cache). 5: The disk controller actually writes the data

Note on POSIX/Linux Kernel will take at least 30 seconds to write. This means that if there is a failure, all the data written in the latest 30 seconds can get potentially lost.

title = "System Scope and Context" date = "2021-01-11" categories = ["Spec", "Design"] tags = ["Documentation", "System", "Context"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

System Scope and Context


System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).


The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.


Various options:

  • Context diagrams

  • Lists of communication partners and their interfaces.

Business Context


Specification of all communication partners (users, IT-systems, …​) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.


All stakeholders should understand which data are exchanged with the environment of the system.


All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.

Alternatively (or additionally) you can use a table. The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.

<Diagram or Table>

<optionally: Explanation of external domain interfaces>

Technical Context


Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation with I/O uses which channel.


Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.


E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output.

<Diagram or Table>

<optionally: Explanation of technical interfaces>

<Mapping Input/Output to Channels>

title = "Solution Strategy" date = "2021-01-11" categories = ["Spec", "Design"] tags = ["Documentation", "Strategy", "Solution"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

Solution Strategy


Fundamental decisions and solution strategies, that shape the system’s architecture.

  • technology decisions

  • decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern

  • decisions on how to achieve key quality goals

  • relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.


These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules.


KDB+ for Database Technology Redis for Network Management Terraform Docker for Hypervisor/Container DynamoDB/PostGres for Service/Logging Persistance

=== RPC Layer

A list of URL of out Parity node should be kept in DynamoDB. There is also a special URL called leader that points to Infura/AlchemyAPI

` eth_getBlockNumber` should be run on each of the nodes from the list every 60 seconds. The result is compared with the leader. For the node to be deemed healthy it has to respond and be no more than 10 blocks behind Infura. The health status of each node is saved to DynamoDB/PostGres

Change of health status of any node triggers regeneration of proxy config. Proxy config is simply an nginx .conf file that configures an upstream service which load-balances load between our nodes.

If none of our nodes is healthy the generated config proxies all requests to [This is Open] as a fallback. the config file is uploaded to S3 bucket.

  • Uploading config file to S3 bucket triggers update of ECS Service that runs nginx container with with generated config. Standard GitDevOps

  • Monitoring nodes The upside of using AWS services is that they come with default metrics out-of-box

Central Dogma (the 'black box')

the core guts of the backbone network

Writing atomically to a database and a message broker can add unnecessary code complexity

Message Broker unavailability would force decisions about each microservice’s trade-offs between availability and consistency

+ Solution Separate the concern of managing inter-service communication by using an event-driven Message Relay

  • RedisGears can be used to easily implement the Transactional Outbox pattern by listening for events within

Redis databases and relaying event notifications (write-behind pattern) to a Message Broker for downstream inter-service communication Redis-based microservices would avoid code complexity, concerns with Message Broker unavailability, and performance overhead


Challenge Observability, tracing, and auditing of Choreography-based Sagas is difficult across a decoupled chain of microservices


  • Event Sourcing implies recording every microservice’s state change as an immutable event; acting as a source of truth

  • It is composed of a Message Broker and Event Store

  • Based on the or dered sequence of events persisted in the event store, a microservice can replay/rebuild its system state by reprocessing recorded events at any time

  • Redis Streams is an immutable in-memory append-only log data structure perfectly suited and used as an Event Store

  • Visualizing a stream of events can provide real-time observability of the system’s state and instant recovery/replay


Load Balancer - HAProxy or alt?s

System Recovery

Incident Resposne Planning

Legal Questionsz - minimal

title = "Building blocks and foundational layer" date = "2021-01-11" categories = ["Spec", "Design"] tags = ["Documentation", "Architecture", "Design"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

Building Block View


The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, datas structures, …​) as well as their dependencies (relationships, associations, …​)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.


Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.


The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Hierarchy of building blocks

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

Whitebox Overall System

Here you describe the decomposition of the overall system using the following white box template. It contains

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

<Overview Diagram>


<text explanation>

Contained Building Blocks

<Description of contained building block (black boxes)>

Important Interfaces

<Description of important interfaces>

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name Responsibility

<black box 1>


<black box 2>


If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

<Name black box 1>

Here you describe <black box 1> according the the following black box template:

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks



<(Optional) Quality/Performance Characteristics>

<(Optional) Directory/File Location>

<(Optional) Fulfilled Requirements>

<(optional) Open Issues/Problems/Risks>

<Name black box 2>

<black box template>

<Name black box n>

<black box template>

<Name interface 1>


<Name interface m>

Level 2

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

White Box <building block 1>

…​describes the internal structure of building block 1.

<white box template>

White Box <building block 2>

<white box template>


White Box <building block m>

<white box template>

Level 3

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

White Box <_building block x.1_>

Specifies the internal structure of building block x.1.

<white box template>

White Box <_building block x.2_>

<white box template>

White Box <_building block y.1_>

<white box template>

title = "Runtime and Execution" date = "2021-01-11" categories = ["Spec", "Operations"] tags = ["Documentation", "Production", "Runtime"] :idprefix: :idseparator: - :!example-caption: :!table-caption: :page-pagination:

Runtime View


The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

  • important use cases or features: how do building blocks execute them?

  • interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

  • operation and administration: launch, start-up, stop

  • error and exception scenarios

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.


You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).


There are many notations for describing scenarios, e.g.

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

<Runtime Scenario 1>

  • <insert runtime diagram or textual description of the scenario>

  • <insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>

<Runtime Scenario 2>


<Runtime Scenario n>

title = "Deployment and Failover" date = "2021-01-11" categories = ["Spec", "Operations"] tags = ["Documentation", "Production", "Recovery"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

Deployment View


The deployment view describes:

  1. the technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and

  2. the mapping of (software) building blocks to that infrastructure elements.

Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.

Especially document the deployment view when your software is executed as distributed system with more then one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture those elements of the infrastructure that are needed to show the deployment of your building blocks. Hardware architects can go beyond that and describe the infrastructure to any level of detail they need to capture.


Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. Therefore, you need to know the infrastructure.


Maybe the highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section you will zoom into this black box using additional deployment diagrams:

  • UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.

  • When your (hardware) stakeholders prefer other kinds of diagrams rather than the deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

Infrastructure Level 1

Describe (usually in a combination of diagrams, tables, and text):

  • the distribution of your system to multiple locations, environments, computers, processors, .. as well as the physical connections between them

  • important justification or motivation for this deployment structure

  • Quality and/or performance features of the infrastructure

  • the mapping of software artifacts to elements of the infrastructure

For multiple environments or alternative deployments please copy that section of arc42 for all relevant environments.

<Overview Diagram>


<explanation in text form>

Quality and/or Performance Features

<explanation in text form>

Mapping of Building Blocks to Infrastructure

<description of the mapping>

Infrastructure Level 2

Here you can include the internal structure of (some) infrastructure elements from level 1.

Please copy the structure from level 1 for each selected element.

<Infrastructure Element 1>

<diagram + explanation>

<Infrastructure Element 2>

<diagram + explanation>


<Infrastructure Element n>

<diagram + explanation>

title = "Interdependent and Cross-cutting" date = "2021-01-11" categories = ["Spec", "Operations"] tags = ["Documentation", "Production", "Runtime"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

Cross-cutting Concepts


This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as

  • domain models

  • architecture patterns or design patterns

  • rules for using specific technology

  • principal, often technical decisions of overall decisions

  • implementation rules


Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieve inner qualities of your system.

Some of these concepts cannot be assigned to individual building blocks (e.g. security or safety). This is the place in the template that we provided for a cohesive specification of such concepts.


The form can be varied:

  • concept papers with any kind of structure

  • cross-cutting model excerpts or scenarios using notations of the architecture views

  • sample implementations, especially for technical concepts

  • reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)


A potential (but not mandatory) structure for this section could be:

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Under-the-hood"

  • development concepts

  • operational concepts

Note: it might be difficult to assign individual concepts to one specific topic on this list.

Possible topics for crosscutting concepts

<Concept 1>


<Concept 2>



<Concept n>


title = "Design Decisions and ADR's" date = "2021-01-11" categories = ["Spec", "Design"] tags = ["Documentation", "Architecture", "Design"] :idprefix: :idseparator: - :!example-caption: :!table-caption:

Design Decisions


Important, expensive, large scale or risky architecture decisions including rationals. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block).

Avoid redundancy. Refer to section 4, where you already captured the most important decisions of your architecture.


Stakeholders of your system should be able to comprehend and retrace your decisions.


Various options:

  • List or table, ordered by importance and consequences or:

  • more detailed in form of separate sections per decision

  • ADR (architecture decision record) for every important decision

  1. Limit The Number of Clusters

  2. librdkafka based Client see llink:https://cwiki.apache.org/confluence/display/KAFKA/Clients

  3. Avro as data format*

  4. Model Events Not Commands

  5. Zookeeper?

title = "Quality Requirements" date = "2021-01-11" categories = ["Spec"] tags = ["Documentation", "Requirements"] :idprefix: :idseparator: - :!example-caption: :!table-caption: :page-pagination:

Quality Requirements


This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.


Since quality requirements will have a lot of influence on architectural decisions you should know for every stakeholder what is really important to them, concrete and measurable.

Quality Tree


The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.


The tree structure with priorities provides an overview for a sometimes large number of quality requirements.


The quality tree is a high-level overview of the quality goals and requirements:

  • tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

  • a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

Quality Scenarios


Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

  • Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.

  • Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.


Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.


Tabular or free form text.

title = "Risks and Technical Debts" date = "2021-01-11" categories = ["Spec"] tags = ["Documentation", "Risks", "Engineering"] :idprefix: :idseparator: - :!example-caption: :!table-caption: :page-pagination:

Risks and Technical Debts


A list of identified technical risks or technical debts, ordered by priority


“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.


List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

title = "Glossary" date = "2021-01-11" categories = ["Spec", "Glossary"] tags = ["Documentation", "Appendix", "Reference"] :idprefix: :idseparator: - :!example-caption: :!table-caption:



The most important domain and technical terms that your stakeholders use when discussing the system.

You can also see the glossary as source for translations if you work in multi-language teams.


You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms


A table with columns <Term> and <Definition>.

Potentially more columns in case you need translations.

Block producers // Transaction Inclusion Block proposers are most analogous to traditional blockchain miners. It is critical that they preserve the censorship resistance that we see in blockchains today. However, instead of proposing blocks with an ordering, they simply propose a set of transactions to eventually be included before N blocks.

Sequencers // Transaction Ordering Sequencers are elected by a smart contract managed auction run by the block producers called the MEVA contract. This auction assigns the right to sequence the last N transactions. If, within a timeout the sequencer has not submitted an ordering which is included by block proposers, a new sequencer is elected.

e depth of a node is the number of nodes on the path from the root of the node’s tree (the seed) to the node. Let n=t*(d^(H)-1)/(d-1) be be the total number of nodes.

Term Definition

Geth Transaction Pool